Guida introduttiva: Effettuare le prime chiamate Web IQ API

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

Se non si dispone già di una risorsa Web IQ, crearne una tramite il portale di Azure o interfaccia della riga di comando di Azure prima di continuare.

Scegliere un esempio di API REST o un esempio Python o TypeScript SDK di seguito. Gli SDK Python e TypeScript gestiscono automaticamente l'autenticazione, i nuovi tentativi e i tipi di risposta.

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

• Una chiave API Web IQ da Gestione profili.

Tip

Preferisce un avvio guidato senza codice? Seguire Introduzione al portale per sviluppatori di IQ Web: selezionare il profilo dell'app, creare una chiave API, inviare una richiesta da Playground, copiare il codice generato e controllare l'utilizzo.

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 SDK

Installare l'SDK con pip install webiq (Python 3.11 o versione successiva), quindi eseguire:

import os
from webiq import WebIQClient
from webiq.types import ContentFormat

with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
    results = client.web.search(
        "latest developments in retrieval augmented generation",
        max_results=10,
        content_format=ContentFormat.passage,
        max_length=3000,
    )
    for result in results.webResults or []:
        print(result.title, result.url)

TypeScript SDK

Installare l'SDK con npm install @microsoft/webiq (Node.js 22.18 o versione successiva). Salvare questo esempio come search.mts ed eseguirlo con node search.mts.

import { WebIQClient, ContentFormat } from "@microsoft/webiq";

async function main() {
  const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });

  try {
    const results = await client.web.search(
      "latest developments in retrieval augmented generation",
      {
        maxResults: 10,
        contentFormat: ContentFormat.PASSAGE,
        maxLength: 3000,
      },
    );
    for (const result of results.webResults ?? []) {
      console.log(result.title, result.url);
    }
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Python (REST)

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 (REST)

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 Web IQ Support a esaminare una richiesta.

Tra le risposte REST e i risultati degli strumenti MCP, i campi del modello con null o valori stringa vuota ("") vengono omessi, inclusi i campi degli oggetti risultato annidati; i campi elenco/matrice vuoti ([]) vengono mantenuti. Considerare un campo stringa assente come non disponibile e un campo elenco vuoto 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	Sfoglia	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 eseguire la scansione della pagina quando non è già disponibile nell'indice. La scansione in tempo reale è soggetta a restrizioni di cortesia e disponibilità dell'editore; fallback non garantisce una scansione effettiva.

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 SDK

Installare l'SDK con pip install webiq (Python 3.11 o versione successiva), quindi eseguire:

import os
from webiq import WebIQClient
from webiq.types import BrowseContentFormat

with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
    page = client.browse.fetch(
        "https://news.microsoft.com/source/",
        content_format=BrowseContentFormat.markdown,
        max_length=3000,
        live_crawl="fallback",
    )
    print(page.content)

TypeScript SDK

Installare l'SDK con npm install @microsoft/webiq (Node.js 22.18 o versione successiva). Salvare questo esempio come browse.mts ed eseguirlo con node browse.mts.

import { WebIQClient, BrowseContentFormat } from "@microsoft/webiq";

async function main() {
  const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });

  try {
    const page = await client.browse.fetch(
      "https://news.microsoft.com/source/",
      {
        contentFormat: BrowseContentFormat.MARKDOWN,
        maxLength: 3000,
        liveCrawl: "fallback",
      },
    );
    console.log(JSON.stringify(page, null, 2));
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Python (REST)

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 (REST)

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 ricerca per indicizzazione dinamica può restituire 202 con retryAfter, un timestamp UTC ISO 8601; attendere fino a quel momento, 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 fino all'ora in retryAfter (timestamp UTC ISO 8601), quindi inviare di nuovo la stessa richiesta.

Per altri errori, salvare traceId e vedere Gestione degli errori. Per contattare il supporto di Web IQ, includere il nome della società, il nome della risorsa Web IQ o del profilo dell'app e l'traceIdID area di lavoro.

Passaggi successivi

• Esplora i riferimenti API Ricerca Web e Sfoglia.
• Usare gli SDK Python e TypeScript.
• Installare il server MCP in Claude Code, Cursor o VS Code.
• Configurare l'autenticazione di produzione con Microsoft Entra ID.
• Eseguire esempi completi dai campioni di codice di Web IQ su GitHub.
• Segui il modulo di formazione Integra le informazioni basate sul Web nel tuo agente con Web IQ.
• Guarda Grounding degli agenti con intelligence del mondo reale, l'episodio Web IQ della serie Microsoft IQ.