Saran (Azure Cognitive Search REST API)

Permintaan Saran adalah kueri search-as-you-type yang mencari nilai yang cocok di bidang yang mengetahui saran dan mengembalikan dokumen yang berisi kecocokan. Misalnya, jika Anda mengaktifkan saran di bidang kota , mengetik "laut" menghasilkan dokumen yang berisi "Seattle", "Sea Tac", dan "Seaside" (semua nama kota aktual) untuk bidang tersebut.

Responsnya adalah konten dari dokumen yang cocok ditambah kunci dokumen. Berbeda dengan Lengkapi Otomatis, yang mengembalikan istilah atau frasa lengkap yang digunakan dalam kueri sekunder, permintaan ini mengembalikan informasi yang diselesaikan ke dokumen aktual. Jika istilah atau frasa yang cocok identik di seluruh dokumen, konten yang cocok akan diulang. Untuk meningkatkan struktur hasil, pertimbangkan untuk menggunakan $select filter untuk mengembalikan bidang tambahan yang memberikan lebih banyak diferensiasi dan konteks.

HTTPS diperlukan untuk permintaan layanan. Permintaan Saran dapat dibuat menggunakan metode GET atau POST.

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]  

Berbeda dengan permintaan Dokumen Pencarian , Anda mungkin mengikat panggilan Saran ke input keyboard, sedangkan panggilan Pencarian mungkin terikat ke peristiwa klik.

Ketika dipanggil dengan GET, panjang URL permintaan tidak boleh melebihi 8 KB. Panjang ini biasanya cukup untuk sebagian besar aplikasi. Namun, beberapa aplikasi menghasilkan kueri yang sangat besar, khususnya ketika ekspresi filter OData digunakan. Untuk aplikasi ini, HTTP POST adalah pilihan yang lebih baik karena memungkinkan filter yang lebih besar daripada GET.

Dengan POST, jumlah klausa dalam filter adalah faktor pembatas, bukan ukuran string filter mentah karena batas ukuran permintaan untuk POST adalah sekitar 16 MB. Meskipun batas ukuran permintaan POST sangat besar, ekspresi filter tidak dapat sangat kompleks. Untuk informasi selengkapnya tentang batasan kompleksitas filter, lihat Sintaks Ekspresi OData untuk Azure Cognitive Search.

Parameter URI

Parameter Deskripsi
[nama layanan] Wajib diisi. Atur ini ke nama unik yang ditentukan pengguna dari layanan pencarian Anda.
[nama indeks]/docs Wajib diisi. Menentukan kumpulan dokumen indeks bernama.
versi-api Wajib diisi. Versi stabil saat ini adalah api-version=2020-06-30. Lihat versi API untuk versi lainnya. Untuk kueri, versi api selalu ditentukan sebagai parameter URI untuk GET dan POST.

Rekomendasi pengodean URL

Ingatlah untuk mengodekan URL parameter kueri tertentu saat memanggil GET REST API secara langsung. Untuk operasi Saran , ini termasuk:

  • pencarian
  • $filter
  • highlightPreTag
  • highlightPostTag

Pengodean URL hanya direkomendasikan untuk parameter individual. Jika Anda secara tidak sengaja mengodekan URL seluruh string kueri (semuanya setelah ?), permintaan akan putus.

Selain itu, pengodean URL hanya diperlukan saat memanggil REST API secara langsung menggunakan GET. Tidak ada pengodean URL yang diperlukan saat memanggil Saran menggunakan POST, atau saat menggunakan pustaka klien Azure Cognitive Search .NET menangani pengodean URL untuk Anda.

Header permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Bidang Deskripsi
Content-Type Wajib diisi. Atur titik akhir ini ke application/json
api-key Wajib diisi. api-key digunakan untuk mengautentikasi permintaan ke layanan Pencarian Anda. Ini adalah nilai string, unik untuk URL layanan Anda. Permintaan kueri terhadap docs koleksi dapat menentukan kunci admin atau kunci kueri sebagai api-key. Kunci kueri digunakan untuk operasi khusus kueri.

Anda bisa mendapatkan nilai api-key dari dasbor layanan Anda di portal Azure. Untuk informasi selengkapnya, lihat Menemukan kunci yang sudah ada.

Isi Permintaan

Untuk GET: None.

Untuk POST:

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

Parameter kueri

Kueri menerima beberapa parameter pada URL saat dipanggil dengan GET, dan sebagai properti JSON dalam isi permintaan saat dipanggil dengan POST. Sintaks untuk beberapa parameter sedikit berbeda antara GET dan POST. Perbedaan ini dicatat sebagaimana berlaku di bawah ini.

