Saran (Azure AI Search REST API)

Artikel
05/10/2023

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 Pencarian Azure AI.

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 AI Search .NET menangani pengodean URL untuk Anda.

Judul Permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Bidang Deskripsi

Jenis-Konten Wajib diisi. Atur titik akhir ini ke application/json

api-key Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Kunci api adalah string unik yang dihasilkan sistem yang mengautentikasi permintaan ke layanan pencarian Anda. Permintaan kueri terhadap koleksi dokumen dapat menentukan kunci admin atau kunci kueri sebagai kunci API. Kunci kueri digunakan untuk operasi baca-saja terhadap kumpulan dokumen. Lihat Menyambungkan ke Pencarian Azure AI menggunakan autentikasi kunci untuk detailnya.

Bidang	Deskripsi
Jenis-Konten	Wajib diisi. Atur titik akhir ini ke `application/json`
api-key	Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Kunci api adalah string unik yang dihasilkan sistem yang mengautentikasi permintaan ke layanan pencarian Anda. Permintaan kueri terhadap koleksi dokumen dapat menentukan kunci admin atau kunci kueri sebagai kunci API. Kunci kueri digunakan untuk operasi baca-saja terhadap kumpulan dokumen. Lihat Menyambungkan ke Pencarian Azure AI menggunakan autentikasi kunci untuk detailnya.

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 Pencarian Azure AI untuk detail tentang subset tata bahasa ekspresi OData yang didukung Azure AI 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	bilangan bulat	Pilihan. 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 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	bilangan bulat	Pilihan. 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.