Komplettera automatiskt (REST API för Azure AI Search)

Artikel
03/05/2024

API:et komplettera automatiskt slutför en delvis skriven frågeinmatning med befintliga termer i sökindexet för användning i en sekundär fråga. Om frågeindata till exempel är "medic"returnerar "medicare"API:et Komplettera automatiskt , "medicaid", "medicine" om dessa termer finns i indexet. Internt söker sökmotorn efter matchande termer i fält som har en förslagsvisare konfigurerad.

HTTPS krävs för tjänstbegäranden. Begäran om automatisk komplettering kan konstrueras med hjälp av GET- eller POST-metoderna.

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

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

När det anropas med GET får längden på begärande-URL:en inte överstiga 8 kB. Den här längden räcker vanligtvis för de flesta program. Vissa program skapar dock mycket stora frågor, särskilt när OData-filteruttryck används. För dessa program är HTTP POST ett bättre alternativ eftersom det tillåter större filter än GET.

Med POST är antalet satser i ett filter den begränsande faktorn, inte storleken på den råa filtersträngen eftersom storleksgränsen för begäran för POST är cirka 16 MB. Även om storleksgränsen för POST-begäran är mycket stor kan filteruttryck inte vara godtyckligt komplexa. Mer information om begränsningar för filterkomplexitet finns i OData-uttryckssyntax för Azure AI Search.

URI-parametrar

Parameter	Beskrivning
[tjänstnamn]	Krävs. Ange det unika, användardefinierade namnet på söktjänsten.
[indexnamn]/dokument	Krävs. Anger dokumentsamlingen för ett namngivet index.
api-version	Krävs. En lista över versioner som stöds finns i API-versioner . För frågor anges api-versionen alltid som en URI-parameter för både GET och POST.

Rekommendationer för URL-kodning

Kom ihåg att URL-koda specifika frågeparametrar när du anropar GET REST API direkt. För automatisk komplettering kan URL-kodning vara nödvändigt för följande frågeparametrar:

sök
$filter
highlightPreTag
highlightPostTag

URL-kodning rekommenderas endast för enskilda parametrar. Om du oavsiktligt URL-kodar hela frågesträngen (allt efter ?), avbryts begäranden.

Dessutom är URL-kodning endast nödvändigt när du anropar REST API direkt med GET. Ingen URL-kodning krävs när du använder POST, eller när du använder Azure AI Search .NET-klientbiblioteket, som hanterar kodning åt dig.

Rubriker för begäran

I följande tabell beskrivs nödvändiga och valfria begärandehuvuden.

Fält	Description
Content-Type	Krävs. Ange detta till `application/json`
api-key	Valfritt om du använder Azure-roller och en ägartoken anges på begäran, annars krävs en nyckel. Frågebegäranden mot `docs` samlingen kan ange antingen en administratörsnyckel eller en frågenyckel som `api-key`. Frågenyckeln används för skrivskyddade åtgärder i en samling indexdokument. Mer information finns i Ansluta till Azure AI Search med nyckelautentisering .

Begärandetext

För GET: Ingen.

För POST:

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "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),
  "search": "partial_search_input",  
  "searchFields": "field_name_1, field_name_2, ...",
  "suggesterName": "suggester_name",  
  "top": # (default 5)  
}

Frågeparametrar

En fråga accepterar flera parametrar på URL:en när den anropas med GET och som JSON-egenskaper i begärandetexten när den anropas med POST. Syntaxen för vissa parametrar skiljer sig något mellan GET och POST. Dessa skillnader anges enligt vad som är tillämpligt nedan.

