Automatisch aanvullen (Azure AI Search REST API)
De API voor automatisch aanvullen voltooit een gedeeltelijk getypte queryinvoer met behulp van bestaande termen in de zoekindex voor gebruik in een secundaire query. Als de queryinvoer bijvoorbeeld is "medic", retourneert "medicare"de API voor automatisch aanvullen , "medicaid", "medicine" als deze termen in de index staan. Intern zoekt het zoekprogramma naar overeenkomende termen in velden waarvoor een Suggester is geconfigureerd.
HTTPS is vereist voor serviceaanvragen. De aanvraag voor automatisch aanvullen kan worden samengesteld met behulp van de get- of POST-methode.
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]
Wanneer de aanvraag-URL wordt aangeroepen met GET, mag de lengte van de aanvraag-URL niet groter zijn dan 8 kB. Deze lengte is meestal voldoende voor de meeste toepassingen. Sommige toepassingen produceren echter zeer grote query's, met name wanneer OData-filterexpressies worden gebruikt. Voor deze toepassingen is HTTP POST een betere keuze omdat het grotere filters dan GET toestaat.
Met POST is het aantal componenten in een filter de beperkende factor, niet de grootte van de onbewerkte filtertekenreeks, omdat de limiet voor de aanvraaggrootte voor POST ongeveer 16 MB is. Hoewel de limiet voor de POST-aanvraaggrootte erg groot is, kunnen filterexpressies niet willekeurig complex zijn. Zie OData Expression Syntax for Azure AI Search (Syntaxis van OData-expressie voor Azure AI Search) voor meer informatie over beperkingen van filtercomplexiteit.
URI-parameters
| Parameter | Beschrijving |
|---|---|
| [servicenaam] | Vereist. Stel deze in op de unieke, door de gebruiker gedefinieerde naam van uw zoekservice. |
| [indexnaam]/docs | Vereist. Hiermee geeft u de documentenverzameling van een benoemde index op. |
| api-versie | Vereist. Zie API-versies voor een lijst met ondersteunde versies. Voor query's wordt de API-versie altijd opgegeven als een URI-parameter voor zowel GET als POST. |
Aanbevelingen voor URL-codering
Vergeet niet om specifieke queryparameters via URL te coderen wanneer u de GET REST API rechtstreeks aanroept. Voor automatisch aanvullen kan URL-codering nodig zijn voor de volgende queryparameters:
- zoeken
- $filter
- highlightPreTag
- highlightPostTag
URL-codering wordt alleen aanbevolen voor afzonderlijke parameters. Als u per ongeluk de hele querytekenreeks (alles na de ?) urlcodereert, worden aanvragen verbroken.
URL-codering is ook alleen nodig wanneer u de REST API rechtstreeks aanroept met behulp van GET. Er is geen URL-codering nodig bij het gebruik van POST of bij het gebruik van de Azure AI Search .NET-clientbibliotheek, die codering voor u afhandelt.
Aanvraagheaders
In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.
| Velden | Description |
|---|---|
| Content-Type | Vereist. Stel dit in op application/json |
| api-sleutel | Optioneel als u Azure-rollen gebruikt en er een bearer-token wordt opgegeven voor de aanvraag, anders is een sleutel vereist. Queryaanvragen voor de docs verzameling kunnen een beheerderssleutel of querysleutel opgeven als de api-key. De querysleutel wordt gebruikt voor alleen-lezen bewerkingen in een verzameling indexdocumenten. Zie Verbinding maken met Azure AI Search met behulp van sleutelverificatie voor meer informatie. |
Aanvraagbody
Voor GET: Geen.
Voor 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)
}
Queryparameters
Een query accepteert verschillende parameters op de URL wanneer deze wordt aangeroepen met GET en als JSON-eigenschappen in de hoofdtekst van de aanvraag wanneer deze wordt aangeroepen met POST. De syntaxis voor sommige parameters verschilt enigszins tussen GET en POST. Deze verschillen worden hieronder vermeld, zoals van toepassing.
| Naam | Type | Description |
|---|---|---|
| api-versie | tekenreeks | Vereist. Versie van de REST API die wordt gebruikt voor de aanvraag. Zie API-versiebeheer voor een lijst met ondersteunde versies. Voor deze bewerking wordt de API-versie opgegeven als een URI-parameter, ongeacht of u Automatisch aanvullen aanroept met GET of POST. |
| autocompleteMode | tekenreeks | Optioneel. De standaardinstelling is oneTerm. Geldige waarden zijn oneTerm, twoTerms, oneTermWithContext. oneTerm retourneert één term. Als de query twee termen bevat, wordt alleen de laatste term voltooid. Als u bijvoorbeeld "washington medic"ziet, kan het antwoord een van deze enkele termen zijn: "medicaid", "medicare", "medicine". twoTerms komt overeen met tweetermen in de index. Als u bijvoorbeeld krijgt "medic", kan het antwoord zijn "medicare coverage", of "medical assistant". In veel gevallen worden de enkele termen "medicare" of "medical" niet geretourneerd omdat de voorkeur wordt gegeven aan woordgroepen met twee termen die overeenkomen.oneTermWithContext voltooit de laatste term in een query met twee of meer termen, waarbij de laatste twee termen een woordgroep zijn die in de index bestaat. Als u bijvoorbeeld krijgt "washington medic", kan het antwoord zijn"washington medicaid", . "washington medical" |
| $filter | tekenreeks | Optioneel. Een gestructureerde zoekexpressie in de standaard-OData-syntaxis die de documenten filtert die in aanmerking komen voor het produceren van de voltooide termensuggesties. Filterexpressies 'search.ismatch' en 'search.ismatchscoring*' worden niet ondersteund in de API voor automatisch aanvullen. Alleen filterbare velden kunnen in een filter worden gebruikt. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam filter in plaats van $filter. Zie Syntaxis van OData-expressie voor Azure AI Search voor meer informatie over de subset van de grammatica van de OData-expressie die azure AI Search ondersteunt. |
| Fuzzy | booleaans | Optioneel. De standaardinstelling is false. Als deze is ingesteld op true, vindt deze API suggesties, zelfs als de zoektekst een vervangend of ontbrekend teken bevat (1). Dit biedt een betere ervaring in sommige scenario's, maar dit brengt kosten met zich mee omdat zoekopdrachten voor fuzzy suggesties langzamer zijn en meer resources verbruiken. |
| highlightPostTag | tekenreeks | Optioneel. Standaard ingesteld op een lege tekenreeks. Een tekenreekstag die wordt toegevoegd aan de gemarkeerde term. Moet worden ingesteld met highlightPreTag. Gereserveerde tekens in DE URL moeten in procenten zijn gecodeerd (bijvoorbeeld %23 in plaats van #). Bij aangeroepen met behulp van GET, moeten de gereserveerde tekens in de URL zijn gecodeerd met procenten (bijvoorbeeld %23 in plaats van #). |
| highlightPreTag | tekenreeks | Optioneel. Standaard ingesteld op een lege tekenreeks. Een tekenreekstag die vooraf gaat aan de gemarkeerde term. Moet worden ingesteld met highlightPostTag. Bij aangeroepen met behulp van GET, moeten de gereserveerde tekens in de URL zijn gecodeerd met procenten (bijvoorbeeld %23 in plaats van #). |
| minimumCoverage | geheel getal | Optioneel. De standaardwaarde is 80. Een getal tussen 0 en 100 dat het percentage van de index aangeeft dat beschikbaar moet zijn voor het uitvoeren van de query voordat deze als geslaagd kan worden gerapporteerd. De standaardwaarde weerspiegelt een afwijking ten opzichte van snelheid en efficiëntie ten opzichte van volledige dekking. Als u de dekking vermindert, beperkt u de query-uitbreiding, zodat resultaten sneller terugkomen. Hiermee kan de query ook slagen bij gedeeltelijke beschikbaarheid van indexen, zelfs als een shard traag reageert of niet beschikbaar is vanwege problemen met de servicestatus of indexonderhoud. Ongeacht de waarde van minimumCoverage, moet dat percentage van de index beschikbaar zijn, anders retourneert Automatisch aanvullen HTTP-statuscode 503. Als Automatisch aanvullen slaagt op het niveau minimumCoverage, wordt HTTP 200 geretourneerd en wordt in het antwoord een @search.coverage waarde opgenomen die het percentage van de index aangeeft dat beschikbaar was bij het uitvoeren van de query. Het verlagen van deze waarde kan handig zijn als er 503-fouten optreden. Anders kunt u overwegen om de waarde te verhogen als het antwoord onvoldoende overeenkomsten biedt. |
| zoeken | tekenreeks | Vereist. De tekst die u wilt zoeken. De zoektekst die moet worden voltooid. Moet ten minste één teken en niet meer dan 100 tekens bevatten. Het mag geen operatoren, querysyntaxis of woordgroepen tussen aan citeren bevatten. |
| searchFields | tekenreeks | Optioneel. De lijst met door komma's gescheiden veldnamen om te zoeken naar de opgegeven zoektekst. Doelvelden moeten worden vermeld in de definitie Van suggesties in de index. |
| suggesterName | tekenreeks | Vereist. De naam van de suggester zoals opgegeven in de verzameling Suggesters die deel uitmaakt van de indexdefinitie. Een suggester bepaalt welke velden worden gescand op voorgestelde querytermen. |
| $top | geheel getal | Optioneel. De standaardwaarde is 5. Het aantal automatisch aangevulde suggesties dat moet worden opgehaald. De waarde moet een getal tussen 1 en 100 zijn. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam bovenaan in plaats van $top. |
(1) Beperkingen van fuzzy in Automatisch aanvullen:
Ten eerste is de bewerkingsafstand beperkt tot slechts één tekenverschil per token, in tegenstelling tot de parameter fuzzy in de zoekopdracht. Het beperken van de bewerkingsafstand tot één teken betekent dat niet alle kandidaatovereenkomsten worden gevonden, maar de limiet is nodig om een acceptabel prestatieniveau te garanderen.
Ten tweede vindt de fuzzy-stap plaats na de gedeeltelijke tokenuitbreiding en worden alleen termen uit dezelfde indexshard in aanmerking genomen voor fuzzy overeenkomsten. Deze beperking verhoogt de prestaties van de API voor automatisch aanvullen door de aggregatie van fuzzy overeenkomsten voor alle shards te elimineren. Deze beperking wordt minder merkbaar naarmate er meer termen aan de index worden toegevoegd, wat resulteert in een vergelijkbare termenverdeling voor elke shard. Als termen gelijkmatig worden verdeeld, zijn fuzzy overeenkomsten binnen een shard een goede benadering van fuzzy overeenkomsten in de hele index. De resultaten kunnen echter inferieur zijn als de index minder termen heeft, zoals in een test- of prototype-index, wat resulteert in een ongelijke weergave tussen shards. Zie partitie- en replicacombinaties voor meer informatie over hoe indexen worden onderverdeeld in shards.
Antwoord
Statuscode: '200 OK' wordt geretourneerd voor een geslaagd antwoord.
De nettolading van het antwoord heeft twee eigenschappen.
| Eigenschap | Beschrijving |
|---|---|
| "tekst" | De voltooide term of woordgroep |
| "queryPlusText" | De initiële queryinvoer plus de voltooide term of woordgroep |
{
"@search.coverage": # (if minimumCoverage was provided in the query),
"value": [
{
"text": "...",
"queryPlusText": "..."
},
...
]
}
Voorbeelden
Voorbeeld 1: Haal drie suggesties voor automatisch aanvullen op waarbij de gedeeltelijke zoekinvoer is 'washington medic' met de standaardmodus (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"
}
Reactie:
{
"value": [
{
"text": "medicaid",
"queryPlusText": "washington medicaid"
},
{
"text": "medicare",
"queryPlusText": "washington medicare"
},
{
"text": "medicine",
"queryPlusText": "washington medicine"
}
]
}
Voorbeeld 2: Drie suggesties voor automatisch aanvullen ophalen waarbij de gedeeltelijke zoekinvoer is 'washington medic' en 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"
}
Reactie:
{
"value": [
{
"text": "medicaid insurance",
"queryPlusText": "washington medicaid insurance"
},
{
"text": "medicare plan",
"queryPlusText": "washington medicare plan"
},
{
"text": "medicine book",
"queryPlusText": "washington medicine book"
}
]
}
U ziet dat suggesterName vereist is voor een bewerking voor automatisch aanvullen.