Condividi tramite

Ricerca documenti (API REST ricerca intelligenza artificiale di Azure)

  • Articolo

Una richiesta di query è destinata alla raccolta documenti di un singolo indice in un servizio di ricerca. Include parametri che definiscono i criteri di corrispondenza e i parametri che formano la risposta. A partire dalla versione dell'API 2021-04-30-Preview, è anche possibile usare un alias di indice per indirizzare un determinato indice anziché usare il nome dell'indice stesso.

È possibile usare GET o POST. I parametri di query vengono specificati nella stringa di query per le richieste GET e nel corpo della richiesta per le richieste POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]

Se si usa POST, aggiungere l'azione "search" come parametro URI.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

Quando viene chiamato con GET, la lunghezza dell'URL della richiesta non può superare 8 KB. Questa lunghezza è in genere sufficiente per la maggior parte delle applicazioni. Tuttavia, alcune applicazioni producono query di grandi dimensioni, in particolare quando vengono usate espressioni di filtro OData. Per queste applicazioni, HTTP POST è una scelta migliore perché consente filtri più grandi di GET.

Con POST il fattore limitante è il numero di clausole in un filtro, non la dimensione della stringa di filtro non elaborata, poiché il limite delle dimensioni della richiesta per POST è di circa 16 MB. Anche se il limite di dimensioni della richiesta POST è elevato, le espressioni di filtro non possono essere arbitrariamente complesse. Per altre informazioni sulle limitazioni di complessità dei filtri, vedere Sintassi dell'espressione OData per Ricerca di intelligenza artificiale di Azure.

Parametri dell'URI

Parametro Descrizione
[nome servizio] Obbligatorio. Impostare questo valore sul nome univoco definito dall'utente del servizio di ricerca.
[nome indice]/docs Obbligatorio. Specifica la raccolta documenti di un indice denominato.
[parametri di query] I parametri di query vengono specificati nell'URI per le richieste GET e nel corpo della richiesta per le richieste POST.
api-version Obbligatorio. La versione stabile corrente è api-version=2020-06-30. Per altre versioni, vedere Versioni API . Per le query, la versione api viene sempre specificata come parametro URI per GET e POST.

Raccomandazioni per la codifica URL

Ricordarsi di codificare parametri di query specifici con codifica URL quando si chiama direttamente l'API REST GET. Per un'operazione Documenti di ricerca , la codifica URL potrebbe essere necessaria per i parametri di query seguenti:

  • ricerca
  • $filter
  • facet
  • highlightPreTag
  • highlightPostTag

La codifica URL è consigliata solo per i singoli parametri. Se inavvertitamente si codifica nell'URL l'intera stringa di query (tutto quanto segue ?), le richieste si interromperanno.

La codifica dell'URL è necessaria solo quando si chiama direttamente l'API REST con GET. Nessuna codifica URL è necessaria quando si usa POST o quando si usa la libreria client di Ricerca intelligenza artificiale di Azure .NET, che gestisce la codifica per l'utente.

Intestazioni richiesta

La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.

Campi Descrizione
Content-Type Obbligatorio. Impostare questa opzione su "application/json"
api-key Facoltativo se si usano ruoli di Azure e viene fornito un token di connessione nella richiesta, altrimenti è necessaria una chiave. Una chiave API è una stringa univoca generata dal sistema che autentica la richiesta al servizio di ricerca. Le richieste di query sulla raccolta documenti possono specificare una chiave di amministrazione o una chiave di query come chiave API. La chiave di query viene usata per operazioni di sola lettura nella raccolta documenti. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione delle chiavi .

Corpo della richiesta

Per GET: nessuno.

Per POST:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Continuazione di risposte di ricerca parziali

A volte Ricerca intelligenza artificiale di Azure non può restituire tutti i risultati richiesti in una singola risposta di ricerca. Ciò può verificarsi per diversi motivi, ad esempio quando la query richiede troppi documenti senza specificare $top o specificando un valore troppo grande per $top. In questi casi, Ricerca intelligenza artificiale di Azure include l'annotazione @odata.nextLink nel corpo della risposta e anche @search.nextPageParameters se si tratta di una richiesta POST. È possibile usare i valori di queste annotazioni per formulare un'altra richiesta di ricerca per ottenere la parte successiva della risposta di ricerca. Tale operazione è denominata continuazione della richiesta di ricerca originale e le annotazioni vengono in genere chiamate token di continuazione. Per informazioni dettagliate sulla sintassi di queste annotazioni e dove vengono visualizzati nel corpo della risposta, vedere l'esempio seguente in Risposta.

