Referensi WEB Search REST API

Titik Akhir:POST https://api.microsoft.ai/v3/search/web

Permintaan Sampel:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "latest trends in LLM RAG",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Parameters

Parameter	Required	Type	Default	Description
kueri	Yes	string	-	String kueri pencarian. Panjang maksimum adalah 1000 karakter. Mendukung operator "site:" dan "-site:" untuk menyertakan atau mengecualikan hasil dari situs tertentu (misalnya, "query site:example.com"). Gunakan operator ini hanya jika perlu, karena secara inheren mengurangi relevansi hasil.
maxResults	No	integer	10	Jumlah maksimum hasil yang akan dikembalikan. Defaultnya adalah 10 dan nilai maksimum adalah 50.
language	No	string	"en"	Kode bahasa ISO 639-1 2 huruf untuk bahasa antarmuka dalam hasil pencarian. Lihat Bahasa yang Didukung untuk daftar lengkapnya.
region	No	string	"US"	Kode negara/wilayah 2 huruf tempat hasilnya harus berasal (misalnya "US", "JP", "GB", dll.). Lihat Wilayah yang Didukung untuk daftar lengkapnya.
lokasi	No	string	-	Informasi lokasi dalam format "lat:<float>; long:<float>", misalnya "lat:40.753250; long:-74.003807". Jika tidak ditentukan, lokasi dalam kueri akan disimpulkan.
contentFormat	No	string	"bagian" ("html" dengan akses dokumen lengkap)	passage mengembalikan bagian dari setiap hasil yang paling relevan dengan kueri (disarankan untuk grounding). text, html dan markdown mengembalikan dokumen lengkap dan hanya berlaku untuk aplikasi dengan akses dokumen lengkap; lihat Bagian dan format konten. Atur pada setiap permintaan. Catatan: API web tidak mengembalikan snippet bidang.
panjang maksimum	No	integer	3000 (10000 dengan akses dokumen penuh)	Karakter maksimum dalam content per hasil, 1 hingga 500000. Tanpa akses dokumen penuh, content paling banyak 3000 karakter. Lihat Default dan batasan. Atur pada setiap permintaan.
safeSearch	No	string	"ketat"	Tingkat pemfilteran pencarian yang aman. Nilai: "off", "strict". Defaultnya adalah "ketat".

Format konten

Atur contentFormat = passage untuk mendapatkan bagian dari setiap hasil yang paling relevan dengan kueri, hingga maxLength karakter (3000 adalah titik awal yang baik). Ini adalah format yang direkomendasikan untuk grounding; lihat Apa itu passage, dan mengapa menggunakannya? di FAQ. Aplikasi dengan akses dokumen lengkap juga dapat meminta dokumen lengkap sebagai text, html atau markdown; untuk aplikasi lain, format tersebut mengembalikan HTTP 403. Lihat Bagian dan format konten.

SafeSearch

Mode SafeSearch memungkinkan Anda mengontrol seberapa banyak konten web sensitif yang difilter API Web sebelum hasil dikembalikan. Konten sensitif mencakup kekerasan, melukai diri sendiri, dan kategori lainnya. Nilai defaultnya adalah strict.

Value	Description	Disarankan Untuk
strict	Memblokir konten yang terkait dengan topik dewasa, cabul, kekerasan, kebencian, dan menyakiti diri sendiri.	Penyebaran yang aman bagi anak, pendidikan, konsumen/konservatif.
off	Masih memblokir konten ilegal. Untuk konten lain yang berpotensi berbahaya, mengalihkan tanggung jawab untuk pemfilteran akhir kepada pengguna.	Penelitian, analisis, perusahaan keikutsertaan, kasus penggunaan 3P tingkat lanjut.

Note

Jika Anda menggunakan site: operator kueri, respons mungkin berisi konten dewasa terlepas dari nilainya safeSearch . Gunakan site: hanya jika Anda mengetahui konten di situs dan skenario Anda mendukung kemungkinan konten dewasa.

Header Permintaan

Field	Type	Description
host	string	Host untuk API AI Microsoft: api.microsoft.ai.
x-apikey atau Otorisasi	string	Kunci API Anda atau token akses Entra ID untuk autentikasi.
jenis konten	string	Jenis MIME isi permintaan. Gunakan application/json.

Jawaban

Respons Web