Nama Jenis Deskripsi
versi-api string Wajib diisi. Versi REST API yang digunakan untuk permintaan. Untuk daftar versi yang didukung, lihat versi API. Untuk operasi ini, versi api ditentukan sebagai parameter kueri di URL terlepas dari apakah Anda memanggil API dengan GET atau POST.
$filter string Opsional. Ekspresi yang memfilter dokumen yang dipertimbangkan untuk saran. Hanya bidang yang dapat difilter yang dapat digunakan dalam filter. Ekspresi filter "search.ismatch" dan "search.ismatchscoring*" tidak didukung di API Lengkapi Otomatis. Ketika dipanggil dengan POST, parameter ini diberi nama filter alih-alih $filter. Lihat Sintaks Ekspresi OData untuk Azure Cognitive Search untuk detail tentang subset tata bahasa ekspresi OData yang didukung Azure Cognitive Search.
Fuzzy boolean Opsional. Default ke false. Ketika diatur ke true, API ini menemukan saran bahkan jika ada karakter yang diganti atau hilang dalam teks pencarian. Jarak edit adalah 1 per string kueri. Jika string kueri adalah beberapa istilah, hanya ada satu karakter yang hilang, ekstra, diganti, atau diubah urutannya di seluruh string. Mengaktifkan kecocokan fuzzy dapat menjadi pengalaman yang lebih baik dalam beberapa skenario, itu memang dikenakan biaya performa, karena pencarian saran fuzzy lebih lambat dan mengonsumsi lebih banyak sumber daya.
highlightPostTag string Opsional. Default ke string kosong. Tag string yang ditambahkan ke istilah yang disorot. Harus diatur dengan highlightPreTag. Karakter yang dicadangkan dalam URL harus dikodekan persen (misalnya, %23, bukan #). Ketika dipanggil menggunakan GET, karakter yang dipesan dalam URL harus dikodekan persen (misalnya, %23 alih-alih #).
highlightPreTag string Opsional. Default ke string kosong. Tag string yang ditambahkan ke istilah yang disorot. Harus diatur dengan highlightPostTag. Ketika dipanggil menggunakan GET, karakter yang dipesan dalam URL harus dikodekan persen (misalnya, %23 alih-alih #).
$orderby string Opsional. Daftar ekspresi yang dipisahkan koma untuk mengurutkan hasilnya. Setiap ekspresi dapat berupa nama bidang atau panggilan ke geo.distance() fungsi. Setiap ekspresi dapat diikuti dengan "asc" (naik) atau "turun" (menurun). Defaultnya adalah urutan naik. Ada batas 32 klausul untuk $orderby. Ketika dipanggil dengan POST, parameter ini dinamai urutan alih-alih $orderby.
minimumCoverage integer Opsional. Default ke 80. Angka antara 0 dan 100 menunjukkan persentase indeks yang harus tersedia untuk melayani kueri sebelum dapat dilaporkan sebagai keberhasilan.

Default mencerminkan bias terhadap kecepatan dan efisiensi atas cakupan penuh. Mengurangi cakupan membatasi ekspansi kueri, memungkinkan hasil untuk kembali lebih cepat. Ini juga memungkinkan kueri untuk berhasil pada ketersediaan indeks parsial, bahkan jika satu pecahan lambat merespons atau tidak tersedia karena masalah kesehatan layanan atau pemeliharaan indeks.

Apa pun nilai minimumCoverage, persentase indeks tersebut harus tersedia atau Saran mengembalikan kode status HTTP 503. Jika Saran berhasil pada tingkat minimumCoverage, saran mengembalikan HTTP 200 dan menyertakan @search.coverage nilai dalam respons yang menunjukkan persentase indeks yang tersedia saat melayani kueri.

Menurunkan nilai ini mungkin berguna jika terjadi kesalahan 503. Jika tidak, Anda mungkin mempertimbangkan untuk menaikkan nilai jika respons memberikan kecocokan yang tidak mencukupi.
pencarian string Wajib diisi. Teks yang akan dicari. Teks pencarian untuk diselesaikan. Harus minimal 1 karakter, dan tidak lebih dari 100 karakter. Ini tidak boleh berisi operator, sintaks kueri, atau frasa yang dikutip.
pencarian string Wajib diisi. Teks pencarian yang digunakan untuk menyarankan kueri. Harus minimal 1 karakter, dan tidak lebih dari 100 karakter. Ini tidak boleh berisi operator, sintaks kueri, atau frasa yang dikutip.
searchFields string Opsional. Daftar nama bidang yang dipisahkan koma untuk mencari teks pencarian yang ditentukan. Bidang target harus tercantum dalam definisi Pemberi Saran dalam indeks.
$select string Opsional. Daftar bidang yang dipisahkan koma untuk diambil. Jika tidak ditentukan, hanya kunci dokumen dan teks saran yang dikembalikan. Anda dapat secara eksplisit meminta semua bidang dengan mengatur parameter ini ke *. Saat memanggil dengan POST, parameter ini diberi nama pilih alih-alih $select.
suggesterName string Wajib diisi. Nama pemberi saran seperti yang ditentukan dalam koleksi Pemberi Saran yang menjadi bagian dari definisi indeks. Pemberi saran menentukan bidang mana yang dipindai untuk istilah kueri yang disarankan.
$top integer Opsional. Default ke 5). Jumlah saran yang diselesaikan secara otomatis untuk diambil. Nilai harus berupa angka antara 1 dan 100. Saat memanggil dengan POST, parameter ini dinamai teratas alih-alih $top.

Respons

Kode Status: "200 OK" dikembalikan untuk respons yang berhasil.

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

Jika opsi proyeksi digunakan untuk mengambil bidang, bidang tersebut disertakan dalam setiap elemen array:

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

Contoh

Ambil 5 saran di mana input pencarian parsial adalah 'lux':

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

Perhatikan bahwa suggesterName diperlukan dalam operasi Saran.

Lihat juga