Referensi API Autosuggest Kustom v7

Artikel
07/26/2022
5 menit untuk membaca

Peringatan

API Pencarian Bing berpindah dari Cognitive Services ke Layanan Pencarian Bing. Mulai 30 Oktober 2020, setiap instans baru Bing Search perlu diprovisikan dengan mengikuti proses yang didokumentasikan di sini. Bing Search API yang diprovisikan menggunakan Cognitive Services akan didukung selama tiga tahun ke depan atau hingga akhir Perjanjian Enterprise Anda, mana saja yang lebih dulu. Untuk instruksi migrasi, lihat Layanan Pencarian Bing.

API Autosuggest Kustom memungkinkan Anda mengirim string kueri pencarian parsial untuk Bing dan mendapatkan kembali daftar kueri yang disarankan. Biasanya, Anda menggunakan API ini untuk mendukung pengalaman pencarian yang lebih kaya. Misalnya, saat pengguna memasukkan setiap karakter istilah pencarian mereka, Anda akan memanggil API ini dan mengisi daftar drop-down kotak pencarian dengan string kueri yang disarankan.

Untuk informasi tentang mengonfigurasi saran kustom, lihat Mengonfigurasi pengalaman Autosuggest Kustom Anda.

Untuk informasi tentang header yang harus Anda sertakan dalam permintaan, lihat Header Permintaan.

Untuk informasi tentang parameter kueri yang harus Anda sertakan dalam permintaan, lihat Parameter Kueri.

Untuk informasi tentang objek JSON yang mungkin disertakan respons, lihat Objek Respons.

Untuk informasi tentang penggunaan dan tampilan hasil yang diizinkan, lihat persyaratan Penggunaan dan Tampilan SEARCH API Bing.

Catatan

Karena format dan parameter URL dapat berubah tanpa pemberitahuan, gunakan semua URL apa adanya. Anda tidak boleh mengambil dependensi pada format atau parameter URL kecuali jika dicatat.

Titik akhir

Untuk meminta saran kueri kustom, kirim permintaan GET ke:

https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/suggestions/search

Permintaan harus menggunakan protokol HTTPS.

Catatan

Panjang URL maksimum adalah 2.048 karakter. Untuk memastikan bahwa panjang URL Anda tidak melebihi batas, panjang maksimum parameter kueri Anda harus kurang dari 1.500 karakter. Jika URL melebihi 2.048 karakter, server menampilkan 404 Tidak ditemukan.

Header

Berikut adalah header yang mungkin disertakan oleh permintaan dan respons.

Header	Deskripsi
Ocp-Apim-Subscription-Key	Header permintaan yang diperlukan. Kunci langganan yang Anda terima saat mendaftar untuk layanan ini di Cognitive Services.
Retry-After	Header respons. Respons mencakup header ini jika Anda melebihi jumlah kueri yang diizinkan per detik (QPS) atau per bulan (QPM). Header berisi jumlah detik yang harus Anda tunggu sebelum mengirim permintaan lain.

Catatan

Ingatlah bahwa Ketentuan Penggunaan memerlukan kepatuhan terhadap semua hukum yang berlaku, termasuk mengenai penggunaan header ini. Misalnya, di wilayah hukum tertentu, seperti Eropa, ada persyaratan untuk mendapatkan persetujuan pengguna sebelum menempatkan perangkat pelacakan tertentu pada perangkat pengguna.

Parameter kueri

Berikut adalah parameter kueri yang dapat disertakan dalam permintaan. Kolom Wajib diisi menunjukkan bahwa Anda harus menentukan parameter. Anda harus mengodekan nilai parameter kueri ke dalam URL.

Nama	Nilai	Jenis	Diperlukan
customConfig	Pengidentifikasi unik yang mengidentifikasi instans pencarian kustom Anda.	String	Ya
q	String kueri pencarian pengguna. String kueri tidak boleh kosong. Jika kosong atau tidak ditentukan, daftar saran dalam respons kosong. API tidak mendukung Operator Tingkat Lanjut Bing. Jika string kueri menyertakan operator Bing, operator diperlakukan sebagai bagian dari string kueri, bukan sebagai operator.	String	Tidak

Objek respons

Berikut ini adalah objek JSON yang mungkin disertakan oleh respons. Jika permintaan berhasil, objek tingkat atas dalam respons adalah objek Saran . Jika permintaan gagal, objek tingkat atas adalah ErrorResponse.

Objek	Deskripsi
Kesalahan	Mendefinisikan kesalahan yang terjadi.
ErrorResponse	Objek tingkat atas yang disertakan respons saat permintaan gagal.
QueryContext	Menentukan istilah kueri yang Bing digunakan untuk permintaan.
SearchAction	Menentukan kueri pencarian yang disarankan.
SuggestionGroup	Menentukan sekelompok saran dengan jenis yang sama.
Saran	Objek tingkat atas yang disertakan respons saat permintaan berhasil.

Kesalahan

Mendefinisikan kesalahan yang terjadi.

Elemen	Deskripsi	Jenis
code	Kode kesalahan yang mengidentifikasi kategori kesalahan. Untuk daftar kode yang mungkin, lihat Kode Kesalahan.	String
message	Deskripsi kesalahan.	String
moreDetails	Deskripsi yang menyediakan informasi tambahan tentang kesalahan tersebut.	String
parameter	Parameter kueri dalam permintaan yang menyebabkan kesalahan.	String
subCode	Kode kesalahan yang mengidentifikasi kesalahan. Misalnya, jika `code` InvalidRequest, `subCode` mungkin berupa ParameterInvalid atau ParameterInvalidValue.	String
value	Nilai parameter kueri yang tidak valid.	String

