Documenten zoeken (Azure AI Search REST API)

Artikel
07/11/2023

Een queryaanvraag is gericht op de verzameling documenten van één index in een zoekservice. Het bevat parameters die de matchcriteria definiëren en parameters die het antwoord vormgeven. Vanaf de API-versie 2021-04-30-Preview kunt u ook een indexalias gebruiken om een bepaalde index te targeten in plaats van de indexnaam zelf.

U kunt GET of POST gebruiken. Queryparameters worden opgegeven in de queryreeks voor GET-aanvragen en in de aanvraagtekst voor POST-aanvragen.

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

Als u POST gebruikt, voegt u de actie 'zoeken' toe als een URI-parameter.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?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 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 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.
[queryparameters]	Queryparameters worden opgegeven op de URI voor GET-aanvragen en in de aanvraagtekst voor POST-aanvragen.
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 via URL te coderen wanneer u de GET REST API rechtstreeks aanroept. Voor een bewerking Documenten zoeken kan URL-codering nodig zijn voor de volgende queryparameters:

zoeken
$filter
Facet
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. 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 een 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.

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. 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 een 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:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Vervolg van gedeeltelijke zoekantwoorden

Soms kan Azure AI Search niet alle aangevraagde resultaten in één zoekantwoord retourneren. Dit kan om verschillende redenen gebeuren, bijvoorbeeld wanneer de query te veel documenten aanvraagt door niet op te $top geven of een waarde op te geven voor $top die te groot is. In dergelijke gevallen bevat Azure AI Search de @odata.nextLink aantekening in de antwoordtekst en ook @search.nextPageParameters als het een POST-aanvraag was. U kunt de waarden van deze aantekeningen gebruiken om een andere zoekaanvraag te formuleren om het volgende deel van het zoekantwoord op te halen. Dit wordt een voortzetting van de oorspronkelijke zoekaanvraag genoemd en de aantekeningen worden doorgaans vervolgtokens genoemd. Zie het voorbeeld in Antwoord hieronder voor meer informatie over de syntaxis van deze aantekeningen en waar ze worden weergegeven in de hoofdtekst van het antwoord.

De redenen waarom Azure AI Search vervolgtokens kan retourneren, zijn specifiek voor de implementatie en kunnen worden gewijzigd. Robuuste clients moeten altijd klaar zijn om gevallen af te handelen waarbij minder documenten dan verwacht worden geretourneerd en een vervolgtoken wordt opgenomen om door te gaan met het ophalen van documenten. Houd er ook rekening mee dat u dezelfde HTTP-methode moet gebruiken als de oorspronkelijke aanvraag om door te gaan. Als u bijvoorbeeld een GET-aanvraag hebt verzonden, moeten alle vervolgaanvragen die u verzendt ook GET gebruiken (en op dezelfde manier voor POST).

Notitie

