Suggesties (Azure AI Search REST API)

  • Artikel

Een aanvraag voor suggesties is een query die zoekt naar overeenkomende waarden in suggestiebewuste velden en documenten retourneert die een overeenkomst bevatten. Als u bijvoorbeeld suggesties voor een stadsveld inschakelt, worden documenten met 'Seattle', 'Sea Tac' en 'Seaside' (alle werkelijke plaatsnamen) voor dat veld gegenereerd.

Het antwoord is een inhoud uit een overeenkomend document plus de documentsleutel. In tegenstelling tot Automatisch aanvullen, dat een voltooide term of woordgroep retourneert die wordt gebruikt in een secundaire query, retourneert deze aanvraag informatie die wordt omgezet in werkelijke documenten. Als overeenkomende termen of woordgroepen identiek zijn in documenten, wordt de overeenkomende inhoud herhaald. Als u de structuur van de resultaten wilt verbeteren, kunt u het $select filter gebruiken om extra velden te retourneren die meer differentiatie en context bieden.

HTTPS is vereist voor serviceaanvragen. De aanvraag Voorstellen kan worden samengesteld met behulp van de get- of POST-methode.

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]

In tegenstelling tot een aanvraag voor zoeken in documenten , kunt u een aanroep Suggesties binden aan toetsenbordinvoer, terwijl een zoekopdracht mogelijk is gebonden aan een klik-gebeurtenis.

Wanneer 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 maximale grootte van de POST-aanvraag 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 voor 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. De huidige stabiele versie is api-version=2020-06-30. Zie API-versies voor meer 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 url-coderen wanneer u de GET REST API rechtstreeks aanroept. Voor suggestiebewerkingen omvat dit:

  • zoeken
  • $filter
  • highlightPreTag
  • highlightPostTag

URL-codering wordt alleen aanbevolen voor afzonderlijke parameters. Als u per ongeluk de hele queryreeks (alles na de ?) url-codering uitvoert, 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 aanroepen van Suggesties met behulp van POST, of wanneer de Azure AI Search .NET-clientbibliotheek URL-codering voor u verwerkt.

Aanvraagheaders

In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.

Velden Description
Content-Type Vereist. Stel dit in op application/json
api-key Optioneel als u Azure-rollen gebruikt en er een Bearer-token is opgegeven voor de aanvraag, anders is een sleutel vereist. Een API-sleutel is een unieke, door het systeem gegenereerde tekenreeks die de aanvraag verifieert bij uw zoekservice. Queryaanvragen voor de documentenverzameling kunnen een beheerderssleutel of querysleutel opgeven als de API-sleutel. De querysleutel wordt gebruikt voor alleen-lezenbewerkingen voor de documentenverzameling. Zie Verbinding maken met Azure AI Search met behulp van sleutelverificatie voor meer informatie.

Aanvraagbody

Voor GET: Geen.

Voor 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)  
}

Queryparameters

Een query accepteert verschillende parameters op de URL wanneer deze wordt aangeroepen met GET en als JSON-eigenschappen in de aanvraagbody wanneer 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-versies voor een lijst met ondersteunde versies. Voor deze bewerking wordt de API-versie opgegeven als een queryparameter in de URL, ongeacht of u de API aanroept met GET of POST.
$filter tekenreeks Optioneel. Een expressie waarmee de documenten worden gefilterd die in aanmerking komen voor suggesties. Alleen filterbare velden kunnen worden gebruikt in een filter. Filterexpressies 'search.ismatch' en 'search.ismatchscoring*' worden niet ondersteund in de API voor automatisch aanvullen. 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 door Azure AI Search wordt ondersteund.
Fuzzy booleaans Optioneel. De standaardinstelling is false. Als deze optie is ingesteld op true, vindt deze API suggesties, zelfs als er een vervangend of ontbrekend teken in de zoektekst staat. De bewerkingsafstand is 1 per querytekenreeks. Als de querytekenreeks uit meerdere termen bestaat, kan er slechts één extra, vervangen of getransponeerd teken in de hele tekenreeks ontbreken. Het inschakelen van fuzzy overeenkomsten kan in sommige scenario's een betere ervaring zijn. Dit brengt prestatiekosten met zich mee, omdat zoekopdrachten met fuzzy suggesties langzamer zijn en meer resources verbruiken.
highlightPostTag tekenreeks Optioneel. De standaardwaarde is een lege tekenreeks. Een tekenreekstag die wordt toegevoegd aan de gemarkeerde term. Moet worden ingesteld met highlightPreTag. Gereserveerde tekens in DE URL moeten procent zijn gecodeerd (bijvoorbeeld %23 in plaats van #). Wanneer de gereserveerde tekens in de URL worden aangeroepen met behulp van GET, moeten de gereserveerde tekens in procenten zijn gecodeerd (bijvoorbeeld %23 in plaats van #).
highlightPreTag tekenreeks Optioneel. De standaardwaarde is een lege tekenreeks. Een tekenreekstag die vooraf gaat aan de gemarkeerde term. Moet worden ingesteld met highlightPostTag. Wanneer de gereserveerde tekens in de URL worden aangeroepen met behulp van GET, moeten de gereserveerde tekens in procenten zijn gecodeerd (bijvoorbeeld %23 in plaats van #).
$orderby tekenreeks Optioneel. Een lijst met door komma's gescheiden expressies om de resultaten op te sorteren. Elke expressie kan een veldnaam of een aanroep naar de geo.distance() functie zijn. Elke expressie kan worden gevolgd door 'asc' (oplopend) of 'desc' (aflopend). De standaardwaarde is oplopende volgorde. Er is een limiet van 32 componenten voor $orderby. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam volgorde in plaats van $orderby.
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. Het verminderen van de dekking beperkt de query-uitbreiding, waardoor resultaten sneller kunnen worden geretourneerd. Hiermee kan de query ook slagen bij gedeeltelijke beschikbaarheid van indexen, zelfs als een shard traag reageert of niet beschikbaar is vanwege servicestatusproblemen of indexonderhoud.

Ongeacht de waarde van minimumCoverage, moet dat percentage van de index beschikbaar zijn, anders retourneert Suggestions HTTP-statuscode 503. Als suggesties slagen 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 de waarde te verhogen als het antwoord onvoldoende overeenkomsten biedt.
zoeken tekenreeks Vereist. De zoektekst die moet worden gebruikt om query's voor te stellen. Moet ten minste één teken en niet meer dan 100 tekens bevatten. Het mag geen operatoren, querysyntaxis of woordgroepen met 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.
$select tekenreeks Optioneel. Een lijst met door komma's gescheiden velden om op te halen. Als u deze niet opgeeft, worden alleen de documentsleutel en de suggestietekst geretourneerd. U kunt alle velden expliciet aanvragen door deze parameter in te stellen op *. Bij het aanroepen met POST krijgt deze parameter de naam select in plaats van $select.
suggesterName tekenreeks Vereist. De naam van de suggestiefunctie zoals opgegeven in de verzameling Suggesters die deel uitmaakt van de indexdefinitie. Een suggestie 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. Bij het aanroepen met POST krijgt deze parameter de naam top in plaats van $top.

Antwoord

Statuscode: '200 OK' wordt geretourneerd voor een geslaagd antwoord.

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

Als de projectieoptie wordt gebruikt om velden op te halen, worden deze opgenomen in elk element van de matrix:

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

Voorbeelden

Haal 5 suggesties op waarbij de gedeeltelijke zoekinvoer 'lux' is:

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"  
    }

U ziet dat suggesterName vereist is voor een suggestiebewerking.

Zie ook