Belgeleri Ara (Azure AI Arama REST API'si)

  • Makale

Sorgu isteği, arama hizmetindeki tek bir dizinin belge koleksiyonunu hedefler. Eşleşme ölçütlerini tanımlayan parametreleri ve yanıtı şekillendiren parametreleri içerir. 2021-04-30-Preview API sürümünden başlayarak, dizin adını kullanmak yerine belirli bir dizini hedeflemek için bir dizin diğer adı da kullanabilirsiniz.

GET veya POST kullanabilirsiniz. Sorgu parametreleri GET istekleri için sorgu dizesinde ve POST istekleri için 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 kullanıyorsanız, "arama" eylemini URI parametresi olarak ekleyin.

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ığında istek URL'sinin uzunluğu 8 KB'ı aşamaz. Bu uzunluk genellikle çoğu uygulama için yeterlidir. Ancak, bazı uygulamalar özellikle OData filtre ifadeleri kullanıldığında büyük sorgular üretir. Bu uygulamalar için HTTP POST, GET'den daha büyük filtrelere izin verdiğinden daha iyi bir seçimdir.

POST ile, post için istek boyutu sınırı yaklaşık 16 MB olduğundan, filtredeki yan tümcelerin sayısı ham filtre dizesinin boyutu değil sınırlayıcı faktördür. POST isteği boyut sınırı 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. Azure AI Search için OData İfade söz dizimi.

URI Parametreleri

Parametre Açıklama
[hizmet adı] Gereklidir. Bunu arama hizmetinizin benzersiz, kullanıcı tanımlı adı olarak ayarlayın.
[dizin adı]/docs Gereklidir. Adlandırılmış dizinin belge koleksiyonunu belirtir.
[sorgu parametreleri] Sorgu parametreleri GET istekleri için URI'de ve POST istekleri için istek gövdesinde belirtilir.
api-sürümü Gereklidir. Geçerli kararlı sürüm: api-version=2020-06-30. Daha fazla sürüm için bkz. API sürümleri. Sorgular için api sürümü her zaman GET ve POST için bir URI parametresi olarak belirtilir.

URL kodlama önerileri

GET REST API'sini doğrudan çağırırken URL kodlamaya özgü sorgu parametrelerini unutmayın. Arama Belgeleri işlemi için, aşağıdaki sorgu parametreleri için URL kodlaması gerekli olabilir:

  • search
  • $filter
  • facet
  • highlightPreTag
  • highlightPostTag

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

Ayrıca, URL kodlaması yalnızca REST API'yi doğrudan GET kullanarak çağırırken gereklidir. POST kullanırken veya sizin için kodlamayı işleyen Azure AI Search .NET istemci kitaplığını kullanırken URL kodlaması gerekmez.

İstek Üst Bilgileri

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

Alanlar Description
İçerik Türü Gereklidir. Bunu "application/json" olarak ayarlayın
api-key İsteğe bağlı olarak Azure rollerini kullanıyorsanız ve istekte taşıyıcı belirteci sağlanıyorsa bir anahtar gereklidir. Api anahtarı, arama hizmetinizde isteğin kimliğini doğrulayan benzersiz, sistem tarafından oluşturulan bir dizedir. Belge koleksiyonuna yönelik sorgu istekleri, API anahtarı olarak bir admin-key veya query-key belirtebilir. Sorgu anahtarı, belge koleksiyonunda salt okunur işlemler için kullanılır. Ayrıntılar için bkz. Anahtar kimlik doğrulamasını kullanarak Azure AI Search'e bağlanma .

İ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 Devamı

Bazen Azure AI Search tek bir Arama yanıtında istenen tüm sonuçları döndüremez. Sorgunun çok büyük bir değer $top belirtmeyerek veya belirtmeyerek $top çok fazla belge istemesi gibi farklı nedenlerle bu durum oluşabilir. Böyle durumlarda, Azure AI Search yanıt gövdesinde ek açıklamayı @odata.nextLink ve ayrıca @search.nextPageParameters bir POST isteği olup olmadığını içerir. Arama yanıtının bir sonraki bölümünü almak üzere başka bir Arama isteği formüle etmek için bu ek açıklamaların değerlerini kullanabilirsiniz. Bu, özgün Arama isteğinin devamı olarak adlandırılır ve ek açıklamalar genellikle devamlılık belirteçleri olarak adlandırılır. Bu ek açıklamaların söz dizimi ve yanıt gövdesinde nerede göründükleri hakkında ayrıntılı bilgi için aşağıdaki Yanıt bölümündeki örneklere bakın.

Azure AI Search'in devamlılık belirteçleri döndürmesinin nedenleri uygulamaya özgü olup değiştirilebilir. Sağlam istemciler, beklenenden daha az belgenin döndürüldüğü ve belgeleri almaya devam etmek için bir devamlılık belirtecinin eklendiği durumları işlemeye her zaman hazır olmalıdır. Devam etmek için özgün istekle aynı HTTP yöntemini kullanmanız gerektiğini de unutmayın. Örneğin, bir GET isteği gönderdiyseniz, gönderdiğiniz devam istekleri get (ve benzer şekilde POST için) kullanmalıdır.

Not

ve'nin @odata.nextLink@search.nextPageParameters amacı, hizmeti çok fazla sonuç isteyen sorgulardan korumaktır, disk belleği için genel bir mekanizma sağlamak değildir. Sonuçlarda sayfalandırmak istiyorsanız ve $skip öğesini birlikte kullanın$top. Örneğin, 10 boyutlu sayfalar istiyorsanız, ilk isteğinizin ve olması gerekir $top=10$top=10. İkinci istekte ve $skip=10olmalıdır, üçüncü istekte ve $skip=20vb. olmalıdır$top=10.$skip=0

Sorgu Parametreleri

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

Ad Tür Description
api-sürümü string Gereklidir. İstek için kullanılan REST API sürümü. Desteklenen sürümlerin listesi için bkz. API sürümleri. Bu işlem için, GET veya POST ile Arama Belgeleri'ni çağırmanıza bakılmaksızın api-version bir URI parametresi olarak belirtilir.
$count boolean İsteğe bağlı. Geçerli değerler "true" veya "false" değerleridir. Varsayılan olarak "false" kullanılır. POST ile çağrıldığında, bu parametre yerine count $countolarak adlandırılır. Toplam sonuç sayısının getirilip getirilmeyeceğini belirtir. Bu, ve yok sayılarak $top$skiparama ve $filter parametreleriyle eşleşen tüm belgelerin sayısıdır. Bu değeri "true" olarak ayarlamak performansı düşürebilir. Dizin kararlıysa sayı doğrudur, ancak etkin olarak eklenen, güncelleştirilen veya silinen belgelerin altında veya üzerinde rapor oluşturur. Herhangi bir belge olmadan yalnızca sayıyı almak isterseniz =0 kullanabilirsiniz $top.
model veya modeller string İsteğe bağlı. Alanın "modellenebilir" olarak ilişkilendirildiği modele göre bir alan. GET ile çağrıldığında bir facet alan (facet: field1 olur). POST ile çağrıldığında, bu parametre yerine facet adlandırılır facets ve bir dizi (facets: [field1, field2, field3] olarak belirtilir). Dize, modeli özelleştirmek için virgülle ayrılmış ad-değer çiftleri olarak ifade edilen parametreler içerebilir.

Geçerli parametreler şunlardır: "count", "sort", "values", "interval" ve "timeoffset".

"count", model terimlerinin maksimum sayısıdır; varsayılan değer 10'dur. Terim sayısında üst sınır yoktur, ancak özellikle çok sayıda benzersiz terim içeren büyük değerler performansı düşürür. Örneğin, "facet=category,count:5" model sonuçlarında ilk beş kategoriyi alır. Count parametresi benzersiz terimlerin sayısından küçükse sonuçlar doğru olmayabilir. Bunun nedeni, yüz tanıma sorgularının parçalar arasında dağıtılmasıdır. Tüm parçalar arasında doğru bir sayı elde etmek için, sayıyı sıfıra veya modellenebilir alandaki benzersiz değer sayısından büyük veya buna eşit bir değere ayarlayabilirsiniz. Dezavantaj, gecikme süresini artırır.

"sort" "count", "-count", "value", "-value" olarak ayarlanabilir. Sayıya göre azalan düzende sıralamak için sayıyı kullanın. Sayıya göre artan düzende sıralamak için -count kullanın. Değere göre artan düzende sıralamak için değeri kullanın. Değere göre azalan düzende sıralamak için -value kullanın (örneğin, "model=kategori,sayı:3,sort:count", model sonuçlarında ilk üç kategoriyi her şehir adına sahip belge sayısına göre azalan düzende alır). İlk üç kategori Budget, Motel ve Luxury, Budget ise 5 hit, Motel 6, Luxury ise 4 ise, kovalar Motel, Budget, Luxury sırasındadır. -value için, "facet=rating,sort:-value" tüm olası derecelendirmeler için değerlere göre azalan düzende demetler üretir (örneğin, derecelendirmeler 1 ile 5 arasındaysa, demetler her derecelendirmeyle eşleşen belge sayısına bakılmadan 5, 4, 3, 2, 1 sıralanır).

"değerler", dinamik bir model giriş değerleri kümesi belirten kanalla ayrılmış sayısal veya Edm.DateTimeOffset değerlerine ayarlanabilir (örneğin, "facet=baseRate,values:10 | 20" üç demet üretir: biri 0'a kadar taban hız için, ancak 10 dahil değildir, biri 10'a kadar ama 20'yi değil, biri de 20 ve üzeri için). "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" dizesi iki demet üretir: biri Şubat 2010'den önce yenilenmiş oteller için, biri de 1 Şubat 2010 veya sonraki bir tarihte yenilenmiş oteller için. Beklenen sonuçları almak için değerlerin sıralı ve artan sırada listelenmesi gerekir.

"interval", sayılar için 0'dan büyük bir tamsayı aralığıdır veya tarih saat değerleri için dakika, saat, gün, hafta, ay, çeyrek, yıl. Örneğin, "facet=baseRate,interval:100", 100 boyutundaki temel hız aralıklarına göre demetler üretir. Taban ücretlerin tümü 60 ile 600 ABD doları arasındaysa, 0-100, 100-200, 200-300, 300-400, 400-500 ve 500-600 için demetler olacaktır. "facet=lastRenovationDate,interval:year" dizesi, oteller yenilendiğinde her yıl için bir kova üretir.

"timeoffset" ([+-]ss:mm, [+-]ssmm veya [+-]ss) olarak ayarlanabilir. Kullanılırsa, timeoffset parametresi aralık seçeneğiyle ve yalnızca Edm.DateTimeOffset türünde bir alana uygulandığında birleştirilmelidir. değeri, saat sınırlarını ayarlarken hesaba katmak için UTC saat uzaklığını belirtir. Örneğin: "facet=lastRenovationDate,interval:day,timeoffset:-01:00", 01:00:00 UTC'de (hedef saat diliminde gece yarısı) başlayan gün sınırını kullanır.

sayı ve sıralama aynı model belirtiminde birleştirilebilir, ancak bunlar aralık veya değerlerle birleştirilemiyor ve aralık ve değerler birlikte birleştirilemiyor.

Tarih saat dilimindeki aralık modelleri, timeoffset belirtilmezse UTC saati temelinde hesaplanır. Örneğin: "facet=lastRenovationDate,interval:day" için gün sınırı 00:00:00 UTC'de başlar.
$filter string İsteğe bağlı. Standart OData söz diziminde yapılandırılmış bir arama ifadesi. Filtrede yalnızca filtrelenebilir alanlar kullanılabilir. POST ile çağrılırken, bu parametre $filter yerine filtre olarak adlandırılır. Azure AI Search'ün desteklediği OData ifadesi dil bilgisi alt kümesiyle ilgili ayrıntılar için bkz. Azure AI Search için OData İfade Söz Dizimi.
Vurgula -mak string İsteğe bağlı. İsabet vurgulamaları için kullanılan virgülle ayrılmış alan adları kümesi. Yalnızca isabet vurgulama için aranabilir alanlar kullanılabilir. Varsayılan olarak, Azure AI Search alan başına en fazla 5 vurgu döndürür. Alan adının sonuna "-<max # of highlights>" eklenerek alan başına sınır yapılandırılabilir. Örneğin, "highlight=title-3,description-10", başlık alanından en fazla 3 vurgulanmış isabet ve açıklama alanından en fazla 10 isabet döndürür. Vurgu sayısı üst sınırı 1 ile 1000 (dahil) arasında bir tamsayı olmalıdır.
highlightPostTag string İsteğe bağlı. varsayılan olarak "</em>"ayarlanır. Vurgulanan terime eklenen bir dize etiketi.. highlightPreTag ile ayarlanmalıdır. URL'deki ayrılmış karakterler yüzde kodlanmış olmalıdır (örneğin, #yerine %23).
highlightPreTag string İsteğe bağlı. varsayılan olarak "</em>"ayarlanır. Vurgulanan terime ön ekleyen bir dize etiketi. highlightPostTag ile ayarlanmalıdır. URL'deki ayrılmış karakterler yüzde kodlanmış olmalıdır (örneğin, #yerine %23).
minimumCoverage tamsayı İsteğe bağlı. Geçerli değerler 0 ile 100 arasında bir sayıdır ve başarılı olarak bildirilmeden önce sorguya hizmet vermek için kullanılabilir olması gereken dizinin yüzdesini gösterir. Varsayılan olarak "100" olur.

Yüzde yüz kapsam, tüm parçaların isteğe yanıt verdiği anlamına gelir (hizmet durumu sorunları veya bakım etkinlikleri kapsamı azaltılmış değildir). Varsayılan ayarın altında, tam kapsam dışında http durum kodu 503 döndürülüyor.

503 hata oluşuyorsa ve özellikle tek bir çoğaltma için yapılandırılmış hizmetler için sorgu başarısı olasılığını artırmak istiyorsanız minimumCoverage değerinin düşürülmesini sağlamak yararlı olabilir. minimumCoverage değerini ayarlarsanız ve Arama başarılı olursa HTTP 200 döndürür ve yanıta sorguya dahil edilen dizinin yüzdesini gösteren bir @search.coverage değer ekler. Bu senaryoda, eşleşen tüm belgelerin arama sonuçlarında bulunacağı garanti edilmez, ancak arama kullanılabilirliği geri çağırmaktan daha önemliyse kapsamı azaltmak uygulanabilir bir azaltma stratejisi olabilir.
$orderby string İsteğe bağlı. Sonuçları sıralamak için virgülle ayrılmış ifadelerin listesi. POST ile çağrıldığında, bu parametre $orderby yerine orderby olarak adlandırılır. Her ifade bir alan adı veya geo.distance() işlevine yapılan çağrı olabilir. Her ifadeyi artanı belirtmek için "asc" ve azalanı belirtmek için "desc" takip edebilir. Sıralama alanında null değerler varsa, null değerler önce artan düzende, son değerler ise azalan düzende görüntülenir. Varsayılan değer artan düzendir. Bağlar, belgelerin maç skorlarıyla bozulur. Hiçbir $orderby belirtilmezse, varsayılan sıralama düzeni belge eşleştirme puanına göre azalan düzendedir. $orderby için 32 yan tümce sınırı vardır.
Querytype string İsteğe bağlı. Geçerli değerler "basit" veya "dolu" değerleridir. Varsayılan olarak "basit" olur.

"simple", ve gibi +*""simgelere izin veren basit sorgu söz dizimini kullanarak sorgu dizelerini yorumlar. Sorgular varsayılan olarak her belgedeki tüm aranabilir alanlar (veya searchField'lerde belirtilen alanlar) arasında değerlendirilir.

"full", alana özgü ve ağırlıklı aramalara olanak tanıyan tam Lucene sorgu söz dizimini kullanarak sorgu dizelerini yorumlar. Lucene sorgu dilindeki aralık araması, benzer işlevler sunan $filter tarafından desteklenmez.
scoringParameter string İsteğe bağlı. "name-value1,value2" biçimini kullanarak bir puanlama işlevinde (referencePointParameter gibi) tanımlanan her parametrenin değerlerini gösterir,... POST ile çağrıldığında, bu parametre scoringParameters yerine scoringParameters olarak adlandırılır. Ayrıca, her dizenin ayrı bir ad-değer çifti olduğu dizelerin JSON dizisi olarak belirtirsiniz.

İşlev içeren puanlama profilleri için, işlevi giriş listesinden bir - karakterle ayırın. Örneğin, adlı "mylocation" bir işlev "&scoringParameter=mylocation--122.2,44.8" olabilir. İlk tire işlev adını değer listesinden ayırırken, ikinci tire ilk değerin bir parçasıdır (bu örnekte boylam).

Virgül içerebilen etiket artırma gibi puanlama parametreleri için, tek tırnak işaretleri kullanarak listedeki bu tür değerlerden kaçabilirsiniz. Değerlerin kendileri tek tırnak içeriyorsa, iki katına çıkararak bu değerlerden kaçabilirsiniz. adlı "mytag" bir etiket artırma parametreniz olduğunu ve "Hello, O'Brien" ve "Smith" etiket değerlerini artırmak istediğinizi varsayalım; sorgu dizesi seçeneği "&scoringParameter=mytag-'Hello, O''Brien',Smith" olur. Tırnak işaretleri yalnızca virgül içeren değerler için gereklidir.
scoringProfile string İsteğe bağlı. Sonuçları sıralamak için eşleşen belgeler için eşleşme puanlarını değerlendirmek için bir puanlama profilinin adı.
scoringStatistics string İsteğe bağlı. Geçerli değerler "yerel" veya "genel" değerlerdir. Varsayılan olarak "yerel" olarak ayarlanır. Daha tutarlı puanlama için belge sıklığı gibi puanlama istatistiklerinin genel olarak mı (tüm parçalar arasında) yoksa daha düşük gecikme süresi için yerel olarak mı (geçerli parçada) hesaplanıp hesaplanmayacağını belirtin. Bkz . Azure AI Arama'da Puanlama İstatistikleri. Benzer arama ('~') kullanan terimler için puanlama istatistikleri her zaman yerel olarak hesaplanır.
search string İsteğe bağlı. Aranacak metin. SearchFields belirtilmediği sürece tüm aranabilir alanlar varsayılan olarak aranabilir. Dizinde, aranabilir bir alandaki metin belirteç haline getirildiğinden, birden çok terim boşlukla ayrılabilir (örneğin: 'search=hello world'). Herhangi bir terimi eşleştirmek için kullanın * (boole filtresi sorguları için yararlı olabilir). Bu parametrenin atlanması, parametresini olarak ayarlamakla *aynı etkiye sahiptir. Arama söz diziminde ayrıntılar için bkz. Basit sorgu söz dizimi.

Arama yapılabilir alanlar üzerinde sorgu yapıldığında sonuçlar bazen şaşırtıcı olabilir. Belirteç oluşturucu, kesme işaretleri, sayılardaki virgüller gibi İngilizce metinlerde yaygın olan durumları işleme mantığını içerir. Örneğin, 'search=123.456', '123' ve '456' terimleri yerine tek bir '123.456' terimiyle eşleşecektir, çünkü virgüller İngilizcedeki büyük sayılar için binlik ayırıcı olarak kullanılır. Bu nedenle, arama parametresindeki terimleri ayırmak için noktalama işareti yerine boşluk kullanmanızı öneririz.
searchMode string İsteğe bağlı. Geçerli değerler "any" veya "all" Varsayılanları "any" olur. Belgeyi eşleşme olarak saymak için arama terimlerinden herhangi birinin veya tümünün eşleşmesi gerekip gerekmediğini belirtir.
searchFields string İsteğe bağlı. Belirtilen metni aramak için virgülle ayrılmış alan adlarının listesi. Hedef alanlar dizin şemasında aranabilir olarak işaretlenmelidir.
$select string İsteğe bağlı. Sonuç kümesine eklenecek virgülle ayrılmış alanların listesi. Bu yan tümceye yalnızca alınabilir olarak işaretlenmiş alanlar eklenebilir. Belirtilmemişse veya olarak *ayarlanırsa, şemada alınabilir olarak işaretlenmiş tüm alanlar projeksiyona eklenir. POST ile çağrıldığında, bu parametre $select yerine select olarak adlandırılır.
Sessionıd string İsteğe bağlı. sessionId kullanmak, birden çok çoğaltmaya sahip arama hizmetleri için ilgi puanı tutarlılığını artırmaya yardımcı olur. Çok çoğaltmalı yapılandırmalarda, aynı sorgu için tek tek belgelerin ilgi puanları arasında küçük farklılıklar olabilir. Oturum kimliği sağlandığında, hizmet belirli bir isteği bu oturum için aynı çoğaltmaya yönlendirmek için en iyi çabayı gösterir. Aynı oturum kimliği değerlerini tekrar tekrar yeniden kullanmanın çoğaltmalar arasında isteklerin yük dengelemesini engelleyeceğine ve arama hizmetinin performansını olumsuz etkileyebileceğine dikkat edin. sessionId olarak kullanılan değer '_' karakteriyle başlayamaz. Bir hizmetin çoğaltması yoksa, bu parametrenin performans veya puan tutarlılığı üzerinde hiçbir etkisi yoktur.
$skip tamsayı İsteğe bağlı. Atlana arama sonuçlarının sayısı. POST ile çağrıldığında, bu parametre yerine $skipskip olarak adlandırılır. Bu değer 100.000'den büyük olamaz. Belgeleri sırayla taramanız gerekiyorsa ancak bu sınırlama nedeniyle kullanamıyorsanız $skip , dizindeki her belge için benzersiz değerlere sahip bir alanda (örneğin, belge anahtarı gibi) $orderby kullanmayı ve bunun yerine bir aralık sorgusuyla $filter düşünün.
$top tamsayı İsteğe bağlı. Alınacak arama sonuçlarının sayısı. Bu, varsayılan olarak 50'ye ayarlanır. POST ile çağrıldığında, bu parametre yerine $toptop olarak adlandırılır. 1000'den büyük bir değer belirtirseniz ve 1000'den fazla sonuç varsa, yalnızca ilk 1000 sonuç döndürülür ve sonraki sonuç sayfasına bağlantı verilir (aşağıdaki örnekte bakın @odata.nextLink ).

Azure AI Search, sorguların aynı anda çok fazla belge almasını önlemek için sunucu tarafı sayfalama kullanır. Varsayılan sayfa boyutu 50, maksimum sayfa boyutu ise 1000'dir. Bu, belirtmezseniz$top, Varsayılan olarak Arama Belgeleri'nin en fazla 50 sonuç döndürdüğü anlamına gelir. 50'den fazla sonuç varsa, yanıt en fazla 50 sonucun sonraki sayfasını almaya yönelik bilgiler içerir (aşağıdaki Örneklerde "@odata.nextLink" ve "@search.nextPageParameters" bölümüne bakın. Benzer şekilde, için $top 1000'den büyük bir değer belirtirseniz ve 1000'den fazla sonuç varsa, yalnızca ilk 1000 sonuç döndürülür ve en fazla 1000 sonucun sonraki sayfasını almaya yönelik bilgiler verilir.

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 AI Araması için OData İfade Söz Dizimi'nde daha fazla örnek bulabilirsiniz.

  1. Dizinde tarihe göre azalan sıralamada arama:

    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 belirli aralıklarda baseRate içeren kategoriler, derecelendirmeler, etiketler ve öğeler için modelleri 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 model bir alt alandadır. Modeller ara alt belgeleri (Odalar) değil üst belgeyi (Oteller) sayar, bu nedenle yanıt, her fiyat demetinde herhangi bir odası olan otel sayısını belirler.

  3. Filtre kullanarak, kullanıcı Derecelendirme 3 ve "Motel" kategorisini seçtikten sonra önceki çok yönlü 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 terimler için üst sınır ayarlayın. Varsayılan değer 10'dur, ancak model özniteliğindeki count parametresini kullanarak bu değeri artırabilir veya azaltabilirsiniz. Bu örnek, 5 ile sınırlı olan şehir modellerini döndürü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. Belirli alanlarda (örneğin, bir dil alanı) dizinde arama yapın:

    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. Birden çok alanda Dizin'de arama. Örneğin, aranabilir alanları aynı dizin içinde birden çok dilde depolayabilir ve sorgulayabilirsiniz. İngilizce ve Fransızca açıklamalar aynı belgede birlikte varsa, sorgu sonuçlarından 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"
    }

    Aynı anda yalnızca dizin sorgulayabilirsiniz. Tek tek sorgulamayı planlamadığınız sürece her dil için birden çok dizin oluşturmayın.

  7. Sayfalama - Öğelerin ilk sayfasını alın (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 alma:

    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ın:

    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 ve isabet vurgulamalarıyla parçaları döndürme:

    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ıp başvuru konumundan daha yakına doğru sıralanmış belgeleri döndür:

    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. biri "currentLocation" adlı bir parametre, diğeri de "lastLocation" adlı bir parametre tanımlayan iki uzaklık puanlama işlevine sahip "geo" adlı bir puanlama profili olduğunu varsayarak dizinde arama yapın. Aşağıdaki örnekte, "currentLocation" tek bir tire (- ) sınırlayıcıya sahiptir. Bunu boylam ve enlem koordinatları izler ve boylam negatif bir değerdir.

    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 dizindeki belgeleri bulun. Bu sorgu, aranabilir alanların "konfor" ve "konum" terimlerini içerdiği ancak "motel" terimlerini içermediği otelleri 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

    kullanımı searchMode=all varsayılanını searchMode=anygeçersiz kılar ve bunun -motel "VEYA NOT" yerine "VE NOT" anlamına gelir. olmadan searchMode=all, arama sonuçlarını kısıtlamak yerine genişleyen "VEYA NOT" elde edersiniz ve bu bazı kullanıcılar için sezgisel olabilir.

  15. Lucene sorgu söz dizimini kullanarak dizindeki belgeleri bulun). Bu sorgu, kategori alanının "bütçe" terimini ve "yakın zamanda yenilendi" tümceciği içeren tüm aranabilir alanları içerdiği otelleri döndürür. "Yakın zamanda yenilendi" ifadesini içeren belgeler, yükseltme değeri teriminin sonucu olarak daha yüksek sıralanır (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. Daha düşük gecikme süresine göre tutarlı puanlama tercihi yaparken dizindeki belgeleri bulun. Bu sorgu tüm dizin genelinde belge sıklıklarını hesaplar ve aynı "oturum" içindeki tüm sorgular için aynı çoğaltmayı hedeflemek için en iyi çabayı gösterir ve bu da kararlı ve yeniden üretilebilir bir derecelendirme oluşturmaya yardımcı olur.

    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.