Field	Type	Description
webResults	array webResult	Daftar hasil halaman web.
querySignals	querySignals	Sinyal peringkat tingkat kueri untuk kueri pencarian.
riskLevel	string	Tingkat risiko keamanan yang dinilai untuk kueri. Nilai yang mungkin: low, moderate, high, veryHigh.
instrumentationClickBase	string	URL Dasar untuk mengeklik permintaan ping. Tambahkan instrumentationSuffix nilai dari item hasil untuk membentuk URL ping lengkap. Hanya ada untuk aplikasi dengan bendera profil EnableInstrumentationPing. Catatan: Klik pengguna juga dapat dicatat menggunakan pengalihan URL. Ketika pengalihan diaktifkan, tidak ada tindakan yang diperlukan untuk mencatat klik Pengguna, dan instrumentationClickBase tidak akan disertakan dalam respons. Lihat Panduan instrumentasi untuk instruksi penyiapan.
instrumentationCitationBase	string	URL Dasar untuk permintaan ping log LLM. Tambahkan payload DATA untuk membentuk URL ping lengkap. Hanya ada untuk aplikasi dengan bendera profil EnableInstrumentationPing.
traceId	string	ID pelacakan untuk penelusuran kesalahan.

querySignals

Field	Type	Description
freshness	Boolean	Menunjukkan apakah dokumen baru harus diprioritaskan daripada dokumen lain untuk kueri ini.

webResult

Field	Type	Description
title	string	Judul halaman web.
url	string	URL sumber halaman web. Untuk pengguna Tiongkok dengan pengalihan URL diaktifkan, bidang ini sebagai gantinya berisi URL pengalihan yang sama dengan clickUrl.
domain	string	Host tujuan untuk hasilnya. Dikembalikan hanya untuk pengguna Tiongkok dengan pengalihan URL diaktifkan.
isi	string	Konten terperinci (alias grounding) dari halaman web.
crawledAt	string	Tanggal perayapan terakhir halaman web, mengikuti format ISO8601.
terakhirDiperbaruiPada	string	Tanggal terakhir diperbarui dari halaman web, mengikuti format ISO8601.
language	string	Bahasa halaman web, menggunakan kode bahasa ISO 639-1.
isAdult	Boolean	Menunjukkan apakah hasilnya menyertakan konten dewasa.
klikUrl	string	Alihkan URL yang memproksi klik melalui Bing. Hanya ada saat pengalihan klik diaktifkan.
instrumentationSuffix	string	Akhiran untuk ditambahkan ke basis URL ping instrumentasi untuk item hasil ini. Digunakan sebagai nilai K untuk URL ping instrumentasi dan clickUrl pengalihan. Ada saat ping instrumentasi diaktifkan.
contentTier	string	Tingkat konten hasil, yang menjelaskan karakteristik akses komersial sumber konten. Nilai yang mungkin: standard (konten standar tersedia untuk semua pelanggan di bawah penawaran layanan default), entitled (konten tersedia melalui perjanjian lisensi pelanggan yang ada, termasuk konten Bring Your Own License (BYOL) yang telah dilisensikan pelanggan langsung dari penerbit dan akses melalui pengaturan kontrak mereka sendiri), premium (konten premium yang memberikan nilai tambahan di luar penawaran standar dan tunduk pada penagihan).

Note

crawledAt Nilai bidang dan lastUpdatedAt bersifat opsional. Artinya, cakupan mereka tidak 100%. Anda mungkin melihat nilai kosong untuk bidang ini.

Kode Kesalahan

Kode Status	Kategori Kesalahan	Description	Penyebab Umum
200	Keberhasilan	Permintaan itu berhasil.	-
400	Permintaan Tidak Valid	Parameter permintaan tidak valid.	Bidang yang diperlukan hilang, nilai parameter tidak valid, JSON cacat
401	Unauthorized	Autentikasi gagal atau hilang.	Kunci API tidak valid, header x-apikey hilang
403	Forbidden	Kredensial yang valid tetapi izinnya tidak mencukup.	Kunci API tidak memiliki izin yang diperlukan
410	Hilang	HTTPS diperlukan.	Permintaan yang dibuat melalui HTTP alih-alih HTTPS
415	Tipe Media yang Tidak Didukung	Tipe isi tidak didukung.	Header tipe konten yang hilang atau salah
429	Terlalu Banyak Permintaan	Batas kecepatan terlampaui.	Terlalu banyak permintaan dalam jendela waktu
500	Kesalahan Server Internal	Kesalahan server tak terduga.	Masalah server sementara
503	Layanan Tidak Tersedia	Layanan untuk sementara tidak tersedia.	Pemeliharaan atau pemadaman sementara
504	Waktu Habis Gateway	Waktu permintaan berakhir.	Batas waktu layanan upstram

Untuk panduan penanganan kesalahan terperinci, lihat Penanganan Kesalahan.

---

Lihat juga:Pencarian | VideoTelusuri | Gambar | Pencarian | BeritaMCP