Belgeleri Ara (Azure Bilişsel Arama REST API)

Sorgu isteği, arama hizmeti üzerinde tek bir dizinin belge koleksiyonunu hedefler. Eşleşme ölçütlerini tanımlayan parametreleri ve yanıtı şekillendiren parametreleri içerir.

GET veya POST kullanabilirsiniz. SORGU parametreleri, GET istekleri durumunda sorgu dizesinde ve POST istekleri durumunda istek gövdesinde belirtilir.

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]  

GET ile çağrıldıklarda, istek URL'sinin uzunluğu 8 KB'yi aşamaz. Bu uzunluk genellikle çoğu uygulama için yeterlidir. Ancak, bazı uygulamalar özellikle OData filtre ifadeleri kullanılırken çok büyük sorgular üretir. BU uygulamalar için HTTP POST, GET'den daha büyük filtrelere izin verir.

POST ile, POST için istek boyutu sınırı yaklaşık 16 MB olduğu için filtrede yer alan yan tümce sayısı ham filtre dizesinin boyutunu değil sınırlayıcı faktördür. POST isteği boyut sınırı çok büyük olsa da filtre ifadeleri rastgele karmaşık olamaz. Filtre karmaşıklığı sınırlamaları hakkında daha fazla bilgi için bkz. OData İfade söz dizimi Azure Bilişsel Arama.

URI Parametreleri

URL kodlama önerileri

GET çağrılarını doğrudan çağıran belirli sorgu parametrelerini URL ile kodlamayı REST API unutmayın. Belge Ara işlemi için url kodlaması aşağıdaki sorgu parametreleri için gerekli olabilir:

• search
• $filter
• facet
• highlightPreTag
• highlightPostTag

URL kodlaması yalnızca tek tek parametreler için önerilir. Sorgu dizesinin tamamını yanlışlıkla URL ile kodlarsanız (sonrasındaki her ? şey) istekler kes.

Ayrıca URL kodlaması yalnızca get kullanarak doğrudan REST API çağrılır. POST kullanırken veya kodlamayı sizin için Azure Bilişsel Arama .NETistemci kitaplığını kullanırken URL kodlaması gerekmez.

İstek Üst Bilgileri

Aşağıdaki tabloda gerekli ve isteğe bağlı istek üst bilgileri açıklanmıştır.

İstek Gövdesi

GET için: Yok.

POST için:

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

Kısmi Arama Yanıtlarının Devamlılığı

Bazen Azure Bilişsel Arama, istenen tüm sonuçları tek bir Arama yanıtlarında geri getiremz. Bu durum, sorgunun çok fazla belge isteği göndererek çok fazla belge $top veya çok büyük olan $top bir değer belirtme gibi farklı nedenlerle oluşabilir. Böyle durumlarda, Azure Bilişsel Arama ek açıklamasını yanıt gövdesine ve bir POST isteği olup @odata.nextLink @search.nextPageParameters olamayacak şekilde içerecektir. Arama yanıtının sonraki kısmını almak üzere başka bir Arama isteği formüle etmek için bu ek açıklamaların değerlerini kullanabilirsiniz. Buna özgün Arama isteğinin devamlılığı denir ve ek açıklamalar genellikle devamlılık belirteçleri olarak da ifade edilir. Bu ek açıklamaların söz dizimi ve yanıt gövdesinde nerede görünecekleri hakkında ayrıntılı bilgi için aşağıdaki Yanıt örneğine bakın.

Süreklilik belirteçlerini Azure Bilişsel Arama nedenlerinden biri uygulamaya özgü ve değişebilir. Sağlam istemciler, beklenenden daha az belgenin döndürüleceği ve belgeleri almaya devam etmek için bir devamlılık belirtecinin dahil olduğu durumlara her zaman hazır olması gerekir. Ayrıca devam etmek için özgün istekle aynı HTTP yöntemini kullan gerektiğini unutmayın. Örneğin, bir GET isteği gönderdiyebilirsiniz, gönderilen tüm devamlılık istekleri de GET (ve benzer şekilde POST için) kullan gerekir.

Sorgu Parametreleri

Sorgu, GET ile çağrıldıklarında URL'de çeşitli parametreleri ve POST ile çağrıldıklarında istek gövdesinde JSON özellikleri olarak kabul eder. Bazı parametrelerin söz dizimi GET ile POST arasında biraz farklıdır. Bu farklılıklar aşağıda geçerli olduğu gibi not almaktadır.

Yanıt

Durum kodu: başarılı bir yanıt için 200 Tamam döndürülür.

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