Het doel van @odata.nextLink en @search.nextPageParameters is om de service te beschermen tegen query's die te veel resultaten aanvragen, niet om een algemeen mechanisme voor paging te bieden. Als u door de resultaten wilt bladeren, gebruikt $top u en $skip samen. Als u bijvoorbeeld pagina's met de grootte 10 wilt hebben, moet uw eerste aanvraag en $skip=0hebben $top=10 , moet de tweede aanvraag en $skip=10hebben $top=10 , de derde aanvraag moet en $skip=20hebben$top=10, enzovoort.

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-versies voor een lijst met ondersteunde versies. Voor deze bewerking wordt de api-versie opgegeven als een URI-parameter, ongeacht of u Zoeken in documenten aanroept met GET of POST.
`$count`	booleaans	Optioneel. Geldige waarden zijn 'true' of 'false'. De standaardwaarde is 'false'. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam count in plaats van `$count`. Hiermee geeft u op of het totale aantal resultaten moet worden opgehaald. Dit is het aantal documenten dat overeenkomt met de zoek- en $filter parameters, waarbij `$top` en `$skip`worden genegeerd. Het instellen van deze waarde op 'true' kan de prestaties verslechteren. Het aantal is nauwkeurig als de index stabiel is, maar documenten die actief worden toegevoegd, bijgewerkt of verwijderd, worden onder of te veel worden gemeld. Als u alleen het aantal zonder documenten wilt ophalen, kunt u =0 gebruiken `$top`.
facetten of facetten	tekenreeks	Optioneel. Een veld om mee te facet, waarbij het veld wordt aangeduid als 'facetable'. Wanneer aangeroepen met GET, `facet` is een veld (`facet: field1`). Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam `facets` in plaats van `facet` en wordt deze opgegeven als een matrix (`facets: [field1, field2, field3]`). De tekenreeks kan parameters bevatten om de faceting aan te passen, uitgedrukt in door komma's gescheiden naam-waardeparen. Geldige parameters zijn 'count', 'sort', 'values', 'interval' en 'timeoffset'. "aantal" is het maximum aantal facettermen; de standaardwaarde is 10. Er is geen bovengrens voor het aantal termen, maar hogere waarden verslechteren de prestaties, vooral als het facetveld een groot aantal unieke termen bevat. Met 'facet=category,count:5' worden bijvoorbeeld de vijf belangrijkste categorieën in facetresultaten opgehaald. Als de parameter count kleiner is dan het aantal unieke termen, zijn de resultaten mogelijk niet nauwkeurig. Dit komt door de manier waarop facetquery's worden verdeeld over shards. U kunt aantal instellen op nul of op een waarde die groter is dan of gelijk is aan het aantal unieke waarden in het facetable-veld om een nauwkeurige telling voor alle shards te krijgen. De afweging is een hogere latentie. "sort" kan worden ingesteld op "count", "-count", "value", "-value". Gebruik aantal om aflopend te sorteren op aantal. Gebruik -count om oplopend te sorteren op aantal. Gebruik waarde om oplopend op waarde te sorteren. Gebruik -value om aflopend te sorteren op waarde (bijvoorbeeld'facet=category,count:3,sort:count' krijgt de drie belangrijkste categorieën in facetresultaten in aflopende volgorde op het aantal documenten met elke plaatsnaam). Als de drie belangrijkste categorieën Budget, Motel en Luxe zijn en Budget 5 treffers heeft, Motel heeft er 6 en Luxe 4, zijn de buckets in de volgorde Motel, Budget, Luxe. Voor -value produceert "facet=rating,sort:-value" buckets voor alle mogelijke classificaties, in aflopende volgorde op waarde (als de classificaties bijvoorbeeld van 1 tot 5 zijn, worden de buckets gerangschikt op 5, 4, 3, 2, 1, ongeacht hoeveel documenten overeenkomen met elke classificatie). 'waarden' kan worden ingesteld op door pijpen gescheiden numerieke of Edm.DateTimeOffset-waarden die een dynamische set facetinvoerwaarden opgeven (bijvoorbeeld 'facet=baseRate,values:10 \| 20" produceert drie buckets: één voor basistarief 0 tot maar niet inclusief 10, één voor 10 tot maar niet inclusief 20, en één voor 20 en hoger). Een tekenreeks "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" produceert twee buckets: één voor hotels die zijn gerenoveerd vóór februari 2010 en één voor hotels die op 1 februari 2010 of later zijn gerenoveerd. De waarden moeten in oplopende volgorde worden weergegeven om de verwachte resultaten te krijgen. 'interval' is een geheel getal dat groter is dan 0 voor getallen, of minuut, uur, dag, week, maand, kwartaal, jaar voor datum/tijdwaarden. "facet=baseRate,interval:100" produceert bijvoorbeeld buckets op basis van basisfrequentiebereiken van grootte 100. Als de basistarieven allemaal tussen $ 60 en $ 600 liggen, zijn er buckets voor 0-100, 100-200, 200-300, 300-400, 400-500 en 500-600. De tekenreeks 'facet=lastRenovationDate,interval:year' produceert één bucket voor elk jaar waarin hotels zijn gerenoveerd. "timeoffset" kan worden ingesteld op ([+-]hh:mm, [+-]hhmm of [+-]hh). Als u de parameter timeoffset gebruikt, moet deze worden gecombineerd met de intervaloptie en alleen wanneer deze wordt toegepast op een veld van het type Edm.DateTimeOffset. De waarde geeft de UTC-tijdsverschil aan waarmee rekening moet worden gehouden bij het instellen van tijdsgrenzen. Bijvoorbeeld: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" gebruikt de daggrens die begint om 01:00:00 UTC (middernacht in de doeltijdzone). aantal en sortering kunnen worden gecombineerd in dezelfde facetspecificatie, maar ze kunnen niet worden gecombineerd met interval of waarden, en interval en waarden kunnen niet samen worden gecombineerd. Interval-facetten op datum/tijd worden berekend op basis van de UTC-tijd als er geen timeoffset is opgegeven. Bijvoorbeeld: voor 'facet=lastRenovationDate,interval:day' begint de daggrens om 00:00:00 UTC.
$filter	tekenreeks	Optioneel. Een gestructureerde zoekexpressie in de standaard-OData-syntaxis. Alleen filterbare velden kunnen worden gebruikt in een filter. Bij het aanroepen 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.
Markeren	tekenreeks	Optioneel. Een reeks door komma's gescheiden veldnamen die worden gebruikt voor hit-highlights. Alleen doorzoekbare velden kunnen worden gebruikt voor het markeren van treffers. Standaard retourneert Azure AI Search maximaal 5 markeringen per veld. De limiet kan per veld worden geconfigureerd door '-<max aantal markeringen>' toe te voegen na de veldnaam. 'highlight=title-3,description-10' retourneert bijvoorbeeld maximaal 3 gemarkeerde treffers uit het titelveld en maximaal 10 treffers uit het beschrijvingsveld. Het maximum aantal markeringen moet een geheel getal tussen 1 en 1000 zijn.
highlightPostTag	tekenreeks	Optioneel. De standaardwaarde is `"</em>"`. 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 #).
highlightPreTag	tekenreeks	Optioneel. De standaardwaarde is `"</em>"`. Een tekenreekstag die vooraf gaat aan de gemarkeerde term. Moet worden ingesteld met highlightPostTag. Gereserveerde tekens in DE URL moeten procent zijn gecodeerd (bijvoorbeeld %23 in plaats van #).
minimumCoverage	geheel getal	Optioneel. Geldige waarden zijn een getal tussen 0 en 100, wat 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 is '100'. Honderd procent dekking betekent dat alle shards op de aanvraag hebben gereageerd (noch problemen met de servicestatus of onderhoudsactiviteiten hebben de dekking verminderd). Onder de standaardinstelling retourneert minder dan volledige dekking HTTP-statuscode 503. Het verlagen van minimumCoverage kan handig zijn als er 503-fouten optreden en u de kans op een geslaagde query wilt vergroten, met name voor services die zijn geconfigureerd voor één replica. Als u minimumCoverage instelt en Zoeken slaagt, wordt HTTP 200 geretourneerd en wordt in het antwoord een @search.coverage waarde opgenomen die het percentage van de index aangeeft dat is opgenomen in de query. In dit scenario zijn niet alle overeenkomende documenten gegarandeerd aanwezig in de zoekresultaten, maar als de beschikbaarheid van zoekopdrachten belangrijker is dan intrekken, kan het verminderen van de dekking een haalbare oplossing zijn.
$orderby	tekenreeks	Optioneel. Een lijst met door komma's gescheiden expressies om de resultaten op te sorteren. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam orderby in plaats van $orderby. Elke expressie kan een veldnaam of een aanroep van de functie geo.distance() zijn. Elke expressie kan worden gevolgd door 'asc' om oplopend aan te geven en 'desc' om aflopend aan te geven. Als het sorteerveld null-waarden bevat, worden null-waarden eerst weergegeven in oplopende volgorde en de laatste in aflopende volgorde. De standaardwaarde is oplopende volgorde. Bindingen worden verbroken door de matchscores van documenten. Als er geen $orderby is opgegeven, is de standaardsorteervolgorde aflopend op documentmatchscore. Er is een limiet van 32 componenten voor $orderby.
Querytype	tekenreeks	Optioneel. Geldige waarden zijn 'eenvoudig' of 'volledig'. De standaardwaarde is 'eenvoudig'. 'simple' interpreteert queryreeksen met behulp van de eenvoudige querysyntaxis die symbolen zoals `+`en `""*` toestaat. Query's worden standaard geëvalueerd in alle doorzoekbare velden (of velden die worden aangegeven in searchFields) in elk document. 'volledig' interpreteert queryreeksen met behulp van de volledige Lucene-querysyntaxis , waarmee veldspecifieke en gewogen zoekopdrachten mogelijk zijn. Zoeken naar bereiken in de Lucene-querytaal wordt niet ondersteund ten gunste van $filter, die vergelijkbare functionaliteit biedt.
scoringParameter	tekenreeks	Optioneel. Geeft de waarden aan voor elke parameter die is gedefinieerd in een scorefunctie (zoals referencePointParameter) met behulp van de notatie 'name-value1,value2,...' Wanneer deze parameter wordt aangeroepen met POST, heeft deze parameter de naam scoringParameters in plaats van scoringParameter. U geeft deze ook op als een JSON-matrix met tekenreeksen waarbij elke tekenreeks een afzonderlijk naam-waardenpaar is. Voor scoreprofielen die een functie bevatten, scheidt u de functie van de invoerlijst met een `-` teken. Een functie met de naam `"mylocation"` zou bijvoorbeeld '&scoringParameter=mylocation-122.2,44.8' zijn. Het eerste streepje scheidt de functienaam van de lijst met waarden, terwijl het tweede streepje deel uitmaakt van de eerste waarde (lengtegraad in dit voorbeeld). Voor scoreparameters zoals voor tagverbetering die komma's kunnen bevatten, kunt u dergelijke waarden in de lijst laten ontsnappen met behulp van enkele aanhalingstekens. Als de waarden zelf enkele aanhalingstekens bevatten, kunt u deze escapen door te verdubbelen. Stel dat u een parameter voor tagverbetering hebt met de naam `"mytag"` en u de tagwaarden 'Hello, O'Brien' en 'Smith' wilt verhogen, is de queryreeksoptie '&scoringParameter=mytag-'Hello, O''Brien',Smith'. Aanhalingstekens zijn alleen vereist voor waarden die komma's bevatten.
scoringProfile	tekenreeks	Optioneel. De naam van een scoreprofiel voor het evalueren van matchscores voor overeenkomende documenten om de resultaten te sorteren.
scoringStatistics	tekenreeks	Optioneel. Geldige waarden zijn 'lokaal' of 'globaal'. De standaardinstelling is 'lokaal'. Geef op of scorestatistieken, zoals de documentfrequentie, globaal (voor alle shards) moeten worden berekend voor een consistentere score of lokaal (op de huidige shard) voor een lagere latentie. Zie Scorestatistieken in Azure AI Search. Scorestatistieken worden altijd lokaal berekend voor termen die fuzzy zoeken ('~') gebruiken.
zoeken	tekenreeks	Optioneel. De tekst die moet worden gezocht. Alle doorzoekbare velden worden standaard doorzocht, tenzij searchFields is opgegeven. In de index wordt tekst in een doorzoekbaar veld tokenized, zodat meerdere termen kunnen worden gescheiden door witruimte (bijvoorbeeld'search=hello world'). Gebruik (dit kan handig zijn voor booleaanse filterquery's) om een willekeurige term te vinden `` . Het weglaten van deze parameter heeft hetzelfde effect als het instellen op ``. Zie Eenvoudige querysyntaxis voor details over de zoeksyntaxis. Resultaten kunnen soms verrassend zijn bij het uitvoeren van query's op doorzoekbare velden. De tokenizer bevat logica voor het afhandelen van cases die veel voorkomen in Engelse tekst, zoals apostrofs, komma's in getallen, enzovoort. 'search=123.456' komt bijvoorbeeld overeen met één term '123.456' in plaats van de afzonderlijke termen '123' en '456', omdat komma's worden gebruikt als scheidingstekens voor duizendtallen voor grote getallen in het Engels. Daarom raden we u aan witruimte te gebruiken in plaats van interpunctie om termen in de zoekparameter van elkaar te scheiden.
searchMode	tekenreeks	Optioneel. Geldige waarden zijn 'any' of 'all' De standaardwaarde is 'any'. Hiermee geeft u op of een of alle zoektermen moeten worden vergeleken om het document als een overeenkomst te tellen.
searchFields	tekenreeks	Optioneel. De lijst met door komma's gescheiden veldnamen om naar de opgegeven tekst te zoeken. Doelvelden moeten worden gemarkeerd als doorzoekbaar in het indexschema.
$select	tekenreeks	Optioneel. Een lijst met door komma's gescheiden velden die moeten worden opgenomen in de resultatenset. Alleen velden die zijn gemarkeerd als ophaalbaar, kunnen in deze component worden opgenomen. Als dit niet is opgegeven of is ingesteld op `*`, worden alle velden die zijn gemarkeerd als ophaalbaar in het schema opgenomen in de projectie. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam select in plaats van $select.
Sessionid	tekenreeks	Optioneel. Met behulp van sessionId kunt u de consistentie van de relevantiescore verbeteren voor zoekservices met meerdere replica's. In configuraties met meerdere replica's kunnen er kleine verschillen zijn tussen de relevantiescores van afzonderlijke documenten voor dezelfde query. Wanneer een sessie-id wordt opgegeven, doet de service er alles aan om een bepaalde aanvraag naar dezelfde replica voor die sessie te routeren. Wees voorzichtig dat het herhaaldelijk hergebruiken van dezelfde sessie-id-waarden de taakverdeling van de aanvragen over replica's kan verstoren en de prestaties van de zoekservice nadelig kan beïnvloeden. De waarde die wordt gebruikt als sessionId kan niet beginnen met een '_'-teken. Als een service geen replica's heeft, heeft deze parameter geen invloed op de prestaties of scoreconsistentie.
$skip	geheel getal	Optioneel. Het aantal zoekresultaten dat moet worden overgeslagen. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam skip in plaats van `$skip`. Deze waarde mag niet groter zijn dan 100.000. Als u documenten opeenvolgend moet scannen, maar niet kunt gebruiken `$skip` vanwege deze beperking, kunt u overwegen om $orderby te gebruiken voor een veld met unieke waarden voor elk document in de index (bijvoorbeeld de documentsleutel) en $filter met een bereikquery.
$top	geheel getal	Optioneel. Het aantal zoekresultaten dat moet worden opgehaald. De standaardwaarde is 50. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam top in plaats van `$top`. Als u een waarde opgeeft die groter is dan 1000 en er meer dan 1000 resultaten zijn, worden alleen de eerste 1000 resultaten geretourneerd, samen met een koppeling naar de volgende pagina met resultaten (zie @odata.nextLink in het onderstaande voorbeeld). Azure AI Search maakt gebruik van paging aan de serverzijde om te voorkomen dat query's te veel documenten tegelijk ophalen. Het standaardpaginaformaat is 50, terwijl het maximale paginaformaat 1000 is. Dit betekent dat standaard in Documenten zoeken maximaal 50 resultaten retourneert als u niet opgeeft `$top`. Als er meer dan 50 resultaten zijn, bevat het antwoord informatie om de volgende pagina van maximaal 50 resultaten op te halen (zie '@odata.nextLink' en '@search.nextPageParameters' in de onderstaande voorbeelden . Als u een waarde opgeeft die groter is dan 1000 voor `$top` en er meer dan 1000 resultaten zijn, worden alleen de eerste 1000 resultaten geretourneerd, samen met informatie om de volgende pagina van maximaal 1000 resultaten op te halen.

Antwoord

Statuscode: 200 OK wordt geretourneerd voor een geslaagd antwoord.

  {
    "@odata.count": # (if `$count`=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Voorbeelden

Meer voorbeelden vindt u in de syntaxis van OData-expressies voor Azure AI Search.

Zoek in de index die aflopend is gesorteerd op datum:

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

Zoek in een facetzoekactie in de index en haal facetten op voor categorieën, classificaties, tags en items met baseRate in specifieke bereiken.
```
GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  
```
U ziet dat het laatste facet zich op een subveld bevindt. Facetten tellen het bovenliggende document (Hotels) en niet de tussenliggende subdocumenten (Kamers), dus het antwoord bepaalt het aantal hotels dat kamers in elke prijslijst heeft.

Gebruik een filter om het resultaat van de vorige facetquery te verfijnen nadat de gebruiker Classificatie 3 en categorie 'Motel' heeft geselecteerd.

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

Stel in een facetzoekopdracht een bovengrens in voor unieke termen die in een query worden geretourneerd. De standaardwaarde is 10, maar u kunt deze waarde verhogen of verlagen met behulp van de parameter count voor het facetkenmerk. In dit voorbeeld worden facetten voor stad geretourneerd, beperkt tot 5.
```
GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

Zoeken in de index binnen specifieke velden (bijvoorbeeld een taalveld):

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

Zoek in de index in meerdere velden. U kunt bijvoorbeeld doorzoekbare velden opslaan en doorzoeken in meerdere talen, allemaal binnen dezelfde index. Als Engelse en Franse beschrijvingen naast elkaar bestaan in hetzelfde document, kunt u een of alle queryresultaten retourneren:
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
U kunt slechts een query uitvoeren op indexen tegelijk. Maak niet meerdere indexen voor elke taal, tenzij u van plan bent om een query voor één uit te voeren.

Paging: de eerste pagina met items ophalen (paginaformaat is 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

Paging: de tweede pagina met items ophalen (paginaformaat is 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

Een specifieke set velden ophalen:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

Documenten ophalen die overeenkomen met een specifieke filterexpressie:

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

Zoek in de index en retourneer fragmenten met hit-markeringen:

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

Zoek in de index en retourneer documenten die zijn gesorteerd van dichter naar verder weg van een referentielocatie:

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

Zoek in de index, ervan uitgaande dat er een scoreprofiel met de naam 'geo' is met twee functies voor scoren op afstand, één die een parameter met de naam 'currentLocation' definieert en een die een parameter met de naam 'lastLocation' definieert. In het volgende voorbeeld heeft 'currentLocation' een scheidingsteken van één streepje (-). Deze wordt gevolgd door lengte- en breedtegraadcoördinaten, waarbij lengtegraad een negatieve waarde is.
```
GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }  
```
Documenten zoeken in de index met behulp van eenvoudige querysyntaxis. Deze query retourneert hotels waar doorzoekbare velden de termen 'comfort' en 'location' bevatten, maar niet 'motel':
```
Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  
```
Tip

Het gebruik van searchMode=all overschrijft de standaardwaarde van searchMode=any, zodat -motel dit 'AND NOT' betekent in plaats van 'OR NOT'. Zonder searchMode=allkrijgt u 'OR NOT' waardoor zoekresultaten worden uitgebreid in plaats van beperkt. Dit kan voor sommige gebruikers contra-intuïtief zijn.

Documenten zoeken in de index met behulp van Lucene-querysyntaxis). Deze query retourneert hotels waar het categorieveld de term 'budget' bevat en alle doorzoekbare velden met de woordgroep 'onlangs gerenoveerd'. Documenten met de zin 'onlangs gerenoveerd' worden hoger gerangschikt als gevolg van de term boostwaarde (3)

GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full`

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}

Zoek documenten in de index en geef de voorkeur aan consistent scoren boven een lagere latentie. Met deze query worden de documentfrequenties voor de hele index berekend en wordt getroost om voor alle query's binnen dezelfde 'sessie' dezelfde replica te gebruiken, wat helpt bij het genereren van een stabiele en reproduceerbare classificatie.
```
GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```