I motivi per cui Ricerca intelligenza artificiale di Azure potrebbe restituire token di continuazione specifici dell'implementazione e soggetti a modifiche. I client affidabili devono essere sempre pronti a gestire i casi in cui viene restituito un numero di documenti inferiore al previsto e in cui viene incluso un token di continuazione per continuare il recupero dei documenti. Si noti inoltre che per poter continuare è necessario usare lo stesso metodo HTTP della richiesta originale. Se ad esempio si invia una richiesta GET, anche le richieste di continuazione inviate devono usare il metodo GET e lo stesso vale per il metodo POST.

Nota

Lo scopo di @odata.nextLink e @search.nextPageParameters consiste nel proteggere il servizio dalle query che richiedono troppi risultati, non fornire un meccanismo generale per il paging. Se si desidera visualizzare i risultati, usare $top e $skip insieme. Ad esempio, se si vogliono pagine di dimensioni 10, la prima richiesta deve avere e , la seconda richiesta deve avere $top=10 e $skip=0$skip=10, la terza richiesta deve avere $top=10$top=10 e $skip=20, e così via.

Parametri di query

Una query accetta diversi parametri nell'URL quando viene chiamato con GET e come proprietà JSON nel corpo della richiesta quando viene chiamato con POST. La sintassi per alcuni parametri è leggermente diversa tra GET e POST. Queste differenze vengono annotate come applicabili di seguito.

Nome Tipo Descrizione
api-version string Obbligatorio. Versione dell'API REST usata per la richiesta. Per un elenco di versioni supportate, vedere Versioni API. Per questa operazione, la versione api viene specificata come parametro URI indipendentemente dal fatto che si chiamaNo Documenti di ricerca con GET o POST.
$count boolean facoltativo. I valori validi sono "true" o "false". Impostazione predefinita "false". Quando viene chiamato con POST, questo parametro è denominato conteggio anziché $count. Specifica se recuperare il conteggio totale dei risultati. Si tratta del conteggio di tutti i documenti che corrispondono ai parametri di ricerca e $filter, ignorando $top e $skip. L'impostazione di questo valore su "true" può ridurre le prestazioni. Il conteggio è accurato se l'indice è stabile, ma sotto o sovrasterrà eventuali documenti aggiunti attivamente, aggiornati o eliminati. Se si vuole ottenere solo il conteggio senza documenti, è possibile usare $top=0.
facet o facet string Facoltativa. Campo da cui eseguire il facet, in cui il campo viene attribuito come "facetable". Quando viene chiamato con GET, facet è un campo (facet: field1). Quando viene chiamato con POST, questo parametro è denominato facets anziché facet e viene specificato come matrice (facets: [field1, field2, field3]). La stringa può contenere parametri per personalizzare il facet, espresso come coppie nome-valore delimitate da virgole.

I parametri validi sono "count", "sort", "values", "interval" e "timeoffset".

"count" è il numero massimo di termini di facet; il valore predefinito è 10. Non esiste alcun limite massimo per il numero di termini, ma i valori più elevati riducono le prestazioni, soprattutto se il campo con facet contiene un numero elevato di termini univoci. Ad esempio, "facet=category,count:5" ottiene le prime cinque categorie nei risultati del facet. Se il parametro count è minore del numero di termini univoci, i risultati potrebbero non essere accurati. Ciò è dovuto al modo in cui le query di esplorazione in base a facet vengono distribuite nelle partizioni. È possibile impostare il conteggio su zero o su un valore maggiore o uguale al numero di valori univoci nel campo facetable per ottenere un conteggio accurato in tutte le partizioni. Il compromesso è maggiore latenza.

"sort" può essere impostato su "count", "-count", "value", "-value". Usare il conteggio per ordinare in base al conteggio. Usare -count per ordinare in base al conteggio. Usare il valore per ordinare l'ordinamento crescente in base al valore. Utilizzare -value per ordinare in base al valore decrescente (ad esempio, "facet=category,count:3,sort:count" ottiene le prime tre categorie in facet generano un ordine decrescente in base al numero di documenti con ogni nome della città). Se le prime tre categorie sono Budget, Motel e Lusso e Budget ha 5 hit, Motel ha 6 e Lusso ha 4, i bucket sono nell'ordine Motel, Budget, Lusso. Per -value, "facet=rating,sort:-value" produce bucket per tutte le possibili classificazioni, in ordine decrescente in base al valore (ad esempio, se le classificazioni sono da 1 a 5, i bucket vengono ordinati 5, 4, 3, 2, 1, indipendentemente dal numero di documenti corrispondenti a ogni classificazione).

