Suggerimenti (API REST di Ricerca intelligenza artificiale di Azure)

Una richiesta di suggerimenti è una query di ricerca come tipo che cerca i valori corrispondenti nei campi in grado di suggerire e restituisce documenti che contengono una corrispondenza. Ad esempio, se si abilitano i suggerimenti in un campo città , digitando "sea" vengono generati documenti contenenti "Seattle", "Sea Tac" e "Sea" (tutti i nomi di città effettivi) per tale campo.

La risposta è un contenuto di un documento corrispondente più la chiave del documento. A differenza del completamento automatico, che restituisce un termine o una frase completata utilizzata in una query secondaria, questa richiesta restituisce informazioni che vengono risolte in documenti effettivi. Se i termini o le frasi corrispondenti sono identici tra documenti, il contenuto corrispondente viene ripetuto. Per migliorare la struttura dei risultati, è consigliabile usare il $select filtro per restituire campi aggiuntivi che forniscono più differenziazione e contesto.

Per le richieste del servizio, è necessario usare il protocollo HTTPS. La richiesta Suggest può essere costruita usando i metodi GET o POST.

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

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

A differenza di una richiesta di ricerca documenti , è possibile associare una chiamata Suggerimenti all'input da tastiera, mentre una chiamata di ricerca potrebbe essere associata a un evento Click.

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 molto grandi, in particolare quando vengono usate espressioni di filtro OData. Per queste applicazioni, HTTP POST è una scelta migliore perché consente filtri più grandi rispetto a 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 della dimensione della richiesta POST è molto grande, le espressioni di filtro non possono essere arbitrariamente complesse. Per altre informazioni sulle limitazioni di complessità dei filtri, vedere Sintassi delle espressioni OData per Ricerca per intelligenza artificiale di Azure.

Parametri dell'URI

Raccomandazioni per la codifica URL

Ricordarsi di codificare i parametri di query specifici della codifica URL quando si chiama direttamente l'API REST GET. Per le operazioni Suggestions sono inclusi i parametri seguenti:

• ricerca
• $filter
• 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. Non è necessaria alcuna codifica URL quando si chiama Suggestions usando POST o quando si usa la libreria client .NET di Ricerca intelligenza artificiale di Azure gestisce automaticamente la codifica url.

Intestazioni richiesta

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

Corpo della richiesta

Per GET: nessuno.

Per POST:

{  
      "filter": "odata_filter_expression",  
      "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
      "suggesterName": "suggester_name",  
      "top": # (default 5)  
}  

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 sono indicate come applicabile di seguito.

Risposta

Codice di stato: "200 OK" viene restituito per una risposta corretta.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}  

Se per recuperare i campi viene usata l'opzione di proiezione, tali campi vengono inclusi in ogni elemento della matrice:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}  

Esempio

Recuperare 5 suggerimenti per cui l'input di ricerca parziale è "lux":

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30 

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }  

Si noti che suggesterName è obbligatorio in un'operazione Suggestions.

Vedi anche

• Aggiungere suggerimenti a un indice
• Aggiungere suggerimenti o completamento automatico a un'applicazione
• Codici di stato HTTP