Documenten zoeken (Azure Cognitive Search REST API)

Een queryaanvraag is gericht op de verzameling documenten van één index in een zoekservice. Het bevat parameters die de overeenkomstcriteria definiëren en parameters die het antwoord vormen.

U kunt GET of POST gebruiken. Queryparameters worden opgegeven in de queryreeks in het geval van GET-aanvragen en in de aanvraag body in het geval van 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]  

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 wordt aangeroepen met GET, mag de lengte van de aanvraag-URL niet groter zijn dan 8 kB. Deze lengte is doorgaans voldoende voor de meeste toepassingen. Sommige toepassingen produceren echter zeer grote query's, met name wanneer OData-filterexpressie wordt gebruikt. Voor deze toepassingen is HTTP POST een betere keuze omdat er grotere filters zijn dan GET.

Met POST is het aantal componenten in een filter de beperkende factor, niet de grootte van de onbewerkte filterreeks, omdat de limiet voor de aanvraaggrootte voor POST ongeveer 16 MB is. Hoewel de limiet voor de grootte van de POST-aanvraag zeer groot is, kunnen filterexpressies niet willekeurig complex zijn. Zie OData Expression Syntax for Azure Cognitive Search (Syntaxis voor OData-expressies voor meer informatie over beperkingen van filtercomplexiteit).

URI-parameters

Aanbevelingen voor URL-codering

Vergeet niet om specifieke queryparameters url-codering toe te passen wanneer u de GET-REST API 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 URL van de volledige queryreeks codeert (alles na ? de ), worden aanvragen onderbroken.

URL-codering is ook alleen nodig bij het rechtstreeks aanroepen van REST API met BEHULP van GET. Er is geen URL-codering nodig bij het gebruik van POST of bij het gebruik van de Azure Cognitive Search .NET-clientbibliotheek,waarmee codering voor u wordt verwerkt.

Aanvraagheaders

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

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

Voortzetting van gedeeltelijke zoekreacties

Soms Azure Cognitive Search niet alle aangevraagde resultaten in één Zoekopdracht-antwoord retourneren. Dit kan om verschillende redenen gebeuren, zoals wanneer de query te veel documenten aanvraagt door $top niet op te geven of een waarde op te geven voor $top die te groot is. In dergelijke gevallen bevat Azure Cognitive Search de aantekening in de antwoord-body en ook als @odata.nextLink @search.nextPageParameters het een POST-aanvraag was. U kunt de waarden van deze aantekeningen gebruiken om een andere Search-aanvraag te formuleren om het volgende deel van het zoekreactie op te halen. Dit wordt een vervolg van de oorspronkelijke Zoekopdracht-aanvraag 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 antwoord body.

De redenen waarom Azure Cognitive Search vervolgtokens retourneren, zijn implementaties specifiek en kunnen worden gewijzigd. Robuuste clients moeten altijd gereed zijn voor het afhandelen van gevallen waarin minder documenten dan verwacht worden geretourneerd en een vervolg-token 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 ook voor POST).

Queryparameters

Een query accepteert verschillende parameters op de URL wanneer deze wordt aangeroepen met GET en als JSON-eigenschappen in de aanvraag body wanneer deze wordt aangeroepen met POST. De syntaxis voor sommige parameters is iets anders tussen GET en POST. Deze verschillen worden hieronder vermeld als van toepassing.

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

U vindt aanvullende voorbeelden in de OData-expressiesyntaxis voor Azure Cognitive Search.

1. De index aflopend gesorteerd op datum doorzoeken:

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

2. In een facetzoekactie zoekt u de index en haalt u facetten op voor categorieën, classificaties, tags, evenals 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 in een subveld voordeed. Facetten tellen het bovenliggende document (Hotels) en niet tussenliggende subdocumenten (ruimten), dus het antwoord bepaalt het aantal hotels met een kamer in elke prijse bucket.

3. Gebruik een filter om het vorige facetqueryresultaat te beperken nadat de gebruiker Classificatie 3 en categorie 'Filter' 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'"  
       }  
   

4. Stel in een facetzoekactie 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 count-parameter op het facetkenmerk. Dit voorbeeld retourneert facetten voor de stad, 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" ]  
       }  
   

5. Zoek 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"
       }  
   

6. Doorzoek de index in meerdere velden. U kunt bijvoorbeeld doorzoekbare velden in meerdere talen opslaan en er query's op uitvoeren, allemaal binnen dezelfde index. Als engelse en Franse beschrijvingen naast elkaar voorkomen in hetzelfde document, kunt u een of alle beschrijvingen in de 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 alleen een query uitvoeren op de index tegelijk. Maak niet meerdere indexen voor elke taal, tenzij u van plan bent een query één voor één uit te voeren.

7. Paginering: haal de eerste pagina met items op (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  
       }  
   

8. Paginering: haal de tweede pagina met items op (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  
       }  
   

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

10. 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'"  
        }  
    

11. Zoek de index en retourneert fragmenten met belangrijke treffers:

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

12. Zoek in de index en retourneert documenten die zijn gesorteerd van dichter bij 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)')"
        }  
    

13. Zoek in de index ervan uitgaande dat er een scoreprofiel met de naam 'geo' is met functies voor het scoren van twee afstanden, één met de naam 'currentLocation' en één met de naam 'lastLocation':

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

14. Documenten in de index zoeken met behulp van eenvoudige querysyntaxis. Deze query retourneert hotels waar doorzoekbare velden de termen 'comfort' en 'locatie' bevatten, maar niet 'hotels':

    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 overschrijven de standaardwaarde searchMode=any van , zodat dit 'AND NOT' betekent in plaats van -motel 'OR NOT'. Zonder searchMode=all krijgt u 'OR NOT', waarmee zoekresultaten worden uitgebreid in plaats van beperkt, en dit kan voor sommige gebruikers tegen intuïtief zijn.

15. Documenten zoeken in de index met lucene-querysyntaxis). Deze query retourneert hotels waar het categorieveld de term 'budget' bevat en alle doorzoekbare velden met de zin 'recent renovatie'. Documenten met de zin 'recent recent vernieuwd' worden hoger geclassificeerd als gevolg van de term boost-waarde (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"  
    }  
    

16. Zoek documenten in de index terwijl u de voorkeur geeft aan consistent scoren boven een lagere latentie. Deze query berekent de frequenties van documenten voor de hele index en doet er alles aan om dezelfde replica te richten op alle query's binnen dezelfde 'sessie', waardoor stabiele en reproduceerbare classificatie kan worden gegenereerd.

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

Zie ook

• Query's maken in Azure Cognitive Search
• Query's in Azure Cognitive Search
• Hoe zoeken in de volledige tekst werkt in Azure Cognitive Search
• OData-expressiesyntaxis voor Azure vSearch
• Eenvoudige querysyntaxis in Azure Cognitive Search