"values" può impostare su valori numerici delimitati da pipe o Edm.DateTimeOffset che specificano un set dinamico di valori di voce di facet, ad esempio "facet=baseRate,values:10 | 20" produce tre bucket: uno per il tasso di base 0 fino a ma non incluso 10, uno per 10 fino a ma non compreso 20 e uno per 20 e superiore. Una stringa "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" produce due bucket: uno per gli alberghi rinnovati prima del febbraio 2010 e uno per gli alberghi rinnovati il 1° febbraio 2010 o versioni successive. I valori devono essere elencati in sequenza, in ordine crescente per ottenere i risultati previsti.

"intervallo" è un intervallo intero maggiore di 0 per numeri, ore, ora, giorno, settimana, mese, trimestre, anno per i valori dell'ora di data. Ad esempio, "facet=baseRate,interval:100" produce bucket in base agli intervalli di frequenza di base di dimensioni 100. Se le tariffe di base sono tutte comprese tra $ 60 e $ 600, saranno presenti bucket per 0-100, 100-200, 200-300, 300-400, 400-500 e 500-600. La stringa "facet=lastRenovationDate,interval:year" produce un bucket per ogni anno quando gli hotel sono stati rinnovati.

"timeoffset" può essere impostato su ([+-]hh:mm, [+-]hhmm o [+-]hhh). Se usato, il parametro timeoffset deve essere combinato con l'opzione intervallo e solo quando applicato a un campo di tipo Edm.DateTimeOffset. Il valore specifica la differenza dell'ora UTC di cui tenere conto nell'impostazione dei limiti di ora. Ad esempio: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" usa il limite giornaliero che inizia alle 01:00:00 UTC (mezzanotte nel fuso orario di destinazione).

il conteggio e l'ordinamento possono essere combinati nella stessa specifica del facet, ma non possono essere combinati con intervalli o valori e valori e intervallo non possono essere combinati insieme.

I facet di intervallo nell'ora di data vengono calcolati in base all'ora UTC se timeoffset non è specificato. Ad esempio: per "facet=lastRenovationDate,interval:day", il limite del giorno inizia alle 00:00:00 UTC.
$filter string Facoltativa. Espressione di ricerca strutturata nella sintassi standard di OData. È possibile usare solo campi filtrabili in un filtro. Quando si chiama con POST, questo parametro è denominato filtro anziché $filter. Per informazioni dettagliate sul sottoinsieme della grammatica dell'espressione OData supportata da Ricerca di intelligenza artificiale di Azure, vedere Sintassi dell'espressione OData.
highlight string Facoltativa. Insieme di nomi di campo delimitati da virgole usati per evidenziare i riscontri. Solo i campi ricercabili possono essere usati per l'evidenziazione di hit. Per impostazione predefinita, Ricerca intelligenza artificiale di Azure restituisce fino a 5 evidenziazioni per campo. Il limite è configurabile per ogni campo aggiungendo "-<max # di evidenziazioni>" seguendo il nome del campo. Ad esempio, "highlight=title-3,description-10" restituisce fino a 3 hit evidenziati dal campo titolo e fino a 10 hit dal campo descrizione. Il numero massimo di evidenziazioni deve essere un intero compreso tra 1 e 1000 inclusi.
highlightPostTag string Facoltativa. Il valore predefinito è "</em>". Tag stringa che aggiunge al termine evidenziato. Deve essere impostato con highlightPreTag. I caratteri riservati nell'URL devono essere codificati in percentuale (ad esempio, %23 anziché #).
highlightPreTag string Facoltativa. Il valore predefinito è "</em>". Tag stringa che prependa il termine evidenziato. Deve essere impostato con highlightPostTag. I caratteri riservati nell'URL devono essere codificati in percentuale (ad esempio, %23 anziché #).
minimumCoverage numero intero facoltativo. I valori validi sono un numero compreso tra 0 e 100, che indica la percentuale dell'indice che deve essere disponibile per il servizio della query prima che possa essere segnalata come esito positivo. Il valore predefinito è "100".

