Hledání dokumentů (Azure Kognitivní hledání REST API)

Požadavek na dotaz cílí na kolekci dokumentů s jedním indexem ve vyhledávací službě. Obsahuje parametry, které definují kritéria shody, a parametry, které tvarují odpověď.

Můžete použít GET nebo POST. Parametry dotazu jsou zadány v řetězci dotazu v případě požadavků GET a v textu žádosti v případě požadavků post.

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]  

Při volání metody GET nemůže adresa URL požadavku překročit 8 KB. Tato délka je obvykle dostatečná pro většinu aplikací. Některé aplikace však vytváří velmi velké dotazy, konkrétně při použití výrazů filtru OData. Pro tyto aplikace je HTTP POST lepší volbou, protože umožňuje větší filtry než GET.

S POST je počtem klauzulí ve filtru omezující faktor, nikoli velikost nezpracovaného řetězce filtru, protože limit velikosti požadavku pro POST je přibližně 16 MB. I když je limit velikosti požadavku POST velmi velký, výrazy filtru nelze libovolně složitě složitě. Další informace o omezeních složitosti filtru najdete v tématu syntaxe výrazu OData pro Azure kognitivní hledání.

Parametry identifikátoru URI

Doporučení pro kódování adresy URL

Nezapomeňte zadat parametry dotazu specifické pro kódování URL při přímém volání metody Get REST API. Pro operaci hledání dokumentů může být pro následující parametry dotazu potřeba kódování URL.

• search
• $filter
• omezující vlastnost
• highlightPreTag
• highlightPostTag

Kódování adresy URL se doporučuje jenom pro jednotlivé parametry. Pokud omylem zakódujete celý řetězec dotazu (vše za tím ? ,), požadavky budou přerušeny.

Kódování adresy URL je také nutné při volání REST API přímo pomocí GET. Při použití POST nebo při použití klientské knihovny Azure kognitivní hledání .NET, která pro vás zpracovává kódování, není nutné žádné kódování URL.

Hlavičky požadavku

V následující tabulce jsou popsány povinné a volitelné hlavičky požadavků.

Text požadavku

Pro GET: none.

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

Pokračování částečných odpovědí na hledání

Někdy Azure Kognitivní hledání nemůže vrátit všechny požadované výsledky v rámci jedné odpovědi hledání. K tomu může dojít z různých důvodů, například když dotaz požádá o příliš mnoho dokumentů, protože nespecifikuje $top nebo neurčuje hodnotu pro $top, která je příliš velká. V takových případech bude Azure Kognitivní hledání obsahovat @odata.nextLink anotaci v těle odpovědi a také v případě, že se jednalo @search.nextPageParameters o požadavek POST. Hodnoty těchto poznámek můžete použít k formulaci jiné žádosti o vyhledávání k získání další části odpovědi na hledání. To se označuje jako pokračování původního požadavku na hledání a poznámky se obecně nazývají tokeny pro pokračování. Podrobnosti o syntaxi těchto poznámek a jejich zobrazení v těle odpovědi najdete v příkladu v odpovědi níže.

Důvody, proč může Azure Kognitivní hledání vracet pokračování tokeny, jsou specifické pro konkrétní implementaci a můžou se měnit. Robustní klienti by měli být vždycky připraveni zpracovat případy, kdy se vrátí méně dokumentů, než se očekávalo, a k pokračování načítání dokumentů je k dispozici token pro pokračování. Všimněte si také, že je nutné použít stejnou metodu HTTP jako původní požadavek, aby bylo možné pokračovat. Pokud jste například poslali požadavek GET, všechny požadavky na pokračování, které odesíláte, musí také použít metodu GET (a také pro POST).

Parametry dotazu

Dotaz přijímá několik parametrů na adrese URL při volání s vlastnostmi GET a as JSON v textu požadavku při volání metody POST. Syntaxe některých parametrů je mírně odlišná mezi GET a POST. Tyto rozdíly jsou uvedeny níže.

Odpověď