ErrorResponse

Objek tingkat atas yang disertakan respons saat permintaan gagal.

Nama	Nilai	Jenis
_type	Ketik petunjuk.	String
errors	Daftar kesalahan yang menjelaskan alasan permintaan gagal.	Error[]

SearchAction

Menentukan saran pencarian kueri.

Nama	Nilai	Jenis
displayText	Istilah kueri yang disarankan untuk ditampilkan di antarmuka pengguna.	untai
query	Istilah kueri yang disarankan. Jika pengguna memilih istilah kueri dari daftar saran, gunakan istilah dalam permintaan API Bing dan tampilkan hasil pencarian sendiri. Atau, gunakan URL di `url` bidang untuk mengirim pengguna ke halaman hasil pencarian Bing untuk kueri yang disarankan.	untai
searchKind	Jenis saran. Berikut ini adalah nilai yang mungkin. CustomSearch—Saran ini berasal dari sumber data saran pencarian non-Web. WebSearch—Saran berasal dari sumber data saran pencarian web.	untai

SuggestionGroup

Menentukan sekelompok saran dengan jenis yang sama.

Nama	Nilai	Jenis
Nama	Nama grup. Nama mengidentifikasi jenis saran yang dikandung grup. Misalnya, saran pencarian web. Berikut ini adalah kemungkinan nama grup. Kustom—Grup berisi saran dari sumber data saran pencarian non-web. Web—Grup berisi saran pencarian web.	untai
searchSuggestions	Daftar hingga 8 saran. Jika tidak ada saran, array kosong. Anda harus menampilkan semua saran dalam urutan yang disediakan. Daftar ini dalam urutan penurunan relevansi. Saran pertama adalah yang paling relevan dan saran terakhir adalah yang paling tidak relevan. Ukuran daftar dapat berubah.	SearchAction[]

Saran

Objek tingkat atas yang disertakan respons saat permintaan berhasil.

Jika layanan mencurigai penolakan serangan layanan, permintaan berhasil (kode status HTTP adalah 200 OK). Namun, body responsnya kosong.

Nama	Nilai	Jenis
_type	Petunjuk jenis, yang diatur ke Saran.	untai
queryContext	String kueri pengguna.	QueryContext
suggestionGroups	Daftar string kueri yang disarankan yang dikelompokkan menurut jenis. Misalnya, saran pencarian web.	SuggestionGroup[]

Kode kesalahan

Berikut adalah kemungkinan kode status HTTP yang ditampilkan permintaan.

Kode Status	Deskripsi
200	Berhasil.
400	Salah satu parameter kueri hilang atau tidak valid.
401	Kunci langganan hilang atau tidak valid.
410	Permintaan yang digunakan HTTP, bukan protokol HTTPS. HTTPS adalah satu-satunya protokol yang didukung.
429	Penelepon melebihi kueri mereka per kuota kedua.
500	Kesalahan server tidak terduga.

Jika permintaan gagal, respons berisi objek ErrorResponse, yang berisi daftar objek Kesalahan yang menjelaskan apa yang menyebabkan kesalahan. Jika kesalahan terkait dengan parameter, bidang parameter mengidentifikasi parameter yang menjadi masalah. Dan jika kesalahan terkait dengan nilai parameter, bidang value mengidentifikasi nilai yang tidak valid.

{
  "_type": "ErrorResponse", 
  "errors": [
    {
      "code": "InvalidRequest", 
      "subCode": "ParameterMissing", 
      "message": "Required parameter is missing.", 
      "parameter": "q" 
    }
  ]
}

{
  "_type": "ErrorResponse", 
  "errors": [
    {
      "code": "InvalidAuthorization", 
      "subCode": "AuthorizationMissing", 
      "message": "Authorization is required.", 
      "moreDetails": "Subscription key is not recognized."
    }
  ]
}

Berikut adalah kemungkinan nilai kode kesalahan dan kode sub-kesalahan.

Kode	SubCode	Deskripsi
ServerError	UnexpectedError ResourceError NotImplemented	Kode status HTTP adalah 500.
InvalidRequest	ParameterMissing ParameterInvalidValue HttpNotAllowed Diblokir	Bing menampilkan InvalidRequest setiap kali bagian mana pun dari permintaan tidak valid. Misalnya, parameter yang diperlukan hilang atau nilai parameter tidak valid. Jika kesalahannya adalah ParameterMissing atau ParameterInvalidValue, kode status HTTP adalah 400. Jika Anda menggunakan protokol HTTP alih-alih HTTPS, Bing menampilkan HttpNotAllowed, dan kode status HTTP adalah 410.
RateLimitExceeded	Tidak ada sub-kode	Bing menampilkan RateLimitExceed setiap kali Anda melebihi kuota kueri per detik (QPS) atau kueri per bulan (QPM) Anda. Jika Anda melebihi QPS, Bing menampilkan kode status HTTP 429, dan jika Anda melebihi QPM, Bing menampilkan 403.
InvalidAuthorization	AuthorizationMissing AuthorizationRedundancy	Bing menampilkan InvalidAuthorization saat Bing tidak dapat mengautentikasi pemanggil. Misalnya, header `Ocp-Apim-Subscription-Key` hilang atau kunci langganan tidak valid. Redundansi terjadi jika Anda menentukan lebih dari satu metode autentikasi. Jika kesalahannya adalah InvalidAuthorization, kode status HTTP adalah 401.
NoSuggestions	Tidak ada sub-kode	Tidak ada saran yang ditemukan, kode status HTTP adalah 404.