Il cento% di copertura significa che tutte le partizioni hanno risposto alla richiesta (né problemi di integrità del servizio né attività di manutenzione ridotte). Nell'impostazione predefinita, la copertura completa restituisce il codice di stato HTTP 503.

L'abbassamento di minimumCoverage può essere utile se si verificano 503 errori e si vuole aumentare la probabilità di esito positivo della query, in particolare per i servizi configurati per una replica. Se si imposta minimumCoverage e Search ha esito positivo, restituisce HTTP 200 e include un @search.coverage valore nella risposta che indica la percentuale dell'indice incluso nella query. In questo scenario, non tutti i documenti corrispondenti devono essere presenti nei risultati della ricerca, ma se la disponibilità della ricerca è più importante del richiamo, la riduzione della copertura può essere una strategia di mitigazione valida.
$orderby string Facoltativa. Elenco di espressioni delimitate da virgole in base alle quali ordinare i risultati. Quando viene chiamato con POST, questo parametro è denominato orderby anziché $orderby. Ogni espressione può essere un nome di campo o una chiamata alla funzione geo.distance(). Ogni espressione può essere seguita da "asc" per indicare l'crescente e "desc" per indicare la desc decrescente. Se nel campo di ordinamento sono presenti valori Null, i valori Null vengono visualizzati prima in ordine crescente e l'ultimo in ordine decrescente. Per impostazione predefinita, l'ordinamento è crescente. Le situazioni di parità di priorità vengono risolte in base ai punteggi di corrispondenza dei documenti. Se non viene specificata alcuna $orderby, l'ordine di ordinamento predefinito è decrescente in base al punteggio di corrispondenza del documento. È previsto un limite di 32 clausole per $orderby.
queryType string Facoltativa. I valori validi sono "simple" o "full". Il valore predefinito è 'simple'.

"simple" interpreta le stringhe di query usando la sintassi di query semplice che consente simboli come +, * e "". Le query vengono valutate in tutti i campi ricercabili (o i campi indicati in searchFields) in ogni documento per impostazione predefinita.

"full" interpreta le stringhe di query usando la sintassi completa della query Lucene che consente ricerche specifiche e ponderate per il campo. La ricerca di intervalli nel linguaggio di query Lucene non è supportata a favore di $filter, che offre funzionalità simili.
assegnazione dei punteggiParameter string Facoltativa. Indica i valori per ogni parametro definito in una funzione di assegnazione dei punteggi (ad esempio referencePointParameter) usando il formato "name-value1,value2,..." Quando viene chiamato con POST, questo parametro è denominato scoringParameters anziché punteggioParameter. Si specifica anche come matrice JSON di stringhe in cui ogni stringa è una coppia nome-valori separata.

Per i profili di assegnazione dei punteggi che includono una funzione, separare la funzione dall'elenco di input con un - carattere. Ad esempio, una funzione denominata "mylocation" sarebbe "&scoringParameter=mylocation--122.2,44.8". Il primo trattino separa il nome della funzione dall'elenco di valori, mentre il secondo trattino fa parte del primo valore (longitudine in questo esempio).

Per i parametri di assegnazione dei punteggi, ad esempio per il boosting dei tag che possono contenere virgole, è possibile eseguire l'escape di qualsiasi valore nell'elenco usando virgolette singole. Se i valori stessi contengono virgolette singole è possibile eseguire l'escape raddoppiandole. Si supponga di avere un parametro di boosting tag denominato "mytag" e di voler aumentare i valori dei tag "Hello, O'Brien" e "Smith", l'opzione della stringa di query sarà quindi "&scoringParameter=mytag-'Hello, O''Brien',Smith". Le virgolette sono necessarie solo per i valori che contengono virgole.
scoringProfile string Facoltativa. Nome di un profilo di punteggio da usare per la valutazione di punteggi di corrispondenza per i documenti corrispondenti, in modo da ordinare i risultati.
scoringStatistics string Facoltativa. I valori validi sono "local" o "global". Il valore predefinito è "local". Specificare se calcolare le statistiche di assegnazione dei punteggi, ad esempio la frequenza del documento, globalmente (in tutte le partizioni) per un punteggio più coerente o in locale (nella partizione corrente) per una latenza inferiore. Vedere Statistiche di assegnazione dei punteggi in Ricerca di intelligenza artificiale di Azure. Le statistiche di assegnazione dei punteggi verranno sempre calcolate in locale per i termini che usano la ricerca fuzzy ('~')..
ricerca string Facoltativa. Testo da cercare. Tutti i campi ricercabili vengono cercati per impostazione predefinita, a meno che non venga specificato searchFields. Nell'indice il testo in un campo ricercabile viene tokenizzato, in modo che più termini possano essere separati da spazi vuoti, ad esempio 'search=hello world'. Per trovare corrispondenze con qualsiasi termine, usare *, che può essere utile per le query con filtro booleano. L'omissione di questo parametro equivale a impostarlo su *. Per informazioni specifiche sulla sintassi di ricerca, vedere sintassi di query semplice .

