Öneriler (Azure AI Arama REST API'si)

Öneriler isteği, öneride bulunan alanlarda eşleşen değerleri arayan ve eşleşme içeren belgeler döndüren, yazarken arama sorgusudur. Örneğin, bir şehir alanında önerileri etkinleştirirseniz, "deniz" yazılması söz konusu alan için "Seattle", "Sea Tac" ve "Seaside" (tüm gerçek şehir adları) içeren belgeler üretir.

Yanıt, eşleşen bir belgenin içeriği ve belge anahtarıdır. İkincil sorguda kullanılan tamamlanmış bir terimi veya tümceciği döndüren Otomatik Tamamlama'nın aksine, bu istek gerçek belgelere çözümlenen bilgileri döndürür. Eşleşen terimler veya tümcecikler belgeler arasında aynıysa, eşleşen içerik yinelenir. Sonuçların yapısını geliştirmek için filtreyi $select kullanarak daha fazla farklılaşma ve bağlam sağlayan ek alanlar döndürebilirsiniz.

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

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

POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]  

Arama Belgeleri isteğinin aksine, klavye girişine Bir Öneriler çağrısı bağlayabilirsiniz, arama ise tıklama olayına bağlı olabilir.

GET ile çağrıldığında, 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ıldığında çok 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ı ç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 Search için OData İfade söz dizimi.

URI Parametreleri

URL kodlama önerileri

GET REST API'sini doğrudan çağırırken URL kodlamaya özgü sorgu parametrelerini unutmayın. Öneriler işlemleri için bunlar şunları içerir:

• search
• $filter
• 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 kullanarak Öneriler çağrılırken veya Azure AI Search .NET istemci kitaplığı kullanılırken URL kodlaması sizin için gerekli değildir.

İ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:

{  
      "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),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "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 edilir.

Yanıt

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

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

Alanları almak için projeksiyon seçeneği kullanılırsa, bunlar dizinin her öğesine eklenir:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}  

Örnekler

Kısmi arama girişinin 'lux' olduğu 5 öneriyi alın:

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30 

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }  

Öneri işleminde suggesterName'in gerekli olduğuna dikkat edin.

Ayrıca bkz.

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