Namn	Typ	Description
api-version	sträng	Krävs. Version av REST-API:et som används för begäran. En lista över versioner som stöds finns i API-versionshantering. För den här åtgärden anges api-versionen som en URI-parameter oavsett om du anropar Komplettera automatiskt med GET eller POST.
autocompleteMode	sträng	Valfritt. Standardvärdet är oneTerm. Giltiga värden är oneTerm, twoTerms, oneTermWithContext. oneTerm returnerar en enda term. Om frågan har två termer slutförs bara den sista termen. Med tanke på `"washington medic"`kan svaret till exempel vara något av följande enkla termer: `"medicaid"`, `"medicare"`, `"medicine"`. twoTerms matchar tvåtermsfraser i indexet. Med tanke på `"medic"`kan svaret till exempel vara `"medicare coverage"`, eller `"medical assistant"`. I många fall returneras de enskilda termerna `"medicare"` eller `"medical"` inte eftersom tvåtermsfraser som matchar har företräde. oneTermWithContext slutför den sista termen i en fråga med två eller flera termer, där de två sista termerna är en fras som finns i indexet. Med tanke på `"washington medic"`kan svaret till exempel vara `"washington medicaid"`, `"washington medical"`.
$filter	sträng	Valfritt. Ett strukturerat sökuttryck i OData-standardsyntaxen som filtrerar de dokument som övervägs för att producera de färdiga termförslagen. Filteruttrycken "search.ismatch" och "search.ismatchscoring*" stöds inte i API:et Komplettera automatiskt. Endast filterbara fält kan användas i ett filter. När den här parametern anropas med POST får den namnet filter i stället för $filter. Se OData-uttryckssyntax för Azure AI Search för mer information om delmängden av OData-uttrycks grammatiken som stöds av Azure AI Search.
Fuzzy	boolean	Valfritt. Standardvärdet är falskt. När värdet är true hittar det här API:et förslag även om det finns ett ersatt eller saknat tecken i söktexten ⁽¹⁾. Detta ger en bättre upplevelse i vissa scenarier, men det kommer till en prestandakostnad eftersom fuzzy förslag sökningar är långsammare och förbrukar mer resurser.
highlightPostTag	sträng	Valfritt. Standardvärdet är en tom sträng. En strängtagg som lägger till den markerade termen. Måste anges med highlightPreTag. Reserverade tecken i URL:en måste vara procentkodade (till exempel %23 i stället för #). När de anropas med GET måste de reserverade tecknen i URL:en vara procentkodade (till exempel %23 i stället för #).
highlightPreTag	sträng	Valfritt. Standardvärdet är en tom sträng. En strängtagg som förbereder till den markerade termen. Måste anges med highlightPostTag. När de anropas med GET måste de reserverade tecknen i URL:en vara procentkodade (till exempel %23 i stället för #).
minimumCoverage	heltal	Valfritt. Standardvärdet är 80. Ett tal mellan 0 och 100 som anger procentandelen av indexet som måste vara tillgängligt för att betjäna frågan innan den kan rapporteras som en framgång. Standardvärdet återspeglar en bias mot hastighet och effektivitet över full täckning. Om du minskar täckningen begränsas frågeexpansionen, vilket gör att resultaten kan komma tillbaka snabbare. Det gör också att frågan kan lyckas med partiell indextillgänglighet, även om en shard svarar långsamt eller inte är tillgänglig på grund av problem med tjänstens hälsotillstånd eller indexunderhåll. Oavsett värdet för minimumCoverage måste den procentandelen av indexet vara tillgängligt eller så returnerar Autocomplete HTTP-statuskod 503. Om automatisk komplettering lyckas på lägstaCoverage-nivå returnerar den HTTP 200 och innehåller ett @search.coverage värde i svaret som anger procentandelen av indexet som var tillgängligt när frågan hanterades. Att sänka det här värdet kan vara användbart om det uppstår 503 fel. Annars kan du överväga att höja värdet om svaret ger otillräckliga matchningar.
sök	sträng	Krävs. Texten att söka efter. Söktexten som ska slutföras. Måste vara minst 1 tecken och högst 100 tecken. Den får inte innehålla operatorer, frågesyntax eller citerade fraser.
searchFields	sträng	Valfritt. Listan över kommaavgränsade fältnamn för att söka efter den angivna söktexten. Målfält måste anges i definitionen Förslagsgivare i indexet.
suggesterName	sträng	Krävs. Namnet på förslagsverktyget som anges i samlingen Förslagsgivare som ingår i indexdefinitionen. En förslagsställare avgör vilka fält som genomsöks efter föreslagna frågetermer.
$top	heltal	Valfritt. Standardvärdet är 5. Antalet kompletterade förslag som ska hämtas automatiskt. Värdet måste vara ett tal mellan 1 och 100. När den här parametern anropas med POST får den namnet top i stället för $top.

(1) Begränsningar för fuzzy i Komplettera automatiskt:

För det första är redigeringsavståndet begränsat till bara en teckenskillnad per token till skillnad från fuzzy-parametern i sökningen. Att begränsa redigeringsavståndet till ett tecken innebär att inte alla kandidatmatchningar hittas, men taket är nödvändigt för att säkerställa en acceptabel prestandanivå.

För det andra sker fuzzy-steget efter den partiella tokenexpansionen och endast termer från samma indexshard beaktas för fuzzy-matchningar. Den här begränsningen ökar prestandan för API:et för automatisk komplettering genom att eliminera aggregeringen av fuzzy-matchningar över alla shards. Den här begränsningen blir mindre märkbar eftersom fler termer läggs till i indexet, vilket resulterar i liknande termdistribution för varje shard. När termerna fördelas jämnt är fuzzy-matchningar inom en shard en bra uppskattning av fuzzy-matchningar i hela indexet. Resultaten kan dock vara sämre om indexet har färre termer, till exempel i ett test- eller prototypindex, vilket resulterar i en ojämn representation över shards. Mer information om hur index delas in i shards finns i partitions- och replikkombinationer.

Svarsåtgärder

Statuskod: "200 OK" returneras för ett lyckat svar.

Svarsnyttolasten har två egenskaper.

Egenskap	Beskrivning
"text"	Den slutförda termen eller frasen
"queryPlusText"	De första frågeindata plus den slutförda termen eller frasen

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

Exempel

Exempel 1: Hämta tre förslag för automatisk komplettering där de partiella sökindata är 'washington medic' i standardläge (oneTerm):

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}

Svar:

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}

Exempel 2: Hämta tre förslag på automatisk komplettering där de partiella sökindata är 'washington medic' och autocompleteMode=twoTerms:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}