Referensi API Autosuggest v5
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.
Catatan
Versi baru API ini tersedia. Lihat Autosuggest API v7. Untuk informasi tentang peningkatan, lihat panduan peningkatan.
API Autosuggest memungkinkan Anda mengirim istilah kueri pencarian parsial untuk Bing dan mendapatkan kembali daftar kueri yang disarankan yang telah dicari pengguna lain. Selain menyertakan pencarian yang dibuat oleh orang lain, daftar tersebut dapat menyertakan saran berdasarkan niat pengguna.
Biasanya, Anda menggunakan API ini untuk mendukung pengalaman kotak 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.
Bagian ini menyediakan detail teknis tentang parameter dan header kueri yang mungkin disertakan oleh permintaan, dan respons JSON yang berisi kueri yang disarankan. Untuk contoh yang menunjukkan cara membuat permintaan, lihat Mendapatkan istilah pencarian yang disarankan.
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 oleh respons, lihat Objek Respons.
Untuk informasi tentang penggunaan dan tampilan hasil yang diizinkan, lihat persyaratan Penggunaan dan Tampilan API Pencarian Bing.
Endpoint
Untuk meminta saran kueri, kirim permintaan GET ke:
https://api.cognitive.microsoft.com/bing/v5.0/Suggestions
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 |
|---|---|
| Terima | Header permintaan opsional. Jenis media default adalah aplikasi/json. Untuk menentukan bahwa respons menggunakan JSON-LD, atur header Terima ke application/ld+json. |
| Accept-Language | Header permintaan opsional. Daftar bahasa yang dibatasi koma untuk digunakan untuk string antarmuka pengguna. Daftar ini dalam urutan preferensi yang menurun. Untuk mengetahui informasi selengkapnya, termasuk format yang diharapkan, lihat RFC2616. Header ini dan parameter kueri setLang saling eksklusif jangan tentukan keduanya. Jika Anda mengatur header ini, Anda juga harus menentukan parameter kueri cc. Untuk menentukan pasar untuk mengembalikan hasil, Bing menggunakan bahasa pertama yang didukung yang ditemukannya dari daftar dan menggabungkannya dengan cc nilai parameter. Jika daftar tidak menyertakan bahasa yang didukung, Bing menemukan bahasa dan pasar terdekat yang mendukung permintaan atau menggunakan pasar agregat atau default untuk hasilnya. Untuk menentukan pasar yang digunakan Bing, lihat header BingAPIs-Market.Gunakan header ini dan parameter kueri cc hanya jika Anda menentukan beberapa bahasa. Jika tidak, gunakan parameter kueri mkt dan setLang.String antarmuka pengguna adalah string yang digunakan sebagai label di antarmuka pengguna. Ada beberapa string antarmuka pengguna di objek respons JSON. Setiap tautan ke properti Bing.com dalam objek respons menerapkan bahasa yang ditentukan. |
| BingAPIs-Market | Header respons. Pasar yang digunakan oleh permintaan. Bentuknya adalah <languageCode>-<countryCode>. Misalnya, en-US. Jika Anda menentukan pasar yang tidak tercantum dalam Kode Pasar, nilai ini mungkin berbeda dari pasar yang Anda tentukan dalam parameter kueri mkt . Hal yang sama berlaku jika Anda menentukan nilai untuk cc dan Accept-Language yang tidak dapat direkonsiliasi. |
| BingAPIs-TraceId | Header respons. ID entri log yang berisi detail permintaan. Saat terjadi kesalahan, ambil ID ini. Jika Anda tidak dapat menentukan dan mengatasi masalah tersebut, sertakan ID ini bersama dengan informasi lain yang Anda berikan kepada tim Dukungan. |
| 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. |
| User-Agent | Header permintaan opsional. Agen pengguna yang berasal dari permintaan. Bing menggunakan agen pengguna untuk memberikan pengalaman yang dioptimalkan kepada pengguna seluler. Meskipun opsional, Anda dianjurkan untuk selalu menentukan header ini. User-agent harus berupa string yang sama dengan yang dikirim oleh browser yang umum digunakan. Untuk mengetahui informasi tentang agen pengguna, lihat RFC 2616. Berikut adalah contoh string user-agent.
|
| X-MSEdge-ClientID | Permintaan dan header respons opsional. Bing menggunakan header ini untuk memberi perilaku yang konsisten kepada pengguna di seluruh panggilan Bing API. Bing sering kali menerbangkan fitur dan peningkatan baru, dan menggunakan ID klien sebagai kunci untuk menetapkan lalu lintas pada penerbangan yang berbeda. Jika Anda tidak menggunakan ID klien yang sama untuk pengguna di beberapa permintaan, Bing dapat menetapkan pengguna ke beberapa penerbangan yang bertentangan. Ditetapkan ke beberapa penerbangan yang bertentangan dapat menyebabkan pengalaman pengguna yang tidak konsisten. Misalnya, jika permintaan kedua memiliki penetapan penerbangan yang berbeda dengan yang pertama, pengalaman tersebut mungkin tidak diharapkan. Selain itu, Bing dapat menggunakan ID klien untuk menyesuaikan hasil web dengan riwayat pencarian ID klien tersebut, memberikan pengalaman yang lebih kaya bagi pengguna. Bing juga menggunakan header ini untuk membantu meningkatkan peringkat hasil dengan menganalisis aktivitas yang dibuat oleh ID klien. Peningkatan relevansi membantu terkait kualitas hasil yang lebih baik yang disampaikan oleh Bing API dan pada gilirannya memungkinkan rasio klik-tayang yang lebih tinggi untuk konsumen API. PENTING: Meskipun opsional, Anda harus menganggap header ini diperlukan. Mempertahankan ID klien di beberapa permintaan untuk kombinasi pengguna akhir dan perangkat yang sama memungkinkan 1) konsumen API menerima pengalaman pengguna yang konsisten, dan 2) rasio klik-tayang yang lebih tinggi melalui kualitas hasil yang lebih baik dari Bing API. Berikut adalah aturan dasar penggunaan yang berlaku untuk header ini.
CATATAN: Respons Bing mungkin atau mungkin tidak menyertakan header ini. Jika respons menyertakan header ini, tangkap ID klien dan gunakan untuk semua permintaan Bing berikutnya untuk pengguna di perangkat tersebut. CATATAN Jika Anda menyertakan X-MSEdge-ClientID, Anda tidak boleh menyertakan cookie dalam permintaan. |
| X-Search-ClientIP | Header permintaan opsional. Alamat IPv4 atau IPv6 perangkat klien. Alamat IP digunakan untuk menemukan lokasi pengguna. Bing menggunakan informasi lokasi untuk menentukan perilaku pencarian yang aman. CATATAN: Meskipun opsional, Anda dianjurkan untuk selalu menentukan header ini dan header X-Search-Location. Jangan mengaburkan alamat (misalnya, dengan mengubah oktet terakhir menjadi 0). Mengaburkan alamat mengakibatkan lokasi tidak berada di dekat lokasi aktual perangkat, yang dapat mengakibatkan Bing memberikan hasil yang salah. |
| X-Search-Location | Header permintaan opsional. Daftar pasangan kunci/nilai yang dibatasi titik koma yang menjelaskan lokasi geografis klien. Bing menggunakan informasi lokasi untuk menentukan perilaku pencarian yang aman dan menampilkan konten lokal yang relevan. Tentukan pasangan kunci/nilai sebagai <kunci>:<nilai>. Berikut adalah kunci yang Anda gunakan untuk menentukan lokasi pengguna.
CATATAN: Meskipun opsional, Anda dianjurkan untuk selalu menentukan lokasi geografis pengguna. Menyediakan lokasi sangat penting jika alamat IP klien tidak secara akurat mencerminkan lokasi fisik pengguna (misalnya, jika klien menggunakan VPN). Untuk hasil yang optimal, Anda harus menyertakan header ini dan header X-Search-ClientIP, tetapi minimal, Anda harus menyertakan header ini. |
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 |
|---|---|---|---|
| cc | Kode negara 2 karakter negara tempat hasilnya berasal. Untuk daftar nilai yang mungkin, lihat Kode Pasar. Jika Anda mengatur parameter ini, Anda juga harus menentukan header Accept-Language. Bing menggunakan bahasa pertama yang didukung yang ditemukannya dalam bahasa yang ditentukan dan menggabungkannya dengan kode negara untuk menentukan pasar untuk mengembalikan hasil. Jika daftar bahasa tidak menyertakan bahasa yang didukung, Bing menemukan bahasa dan pasar terdekat yang mendukung permintaan tersebut. Atau, Bing dapat menggunakan pasar agregat atau default untuk hasilnya. Gunakan parameter kueri ini dan Accept-Language header hanya jika Anda menentukan beberapa bahasa. Jika tidak, Anda harus menggunakan mkt parameter kueri dan setLang .Parameter ini dan parameter kueri mkt saling eksklusif—jangan tentukan keduanya. |
String | Tidak |
| mkt | Pasar tempat hasilnya berasal. Biasanya, mkt adalah negara tempat pengguna membuat permintaan. Namun, itu bisa menjadi negara yang berbeda jika pengguna tidak berada di negara tempat Bing memberikan hasil. Pasar harus dalam bentuk <kode> bahasa> kode negara<. Misalnya, en-US. String tidak peka huruf besar/kecil. Untuk daftar kemungkinan nilai pasar, lihat Kode Pasar.CATATAN: Jika diketahui, Anda dianjurkan untuk selalu menentukan pasar. Menentukan pasar membantu Bing merutekan permintaan dan menampilkan respons yang sesuai dan optimal. Jika Anda menentukan pasar yang tidak tercantum dalam Kode Pasar, Bing menggunakan kode pasar yang paling sesuai berdasarkan pemetaan internal yang dapat berubah. Parameter ini dan parameter kueri cc saling eksklusif—jangan tentukan keduanya. |
String | Tidak |
| 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 |
| setLang | Bahasa yang digunakan untuk string antarmuka pengguna. Tentukan bahasa menggunakan kode bahasa ISO 639-1 2 huruf. Misalnya, kode bahasa untuk bahasa Inggris adalah EN. Defaultnya adalah EN (Inggris). Meskipun opsional, Anda harus selalu menentukan bahasa. Biasanya, Anda mengatur setLang ke bahasa yang sama dengan yang ditentukan oleh mkt kecuali pengguna ingin string antarmuka pengguna ditampilkan dalam bahasa yang berbeda.Parameter dan header Accept-Language ini saling eksklusif—jangan tentukan keduanya. String antarmuka pengguna adalah string yang digunakan sebagai label di antarmuka pengguna. Ada beberapa string antarmuka pengguna di objek respons JSON. Selain itu, setiap tautan ke properti Bing.com dalam objek respons menerapkan bahasa yang ditentukan. |
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 gunakan untuk permintaan tersebut. |
| 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 kesalahan. Untuk daftar kode yang mungkin, lihat Kode Kesalahan. | String |
| message | Deskripsi kesalahan. | String |
| parameter | Parameter kueri dalam permintaan yang menyebabkan kesalahan. | 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[] |
QueryContext
Menentukan istilah kueri yang Bing gunakan untuk permintaan tersebut.
| Elemen | Deskripsi | Jenis |
|---|---|---|
| adultIntent | Tidak digunakan. | Boolean |
| alterationOverrideQuery | Tidak digunakan. | String |
| alteredQuery | Tidak digunakan. | String |
| originalQuery | Istilah kueri pengguna. | String |
SearchAction
Menentukan saran pencarian kueri.
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.
|
String |
| 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 | Ketik petunjuk. | String |
| queryContext | String kueri pengguna. | QueryContext |
| suggestionGroups | Daftar string kueri yang disarankan yang dikelompokkan menurut jenis. Misalnya, saran pencarian web. | SuggestionGroup[] |
Kode kesalahan
Berikut ini adalah kemungkinan kode status HTTP yang dapat dikembalikan oleh permintaan.
| Kode Status | Deskripsi |
|---|---|
| 200 | Panggilan berhasil. |
| 400 | Salah satu parameter kueri hilang atau tidak valid. |
| 401 | Kunci langganan hilang atau tidak valid. |
| 403 | Pengguna diautentikasi (misalnya, menggunakan kunci langganan yang valid) tetapi mereka tidak memiliki izin ke sumber daya yang diminta. Jika penelepon melebihi kuota kueri per bulan, Bing juga dapat mengembalikan status ini. |
| 410 | Permintaan yang digunakan HTTP, bukan protokol HTTPS. HTTPS adalah satu-satunya protokol yang didukung. |
| 429 | Penelepon melebihi kueri mereka per kuota kedua. |
Jika permintaan gagal, isi respons akan berisi ErrorResponse objek . Objek respons akan menyertakan kode kesalahan dan deskripsi kesalahan. Jika kesalahan terkait dengan parameter, parameter bidang akan mengidentifikasi parameter yang menjadi masalah. Dan jika kesalahan terkait dengan nilai parameter, value bidang akan mengidentifikasi nilai yang tidak valid.
{
"_type": "ErrorResponse",
"errors": [
{
"code": "RequestParameterMissing",
"message": "Required parameter is missing.",
"parameter": "q"
}
]
}
{
"_type": "ErrorResponse",
"errors": [
{
"code": "AuthorizationMissing",
"message": "Authorization is required.",
}
]
}
Berikut ini adalah kemungkinan kode kesalahan.
| Kode kesalahan | Deskripsi |
|---|---|
| RequestParameterMissing | Permintaan tidak memiliki parameter yang diperlukan. Bidang parameter mengidentifikasi parameter yang hilang. |
| RequestParameterInvalidValue | Nilai parameter tidak valid. Bidang parameter mengidentifikasi parameter yang berisi nilai yang tidak valid, dan value bidang berisi nilai yang tidak valid. |
| ResourceAccessDenied | Pemanggil tidak memiliki izin untuk mengakses sumber daya. Kesalahan ini dapat terjadi jika kunci langganan telah dinonaktifkan atau telah kedaluwarsa. |
| ExceededVolume | Penelepon melebihi kuota kueri per bulan (QPM). |
| ExceededQpsLimit | Penelepon melebihi kueri mereka per detik (QPS). |
| Nonaktifkan | Pemanggil tidak memiliki izin untuk mengakses sumber daya. |
| UnexpectedError | Terjadi kesalahan tak terduga pada server. Coba lagi nanti. |
| DataSourceErrors | Terjadi kesalahan saat mengakses sumber daya. |
| AuthorizationMissing | Bing tidak dapat mengautentikasi pemanggil. Kesalahan ini dapat terjadi jika Ocp-Apim-Subscription-Key header hilang. |
| HttpNotAllowed | Permintaan menggunakan protokol HTTP alih-alih protokol HTTPS; Bing hanya mendukung HTTPS. |
| InvalidAuthorization | Bing tidak dapat mengautentikasi pemanggil. Ini dapat terjadi jika kunci langganan tidak valid. |
| InsufficientScope | Pemanggil tidak memiliki izin untuk mengakses sumber daya. Kesalahan ini dapat terjadi jika kunci langganan telah kedaluwarsa. |
Kode pasar
Tabel berikut mencantumkan nilai kode pasar yang dapat Anda gunakan untuk menentukan mkt parameter kueri. Bing hanya akan menampilkan konten untuk pasar ini. Daftar ini dapat berubah.
Untuk daftar kode negara yang mungkin Anda tentukan dalam cc parameter kueri, lihat Kode negara.
| Negara/Wilayah | Bahasa | Kode pasar |
|---|---|---|
| Argentina | Spanyol | es-AR |
| Australia | Inggris | en-AU |
| Austria | Jerman | de-AT |
| Belgia | Belanda | nl-BE |
| Belgia | Prancis | fr-BE |
| Brasil | Portugis | pt-BR |
| Kanada | Inggris | en-CA |
| Kanada | Prancis | fr-CA |
| Cile | Spanyol | es-CL |
| Denmark | Dansk | da-DK |
| Finlandia | Suomi | fi-FI |
| Prancis | Prancis | fr-FR |
| Jerman | Jerman | de-DE |
| Hong Kong SAR | Mandarin Tradisional | zh-HK |
| India | Inggris | en-IN |
| Indonesia | Inggris | en-ID |
| Italia | Italia | it-IT |
| Jepang | Jepang | ja-JP |
| Korea | Korea | ko-KR |
| Malaysia | Inggris | en-MY |
| Meksiko | Spanyol | es-MX |
| Belanda | Belanda | nl-NL |
| Selandia Baru | Inggris | en-NZ |
| Norwegia | Norwegia | no-NO |
| Republik Rakyat Tiongkok | Mandarin | zh-CN |
| Polandia | Polski | pl-PL |
| Republik Filipina | Inggris | en-PH |
| Rusia | Rusia | ru-RU |
| Afrika Selatan | Inggris | en-ZA |
| Spanyol | Spanyol | es-ES |
| Swedia | Swedia | sv-SE |
| Swiss | Prancis | fr-CH |
| Swiss | Jerman | de-CH |
| Taiwan | Mandarin Tradisional | zh-TW |
| Turki | Turki | tr-TR |
| Inggris Raya | Inggris | en-GB |
| Amerika Serikat | Inggris | en-US |
| Amerika Serikat | Spanyol | es-US |
Kode negara
Berikut ini adalah kode negara yang dapat Anda tentukan dalam cc parameter kueri. Daftar ini dapat berubah.
| Negara/Wilayah | Kode Negara |
|---|---|
| Argentina | AR |
| Australia | AU |
| Austria | AT |
| Belgia | BE |
| Brasil | BR |
| Kanada | CA |
| Cile | CL |
| Denmark | DK |
| Finlandia | FI |
| Prancis | FR |
| Jerman | DE |
| Hong Kong SAR | HK |
| India | IN |
| Indonesia | ID |
| Italia | IT |
| Jepang | JP |
| Korea | KR |
| Malaysia | MY |
| Meksiko | MX |
| Belanda | NL |
| Selandia Baru | NZ |
| Norwegia | NO |
| Republik Rakyat Tiongkok | CN |
| Polandia | PL |
| Portugal | PT |
| Republik Filipina | PH |
| Rusia | RU |
| Arab Saudi | SA |
| Afrika Selatan | ZA |
| Spanyol | ES |
| Swedia | SE |
| Swiss | CH |
| Taiwan | TW |
| Turki | TR |
| Inggris Raya | GB |
| Amerika Serikat | US |