Örnekler

Azure bilişsel arama Için OData Ifade sözdizimindeek örnekler bulabilirsiniz.

1. Dizine göre azalan düzende sıralanan dizinde ara:

   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. Çok yönlü bir aramada, dizinde arama yapın ve kategorilerin, derecelendirmelerin, etiketlerin yanı sıra belirli aralıklarda Baserine sahip öğelerin modellerini alın.

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

   Son modelin bir alt alanda olduğunu unutmayın. Modeller, ana belgeyi (oteller) değil, ara alt belgeleri (Odalar) değil, bu nedenle yanıt her bir fiyat demeti içinde herhangi bir odaya sahip olan oteller sayısını saptacaktır.

3. Filtre kullanarak, Kullanıcı derecelendirme 3 ' ü ve "Motel" kategorisini seçtikten sonra, çok yönlü olan önceki sorgu sonucunu daraltın.

   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. Çok yönlü bir aramada, sorguda döndürülen benzersiz şartlar üzerinde üst sınır ayarlayın. Varsayılan değer 10 ' dur, ancak model özniteliğinde Count parametresini kullanarak bu değeri artırabilir veya azaltabilirsiniz. Bu örnek, şehir için model döndürür ve 5 ile sınırlıdır.

   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. Dizinde belirli alanlar içinde arama yapın (örneğin, bir dil alanı):

   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. Dizinde birden çok alanda arama yapın. Örneğin, aranabilir alanları, hepsi aynı dizin içinde birden çok dilde depolayıp sorgulayabilirsiniz. Aynı belgede Ingilizce ve Fransızca açıklamaları birlikte mevcutsa, sorgu sonuçlarında herhangi birini veya tümünü döndürebilirsiniz:

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

   Tek seferde yalnızca dizin sorgulayabilirsiniz. Tek seferde bir tane sorgulamayı planlamıyorsanız, her dil için birden çok dizin oluşturmayın.

7. Sayfalama-öğelerin ilk sayfasını al (sayfa boyutu 10 ' dur):

   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. Sayfalama-öğelerin ikinci sayfasını alın (sayfa boyutu 10 ' dur):

   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. Belirli bir alan kümesini al:

   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. Belirli bir filtre ifadesiyle eşleşen belgeleri al:

    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. Dizinde arama yapın ve isabet noktaları ile dönüş parçaları:

    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. Dizinde arama yapın ve bir başvuru konumundan daha yakın bir yere sıralanmış olan belgeleri geri döndürü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. "CurrentLocation" adlı bir parametreyi ve diğeri "lastLocation" adlı bir parametreyi tanımlayan iki mesafe Puanlama işlevleriyle "coğrafi" olarak adlandırılan bir Puanlama profili olduğunu varsayarak dizinde arama yapın:

    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. Basit sorgu söz dizimini kullanarak dizinde belge bulun. Bu sorgu, aranabilir alanların "rakip" ve "konum" terimlerini içerdiği ancak "Motel" olarak değil, oteller döndürür:

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

    İpucu

    Öğesinin searchMode=all varsayılan değerini geçersiz kılar searchMode=any , -motel bunun yerıne "veya Not" DEĞIL "ve değil" anlamına gelir. Olmadan searchMode=all , arama sonuçlarını kısıtlamadan önce genişleyen "veya Not" alırsınız ve bu, bazı kullanıcılar için sayaç sezgisel olabilir.

15. Dizinde Lucene sorgu söz diziminikullanarak belge bulun. Bu sorgu, Kategori alanının "bütçe" terimini ve "son randevu" ifadesini içeren tüm aranabilir alanları içermesi halinde oteller döndürür. "Son randevu" ifadesini içeren belgeler, artırma değeri (3) sonucu olarak daha yüksek sıralanır

    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. Favoring, daha düşük gecikme süresine göre tutarlı Puanlama yaparken dizinde belge bulun. Bu sorgu, tüm dizinde belge sıklıklarını hesaplar ve tutarlı ve tekrarlanabilir bir sıralama oluşturmaya yardımcı olacak aynı "oturumdaki" tüm sorgular için aynı çoğaltmayı hedeflemek için en iyi çaba kullanacaktır.

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

Ayrıca bkz.

• Azure Bilişsel Arama sorgu oluşturma
• Azure Bilişsel Arama sorguları
• Azure Bilişsel Arama’da tam metin araması nasıl çalışır?
• Azure vSearch için OData Ifadesi söz dizimi
• Azure Bilişsel Arama basit sorgu söz dizimi