Rövid útmutató: Az első webes IQ API-hívások kezdeményezése

Néhány percen belül kezdeményezheti az első Microsoft webes IQ REST API-hívást. Az interneten keresni fog, megvizsgálja a választ, majd kinyeri a tartalmat egy ismert URL-címből.

Az API-kulcsok a Web IQ kiértékelésére szolgáló leggyorsabb módok. éles számítási feladatokhoz használja a Microsoft Entra ID.

Prerequisites

Jótanács

A Web IQ Playground használatával kéréseket küldhet a böngészőből, és kódot hozhat létre cURL, Python, JavaScript, C#, Java, Go és Ruby nyelven.

1. Tárolja az API-kulcsát

Helyezze a kulcsot egy környezeti változóba, hogy a példakérések ne ismételjék meg azt, és ne helyezze el a forráskódban.

macOS vagy Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

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

Warning

Ne commitolja be a kulcsát a verziókezelőbe, és ne tegye elérhetővé a böngészőben vagy az ügyféloldali kódban. Tárolja az éles hitelesítő adatokat egy titokkezelőben.

2. Keresés a weben

A Web Search szolgáltatást akkor használja, ha kérdése vagy lekérdezése van, és azt szeretné, hogy a Web IQ felderítse és rangsorolja a releváns lapokat.

Javasoljuk, hogy minden kérésnél optimalizált működési beállításként állítsa be a contentFormat = passage, maxLength = 3000 és maxResults = 10 elemeket. Innen a használati eset alapján finomhangolhatja ezeket a beállításokat.

Végpont: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

Mentse ezt a példát search.mjs néven, és futtassa a következővel: 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. A válasz értelmezése

A sikeres webkeresés egy webResults tömböt ad vissza. Ez a rövidített példa a leggyakrabban használt mezőket mutatja be:

{
  "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 és url azonosítja a forrást.
  • content a lekérdezés szempontjából releváns szakaszt tartalmazza, mert a kérésben a(z) contentFormat: "passage" szerepelt.
  • traceId segít a Web IQ Supportnak a kérések kivizsgálásában.

A REST-válaszokban és az MCP-eszközök eredményeiben a rendszer kihagyja a "", üres sztring ([]) vagy üres lista/tömb (null) értékekkel rendelkező modellmezőket, beleértve a beágyazott eredményobjektumok mezőit is. A hiányzó sztringmezőt tekintse nem elérhetőnek, a hiányzó listamezőt pedig elem nélkülinek. A rendszer megőrzi a csak szóközöket tartalmazó sztringeket, falseaz 0üres szótárakat, az egyes tömb-/szótárbejegyzéseket és a beágyazott nyers JSON-bejegyzéseket. A gyökértömbök és a protokoll-boríték gyűjtemények, például az MCP content változatlanok maradnak.

Tekintse meg a Web Search API-referenciát az összes paraméterről és válaszmezőről.

4. Válassza a Webes keresés vagy a Tallózás lehetőséget

Kezdje ezzel Használat Mit kap meg?
Kérdés vagy keresési lekérdezés Webes keresés Rangsorolt lapok lekérdezés szempontjából releváns tartalommal
Egy adott URL-cím Böngészik Kinyert tartalom az adott lapról

A gyakori grounding munkafolyamat mindkét végpontot használja: keressen rá a releváns forrásokra, válasszon ki egy találati URL-címet, majd nyissa meg azt az URL-címet, ha teljesebb oldaltartalomra van szüksége.

5. Tartalom kinyerése URL-ből

A Tallózás parancsot akkor használja, ha már tudja, hogy melyik oldalt szeretné elolvasni. liveCrawl: "fallback" felkéri a Web IQ-t, hogy bejárja a lapot, ha az még nem érhető el az indexben.

Végpont: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

Mentse ezt a példát browse.mjs néven, és futtassa a következővel: 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));

A sikeres 200 válasz tartalmazza a lapot url, title a kinyert content és a traceId elemet. Az élő bejárás visszatérhet retryAfter202 értékkel; várja meg ezt az időtartamot, majd küldje el újra ugyanazt a kérést. A teljes válaszszerződéshez tekintse meg a Browse API-referenciát .

Troubleshooting

Állapot Mit kell ellenőrizni?
401 Unauthorized Győződjön meg arról, hogy a(z) WEBIQ_API_KEY be van állítva, és a kérés a x-apikey fejlécben küldi el.
415 Unsupported Media Type Küldje el content-type: application/json.
429 Too Many Requests Várjon, mielőtt újra próbálkozik, és csökkentse a kérések gyakoriságát.
Tallózás 404 Not Found Győződjön meg arról, hogy az URL-cím nyilvános és érvényes. Használja a(z) liveCrawl: "fallback" elemet, ha előfordulhat, hogy az indexelt tartalom nem érhető el.
Tallózás 202 Accepted Várja meg a visszaadott retryAfter időtartamot, majd próbálja meg újra ugyanazt a kérést.

Egyéb hibák esetén mentse a traceId elemet, és tekintse meg a hibakezelést, vagy forduljon a Web IQ Supporthoz.

További lépések

  • Utolsó frissítés időpontja: