Otomatik tamamlama (Azure AI Arama REST API'si)

Otomatik Tamamlama API'si, ikincil sorguda kullanmak üzere arama dizinindeki mevcut terimleri kullanarak kısmen yazılan bir sorgu girişini tamamlar. Örneğin, sorgu girişi ise"medic", bu terimler dizindeyse, Otomatik Tamamlama API'si "medicine" döndürür"medicare""medicaid". Arama altyapısı dahili olarak, Bir Öneri oluşturucu yapılandırılmış alanlarda eşleşen terimleri arar.

Hizmet istekleri için HTTPS gereklidir. Otomatik Tamamlama isteği GET veya POST yöntemleri kullanılarak oluşturulabilir.

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

POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?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 çok büyük sorgular üretir. Bu uygulamalar için, GET'den daha büyük filtrelere izin verdiği için HTTP POST 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ı ç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. Azure AI Araması için OData İfade söz dizimi.

URI Parametreleri

URL kodlama önerileri

GET REST API'sini doğrudan çağırırken BELIRLI sorgu parametrelerini URL ile kodlamayı unutmayın. Otomatik Tamamlama için URL kodlaması aşağıdaki sorgu parametreleri için gerekli olabilir:

• search
• $filter
• highlightPreTag
• highlightPostTag

URL kodlaması yalnızca bağımsız parametreler için önerilir. Tüm sorgu dizesini (öğesinden ?sonraki her şey) yanlışlıkla URL ile kodlarsanız istekler bozulacaktır.

Ayrıca, URL kodlaması yalnızca REST API'yi doğrudan GET kullanarak çağırırken gereklidir. POST kullanırken veya kodlamayı sizin için 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.

İstek Gövdesi

GET için: Yok.

POST için:

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "filter": "odata_filter_expression",
  "fuzzy": true | false (default),  
  "highlightPreTag": "pre_tag",  
  "highlightPostTag": "post_tag",  
  "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
  "search": "partial_search_input",  
  "searchFields": "field_name_1, field_name_2, ...",
  "suggesterName": "suggester_name",  
  "top": # (default 5)  
}  

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 alınmaktadır.

(1) Otomatik Tamamlamada belirsizlik sınırlamaları:

İlk olarak, aramadaki benzer parametreden farklı olarak düzenleme uzaklığı belirteç başına yalnızca bir karakter farkıyla sınırlıdır. Düzenleme uzaklığı bir karakterle sınırlandığında tüm aday eşleşmeleri bulunamaz, ancak kabul edilebilir bir performans düzeyi sağlamak için üst sınır gereklidir.

İkincisi, belirsiz adım kısmi belirteç genişletmesinden sonra gerçekleşir ve benzer eşleşmeler için yalnızca aynı dizin parçasındaki terimler dikkate alınır. Bu kısıtlama, tüm parçalar üzerinde benzer eşleşmelerin toplamını ortadan kaldırarak Otomatik Tamamlama API'sinin performansını artırır. Dizine daha fazla terim eklendikçe bu kısıtlama daha az fark edilir hale gelir ve her parça için benzer terim dağılımı elde edilir. Terimler eşit dağıtıldığı için, parça içindeki benzer eşleşmeler, dizinin tamamında benzer eşleşmelerin iyi bir tahminidir. Ancak, dizinin test veya prototip dizini gibi daha az terime sahip olması durumunda sonuçlar daha az olabilir ve bu da parçalar arasında eşit olmayan bir gösterimle sonuçlanabilir. Dizinlerin parçalara nasıl bölündüğü hakkında daha fazla bilgi için bkz. bölüm ve çoğaltma bileşimleri.

Yanıt

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

Yanıt yükünün iki özelliği vardır.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [
    {
      "text": "...",
      "queryPlusText": "..."
    },
    ...  
  ]
}  

Örnekler

Örnek 1: Kısmi arama girişinin varsayılan modla (oneTerm) olduğu 'washington medic' üç otomatik tamamlama önerisini alın:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}  

Yanıt:

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}  

Örnek 2: Kısmi arama girişinin ve autocompleteMode=twoTermsolduğu 'washington medic' üç otomatik tamamlama önerisini alın:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}  

Yanıt:

{    
  "value": [
    {
      "text": "medicaid insurance",
      "queryPlusText": "washington medicaid insurance"
    },
    {
      "text": "medicare plan",
      "queryPlusText": "washington medicare plan"
    },
    {
      "text": "medicine book",
      "queryPlusText": "washington medicine book"
    }
  ]
}  

Bir Otomatik Tamamlama işleminde suggesterName öğesinin gerekli olduğuna dikkat edin.

Ayrıca bkz.

• Dizine öneri oluşturucu ekleme
• Uygulamaya öneri ekleme veya otomatik tamamlama
• HTTP durum kodu