Stavový kód: Pro úspěšnou odpověď se vrátí 200 OK.

  {
    "@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)
  }

Příklady

Další příklady najdete v syntaxi výrazů OData pro Azure Cognitive Search.

1. Vyhledejte Index seřazený sestupně podle data:

   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. Ve vyhledávání s omezením vlastností vyhledejte index a načtěte facety kategorií, hodnocení, značek a také položek s baseRate v konkrétních rozsahech.

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

   Všimněte si, že poslední facet je u dílčího pole. Facets počítá nadřazený dokument (Hotels) a ne meziprostřední dílčí dokumenty (místnosti), takže odpověď určí počet hotely, které mají v každém cenovém kbelíku nějaké místnosti.

3. Pomocí filtru zužte předchozí výsledek dotazu s facetedem poté, co uživatel vybere Hodnocení 3 a kategorii "Nachytá".

   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. Ve vyhledávání s omezujícími vlastnostmi nastavte horní limit jedinečných termínů vrácených v dotazu. Výchozí hodnota je 10, ale tuto hodnotu můžete zvýšit nebo snížit pomocí parametru count u atributu facet. Tento příklad vrátí facets pro city omezené na 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. Prohledání indexu v konkrétních polích (například v poli jazyka):

   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. Prohledání indexu ve více polích Můžete například ukládat prohledávatelná pole a dotazovat se na je ve více jazycích, a to vše v rámci stejného indexu. Pokud ve stejném dokumentu existují současně anglické a francouzštiny popisy, můžete ve výsledcích dotazu vrátit libovolný nebo vše:

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

   Index můžete dotazovat pouze najednou. Nevytvářejte více indexů pro každý jazyk, pokud nemáte v plánu dotazovat se po jednom.

7. Stránkování – získání první stránky položek (velikost stránky je 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. Stránkování – získání druhé stránky položek (velikost stránky je 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. Načtení konkrétní sady polí:

   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. Načtení dokumentů odpovídajících určitému výrazu filtru:

    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. Vyhledejte index a vraťte fragmenty pomocí zvýrazněných náhotů:

    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. Prohledat index a vrátit dokumenty seřazené z bližšího umístění od referenčního umístění:

    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. Prohledat index za předpokladu, že existuje profil vyhodnocování s názvem "geo" se dvěma funkcemi vyhodnocování vzdálenosti, jednou definující parametr s názvem "currentLocation" a jedním definující parametr s názvem "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. Najděte dokumenty v indexu pomocí jednoduché syntaxe dotazů. Tento dotaz vrátí hotely, kde prohledávatelná pole obsahují termíny "komfort" a "umístění", ale ne "..."

    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

    Použití přepíše výchozí hodnotu , což searchMode=all searchMode=any znamená -motel "A NOT" místo "NEBO NOT". Bez získáte "NEBO NOT", který rozbalí místo toho, aby omezoval výsledky hledání, což může být pro některé uživatele searchMode=all countertuitní.

15. Vyhledejte dokumenty v indexu pomocí syntaxe dotazů Lucene). Tento dotaz vrátí hotels, kde pole kategorie obsahuje termín "budget" a všechna prohledávatelná pole obsahující frázi "recently zahodí". Dokumenty obsahující frázi "recently zahodí" jsou v důsledku výrazu boost value (3) seřazeny na vyšší úrovni.

    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. Najděte v indexu dokumenty a upřednostňte konzistentní vyhodnocování před nižší latencí. Tento dotaz vypočítá frekvence dokumentů napříč celým indexem a bude se snažit cílit na stejnou repliku pro všechny dotazy v rámci stejné "relace", což vám pomůže generovat stabilní a reprodukovatelné hodnocení.

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

Viz také

• Vytváření dotazů v Azure Cognitive Search
• Dotazy v Azure Cognitive Search
• Jak funguje fulltextové vyhledávání ve službě Azure Cognitive Search
• Syntaxe výrazů OData pro Azure vSearch
• Jednoduchá syntaxe dotazů v Azure Cognitive Search