Förslag (REST API för Azure AI Search)
En förslagsbegäran är en sök-som-du-typ-fråga som söker efter matchande värden i förslagsmedvetna fält och returnerar dokument som innehåller en matchning. Om du till exempel aktiverar förslag på ett stadsfält skapar "sea" dokument som innehåller "Seattle", "Sea Tac" och "Seaside" (alla faktiska stadsnamn) för fältet.
Svaret är ett innehåll från ett matchande dokument plus dokumentnyckeln. Till skillnad från Komplettera automatiskt, som returnerar en slutförd term eller fras som används i en sekundär fråga, returnerar den här begäran information som matchar faktiska dokument. Om matchande termer eller fraser är identiska mellan dokument upprepas det matchande innehållet. Om du vill förbättra resultatstrukturen kan du använda $select filtret för att returnera ytterligare fält som ger mer differentiering och kontext.
HTTPS krävs för tjänstbegäranden. Föreslå begäran kan konstrueras med get- eller POST-metoderna.
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]
I motsats till en begäran om sökdokument kan du binda ett förslagsanrop till tangentbordsinmatning, medan ett sökanrop kan vara bundet till en klickhändelse.
När den anropas med GET får längden på begärande-URL:en inte överskrida 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 begränsningsfaktorn, inte storleken på råfiltersträngen eftersom storleksgränsen för begäran för POST är cirka 16 MB. Även om storleksgränsen för POST-begäranden ä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. Den aktuella stabila versionen är api-version=2020-06-30. Fler versioner 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 förslagsåtgärder omfattar detta:
- 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:et direkt med GET. Ingen URL-kodning krävs när du anropar förslag med POST, eller när du använder Azure AI Search .NET-klientbiblioteket hanterar URL-kodning åt dig.
Rubriker för begäran
I följande tabell beskrivs de obligatoriska och valfria begärandehuvudena.
| 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 i begäran, annars krävs en nyckel. En API-nyckel är en unik, systemgenererad sträng som autentiserar begäran till söktjänsten. Frågebegäranden mot dokumentsamlingen kan ange antingen en administratörsnyckel eller frågenyckel som API-nyckel. Frågenyckeln används för skrivskyddade åtgärder mot dokumentsamlingen. Mer information finns i Ansluta till Azure AI Search med nyckelautentisering . |
Begärandetext
För GET: Ingen.
För 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)
}
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-versioner. För den här åtgärden anges api-versionen som en frågeparameter i URL:en oavsett om du anropar API:et med GET eller POST. |
| $filter | sträng | Valfritt. Ett uttryck som filtrerar de dokument som övervägs för förslag. Endast filterbara fält kan användas i ett filter. Filteruttrycken "search.ismatch" och "search.ismatchscoring*" stöds inte i API:et För automatisk komplettering. 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-uttryckets grammatik 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. Redigeringsavståndet är 1 per frågesträng. Om frågesträngen är flera termer kan det bara finnas ett tecken som saknas, extra, ersätts eller transponeras i hela strängen. Att aktivera fuzzy-matchning kan vara en bättre upplevelse i vissa scenarier, men det medför en prestandakostnad, eftersom fuzzy-förslagssö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 i 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 det 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 #). |
| $orderby | sträng | Valfritt. En lista över kommaavgränsade uttryck som resultatet ska sorteras efter. Varje uttryck kan vara antingen ett fältnamn eller ett anrop till geo.distance() funktionen. Varje uttryck kan följas av "asc" (stigande) eller "desc" (fallande). Standardvärdet är stigande ordning. Det finns en gräns på 32 satser för $orderby. När den anropas med POST får den här parametern namnet order i stället för $orderby. |
| 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änglig eller förslag returnerar HTTP-statuskod 503. Om Förslag lyckas på lägstaCoverage-nivå returneras 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 skulle underhållas. 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. Söktexten som ska användas för att föreslå frågor. 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. |
| $select | sträng | Valfritt. En lista över kommaavgränsade fält som ska hämtas. Om den är ospecificerad returneras endast dokumentnyckeln och förslagstexten. Du kan uttryckligen begära alla fält genom att ange den här parametern till *. När du anropar med POST får den här parametern namnet select i stället för $select. |
| 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 du anropar med POST får den här parametern namnet top i stället för $top. |
Svarsåtgärder
Statuskod: "200 OK" returneras för ett lyckat svar.
{
"@search.coverage": # (if minimumCoverage was provided in the query),
"value": [
{
"@search.text": "...",
"<key field>": "..."
},
...
]
}
Om projektionsalternativet används för att hämta fält ingår de i varje element i matrisen:
{
"value": [
{
"@search.text": "...",
"<key field>": "..."
<other projected data fields>
},
...
]
}
Exempel
Hämta 5 förslag där de partiella sökindata är "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"
}
Observera att suggesterName krävs i en förslagsåtgärd.