I risultati possono talvolta risultare sorprendenti quando si eseguono query su campi ricercabili. Il tokenizer include logica per la gestione di casi comuni nel testo inglese, ad esempio apostrofi, virgole nei numeri e così via. Ad esempio, 'search=123,456' corrisponderà a un singolo termine '123.456' anziché ai singoli termini '123' e '456', poiché le virgole vengono usate come separatori di migliaia per numeri di grandi dimensioni in inglese. Per questo motivo, è consigliabile usare spazi vuoti anziché punteggiatura per separare i termini nel parametro di ricerca.
searchMode string Facoltativa. I valori validi sono "any" o "all" I valori predefiniti sono "any". Specifica se è necessario trovare una corrispondenza con uno o tutti i termini di ricerca per includere il documento nel numero delle corrispondenze.
searchFields string Facoltativa. Elenco di nomi di campo delimitati da virgole in cui cercare il testo specificato. I campi di destinazione devono essere contrassegnati come ricercabili nello schema dell'indice.
$select string Facoltativa. Elenco di campi delimitati da virgole da includere nel set di risultati. In questa clausola è possibile includere solo i campi contrassegnati come recuperabili. Se non è specificato o se è impostato su *, nella proiezione vengono inclusi tutti i campi contrassegnati come recuperabili nello schema. Quando viene chiamato con POST, questo parametro viene denominato select anziché $select.
sessionID string Facoltativa. L'uso di sessionId consente di migliorare la coerenza del punteggio di pertinenza per i servizi di ricerca con più repliche. Nelle configurazioni con più repliche possono esserci lievi differenze tra i punteggi di pertinenza dei singoli documenti per la stessa query. Quando viene specificato un ID sessione, il servizio esegue il massimo sforzo per instradare una determinata richiesta alla stessa replica per tale sessione. Tenere presente che il riutilizzo degli stessi valori ID sessione può interferire ripetutamente con il bilanciamento del carico delle richieste tra le repliche e influire negativamente sulle prestazioni del servizio di ricerca. Il valore usato come sessionId non può iniziare con un carattere '_'. Se un servizio non ha repliche, questo parametro non ha alcun effetto sulle prestazioni o sulla coerenza dei punteggi.
$skip numero intero facoltativo. Numero di risultati della ricerca da ignorare. Quando viene chiamato con POST, questo parametro viene denominato skip anziché $skip. Questo valore non può essere maggiore di 100.000. Se è necessario analizzare i documenti in sequenza, ma non è possibile usare a causa di questa limitazione, è consigliabile usare $skip $orderby in un campo con valori univoci per ogni documento nell'indice ,ad esempio la chiave del documento, e $filter con una query di intervallo.
$top numero intero facoltativo. Numero di risultati della ricerca da recuperare. Il valore predefinito è 50. Quando viene chiamato con POST, questo parametro viene denominato top anziché $top. Se si specifica un valore maggiore di 1000 e sono presenti più di 1000 risultati, verranno restituiti solo i primi 1000 risultati, insieme a un collegamento alla pagina successiva dei risultati (vedere @odata.nextLink l'esempio seguente).

Ricerca di intelligenza artificiale di Azure usa il paging lato server per impedire alle query di recuperare troppi documenti contemporaneamente. La dimensione predefinita della pagina è 50, mentre la dimensione massima della pagina è 1000. Ciò significa che per impostazione predefinita i documenti di ricerca restituiscono al massimo 50 risultati se non si specifica $top. Se sono presenti più di 50 risultati, la risposta include informazioni per recuperare la pagina successiva di al massimo 50 risultati (vedere "@odata.nextLink" e "@search.nextPageParameters" negli esempi seguenti. Analogamente, se si specifica un valore maggiore di 1000 per $top e sono presenti più di 1000 risultati, vengono restituiti solo i primi 1000 risultati, insieme alle informazioni per recuperare la pagina successiva di al massimo 1000 risultati.

Risposta

Se la risposta ha esito positivo, viene restituito il codice di stato 200 OK.

  {
    "@odata.count": # (if `$count`=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Esempio

Per altri esempi, vedere Sintassi delle espressioni OData per Ricerca di intelligenza artificiale di Azure.

  1. Eseguire una ricerca nell'indice ordinato in modo decrescente in base alla data:

    GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

  2. In una ricerca in base a facet eseguire ricerche nell'indice e recuperare facet per categorie, classificazioni, tag ed elementi con baseRate in intervalli specifici.

    GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }

    Si noti che l'ultimo facet si trova in un sottocampo. I facet contano il documento padre (Hotels) e non i documenti secondari intermedi (Rooms), quindi la risposta determina il numero di hotel che hanno camere in ogni bucket di prezzo.

  3. Usando un filtro, restringere il risultato precedente della query in base a facet dopo che l'utente seleziona Valutazione 3 e categoria "Motel".

    GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

  4. In una ricerca con facet, impostare un limite massimo per i termini univoci restituiti in una query. Il valore predefinito è 10, ma è possibile aumentare o ridurre questo valore usando il parametro count nell'attributo facet. Questo esempio restituisce facet per city, con un limite di 5.

    GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }

  5. Eseguire una ricerca nell'indice entro campi specifici (ad esempio un campo relativo alla lingua):

    GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

  6. Eseguire una ricerca nell'indice in più campi. Ad esempio, è possibile archiviare ed eseguire query nei campi disponibili per la ricerca in più lingue, all'interno dello stesso indice. Se le descrizioni in inglese e francese coesistono nello stesso documento, è possibile restituire uno o tutti nei risultati della query:

    GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }

    È possibile eseguire query solo su un indice alla volta. Non creare più indici per ogni linguaggio, a meno che non si prevede di eseguire una query una alla volta.

  7. Paging : consente di ottenere la prima pagina di elementi (le dimensioni della pagina sono 10):

    GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

  8. Paging - Ottenere la seconda pagina di elementi (le dimensioni della pagina sono 10):

    GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

  9. Recuperare un set specifico di campi:

    GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

  10. Recuperare i documenti corrispondenti a un'espressione di filtro specifica:

    GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

  11. Eseguire una ricerca nell'indice e restituire frammenti con evidenziazioni di riscontri:

    GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

  12. Eseguire una ricerca nell'indice e restituire documenti ordinati dal più vicino al più lontano rispetto a una posizione di riferimento:

    GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

  13. Cercare l'indice presupponendo che sia presente un profilo di punteggio denominato "geo" con due funzioni di assegnazione dei punteggi della distanza, una che definisce un parametro denominato "currentLocation" e uno che definisce un parametro denominato "lastLocation". Nell'esempio seguente "currentLocation" ha un delimitatore di un singolo trattino (-). Segue le coordinate di longitudine e latitudine, dove longitudine è un valore negativo.

    GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }

  14. Trovare documenti nell'indice usando una sintassi di query semplice. Questa query restituisce gli hotel i cui campi disponibili per la ricerca contengono i termini "comfort" e "location" ma non "motel":

    Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }

    Suggerimento

    Con searchMode=all viene eseguito l'override dell'impostazione predefinita di searchMode=any e si assicura che -motel indichi "AND NOT" invece di "OR NOT". Senza searchMode=all, si ottiene "OR NOT" che espande i risultati della ricerca anziché limitarli e questo può essere poco intuitivo per alcuni utenti.

  15. Trovare documenti nell'indice usando la sintassi di query Lucene. Questa query restituisce gli hotel in cui il campo categoria contiene il termine "budget" e tutti i campi disponibili per la ricerca contengono la frase "recently renovated". I documenti contenenti la frase "recently renovated" avranno una posizione superiore nella classifica, come risultato del valore di incremento dell'importanza di un termine (3)

    GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}

  16. Trovare i documenti nell'indice, garantendo al tempo stesso un punteggio coerente rispetto a una latenza inferiore. Questa query calcola le frequenze dei documenti nell'intero indice e fa il massimo sforzo per la destinazione della stessa replica per tutte le query all'interno della stessa "sessione", che consente di generare una classificazione stabile e riproducibile.

    GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30

    POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }

Vedi anche