Guida introduttiva: Effettuare le prime chiamate Web IQ API

Effettuare la prima chiamata Microsoft Web IQ REST API in pochi minuti. Cercherai nel Web, esaminerai la risposta e quindi estrarrai il contenuto da un URL noto.

Le chiavi API rappresentano il modo più rapido per valutare l'IQ Web. Per i carichi di lavoro di produzione, usare Microsoft Entra ID.

Prerequisites

Tip

Usare Web IQ Playground per inviare richieste dal browser e generare codice in cURL, Python, JavaScript, C#, Java, Go e Ruby.

1. Archiviare la chiave API

Inserire la chiave in una variabile di ambiente in modo che gli esempi di richiesta non la ripetano o la inseriscano nel codice sorgente.

macOS o Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

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

Warning

Non eseguire il commit della chiave nel controllo del codice sorgente né esporla nel browser o nel codice lato client. Memorizza le credenziali di produzione in un Secret Manager.

2. Cerca nel Web

Usare Ricerca Web quando si ha una domanda o una query e si vuole che L'IQ Web rilevi e classifica le pagine pertinenti.

È consigliabile impostare maxResults = 10, contentFormat = passagee maxLength = 3000 su ogni richiesta come punto operativo ottimizzato. Da qui è possibile ottimizzare queste impostazioni in base al caso d'uso.

Endpoint: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

Salvare questo esempio come search.mjs ed eseguirlo con 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. Comprendere la risposta

Una ricerca Web riuscita restituisce un webResults array. Questo esempio abbreviato mostra i campi che verranno usati più spesso:

{
  "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 e url identificano l'origine.
  • content contiene il passaggio rilevante per la query perché la richiesta ha usato contentFormat: "passage".
  • traceId aiuta il supporto di IQ Web a analizzare una richiesta.

Tra le risposte REST e i risultati degli strumenti MCP, i campi del modello con null, una stringa vuota ("") o valori di lista/array vuoti ([]) vengono omessi, inclusi i campi degli oggetti risultato annidati. Considerare un campo stringa assente come non disponibile e un campo elenco assente come senza elementi. Vengono mantenute stringhe contenenti solo spazi, false, 0, dizionari vuoti, singole voci di matrice/dizionario e JSON non elaborato incorporato. Le matrici radice e le collezioni protocol-envelope, ad esempio MCP content, sono invariate.

Vedere le informazioni di riferimento sull'API Ricerca Web per tutti i parametri e i campi di risposta.

4. Scegli Ricerca Web o Esplora

Avvia con Utilizza Cosa ottieni
Una domanda o una query di ricerca Ricerca Web Pagine classificate con contenuto pertinente per le query
un URL specifico Esplora Contenuto estratto da tale pagina

Un flusso di lavoro comune usa entrambi gli endpoint: cercare le fonti pertinenti, selezionare un URL dei risultati, quindi sfogliare tale URL quando è necessario un contenuto di pagina più completo.

5. Estrarre il contenuto da un URL

Usare Sfoglia quando si conosce già la pagina da leggere. liveCrawl: "fallback" chiede a Web IQ di sottoporre la pagina a scansione quando non è già disponibile nell'indice.

Endpoint: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

Salvare questo esempio come browse.mjs ed eseguirlo con 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));

Una risposta riuscita 200 include la pagina url, title, estratti content e un traceId. Una scansione live può restituire 202 con retryAfter; attendere per tale periodo, quindi inviare di nuovo la stessa richiesta. Vedere le informazioni di riferimento sulla Browse API per la struttura completa della risposta.

Troubleshooting

Stato Controlli da eseguire
401 Unauthorized Verificare che WEBIQ_API_KEY sia impostato e che la richiesta lo invii nell'intestazione x-apikey.
415 Unsupported Media Type Invia content-type: application/json.
429 Too Many Requests Attendere prima di riprovare e ridurre la frequenza delle richieste.
Sfoglia 404 Not Found Verificare che l'URL sia pubblico e valido. Usare liveCrawl: "fallback" quando il contenuto indicizzato potrebbe non essere disponibile.
Sfoglia 202 Accepted Attendere per la durata restituita retryAfter, quindi ripetere la stessa richiesta.

Per altre anomalie, salvare traceId e vedere Gestione degli errori o contattare il supporto di Web IQ.

Passaggi successivi

  • Ultimo aggiornamento: