Panduan cepat: Buat panggilan API Web IQ pertama Anda

Lakukan panggilan REST API Microsoft Web IQ pertama Anda dalam beberapa menit. Anda akan mencari web, memeriksa respons, lalu mengekstrak konten dari URL yang diketahui.

Kunci API adalah cara tercepat untuk mengevaluasi Web IQ. Untuk beban kerja produksi, gunakan Microsoft Entra ID.

Prerequisites

Tip

Gunakan Web IQ Playground untuk mengirim permintaan dari browser dan menghasilkan kode di cURL, Python, JavaScript, C#, Java, Go, dan Ruby.

1. Simpan kunci API Anda

Letakkan key dalam variabel lingkungan sehingga contoh permintaan tidak mengulanginya atau menempatkannya di kode sumber Anda.

macOS atau Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

$env:WEBIQ_API_KEY="your-api-key"

Warning

Jangan meng-commit kunci Anda ke source control atau mengeksposnya di browser atau kode sisi klien. Simpan kredensial produksi di Secret Manager.

2. Cari di web

Gunakan Pencarian Web saat Anda memiliki pertanyaan atau kueri dan ingin Web IQ menemukan dan memberi peringkat halaman yang relevan.

Sebaiknya atur maxResults = 10, contentFormat = passage, dan maxLength = 3000 pada setiap permintaan sebagai titik operasi yang dioptimalkan. Dari sana, Anda dapat menyempurnakan pengaturan ini berdasarkan kasus penggunaan Anda.

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

cURL

curl --request POST "https://api.microsoft.ai/v3/search/web" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "latest developments in retrieval augmented generation",
    "maxResults": 10,
    "contentFormat": "passage",
    "maxLength": 3000
  }'

Python

import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/search/web",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "query": "latest developments in retrieval augmented generation",
        "maxResults": 10,
        "contentFormat": "passage",
        "maxLength": 3000,
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

JavaScript

Simpan contoh ini sebagai search.mjs dan jalankan dengan node search.mjs.

const response = await fetch("https://api.microsoft.ai/v3/search/web", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "latest developments in retrieval augmented generation",
    maxResults: 10,
    contentFormat: "passage",
    maxLength: 3000,
  }),
});

if (!response.ok) {
  throw new Error(`Web Search failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

3. Pahami respons

Pencarian Web yang berhasil mengembalikan array webResults. Contoh ringkas ini menunjukkan bidang yang paling sering Anda gunakan:

{
  "webResults": [
    {
      "title": "Example result",
      "url": "https://example.com/article",
      "content": "The query-relevant passage extracted from the page...",
      "crawledAt": "2026-07-18T12:00:00Z"
    }
  ],
  "traceId": "00000000000000000000000000000000"
}
  • title dan url mengidentifikasi sumber.
  • content berisi bagian yang relevan dengan kueri karena permintaan tersebut menggunakan contentFormat: "passage".
  • traceId membantu Web IQ Support menyelidiki permintaan.

Dalam respons REST dan hasil alat MCP, bidang model dengan null, string kosong (""), atau nilai daftar/array kosong ([]) dihilangkan, termasuk bidang objek hasil berlapis. Perlakukan bidang string yang tidak ada sebagai tidak tersedia dan bidang daftar yang tidak ada sebagai tidak memiliki item. String khusus spasi putih, false, 0, dictionary kosong, entri array/dictionary individual, dan JSON mentah yang disematkan dipertahankan. Array akar dan koleksi pembungkus protokol seperti MCP content tidak berubah.

Lihat referensi WEB Search API untuk semua parameter dan bidang respons.

4. Pilih Pencarian Web atau Jelajahi

Mulai dengan Gunakan Apa yang Anda dapatkan
Pertanyaan atau kueri pencarian Pencarian Web Halaman yang diberi peringkat dengan konten yang relevan dengan kueri
URL tertentu Telusuri Konten yang diekstrak dari halaman tersebut

Alur kerja grounding umum menggunakan kedua titik akhir: cari sumber yang relevan, pilih URL hasil, lalu telusuri URL tersebut saat Anda memerlukan konten halaman yang lebih lengkap.

5. Ekstrak konten dari URL

Gunakan Telusuri saat Anda sudah mengetahui halaman mana yang ingin Anda baca. liveCrawl: "fallback" meminta agar Web IQ merayapi halaman ketika halaman tersebut belum tersedia dalam indeks.

Titik Akhir:POST https://api.microsoft.ai/v3/browse

cURL

curl --request POST "https://api.microsoft.ai/v3/browse" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "url": "https://news.microsoft.com/source/",
    "contentFormat": "markdown",
    "maxLength": 3000,
    "liveCrawl": "fallback"
  }'

Python

import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/browse",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "url": "https://news.microsoft.com/source/",
        "contentFormat": "markdown",
        "maxLength": 3000,
        "liveCrawl": "fallback",
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

JavaScript

Simpan contoh ini sebagai browse.mjs dan jalankan dengan node browse.mjs.

const response = await fetch("https://api.microsoft.ai/v3/browse", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    url: "https://news.microsoft.com/source/",
    contentFormat: "markdown",
    maxLength: 3000,
    liveCrawl: "fallback",
  }),
});

if (!response.ok) {
  throw new Error(`Browse failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

Respons yang berhasil 200 mencakup halaman url, title, hasil ekstraksi content, dan sebuah traceId. Perayapan langsung dapat mengembalikan 202 dengan retryAfter; tunggu durasi tersebut, lalu kirim permintaan yang sama lagi. Lihat referensi Browse API untuk kontrak respons lengkap.

Troubleshooting

Status Apa yang harus diperiksa
401 Unauthorized Konfirmasi WEBIQ_API_KEY telah diatur dan permintaan mengirimkannya di x-apikey header.
415 Unsupported Media Type Kirim content-type: application/json.
429 Too Many Requests Tunggu sebelum mencoba kembali dan kurangi frekuensi permintaan.
Telusuri 404 Not Found Konfirmasikan URL bersifat publik dan valid. Gunakan liveCrawl: "fallback" ketika konten terindeks mungkin tidak tersedia.
Telusuri 202 Accepted Tunggu durasi yang dikembalikan retryAfter , lalu coba lagi permintaan yang sama.

Untuk kegagalan lainnya, simpan traceId dan lihat Penanganan Kesalahan atau hubungi Dukungan Web IQ.

Langkah berikutnya

  • Terakhir diperbarui pada