Démarrage rapide : Effectuer vos premiers appels d’API Web IQ

Effectuez votre premier appel à l’API REST Microsoft Web IQ en quelques minutes. Vous allez effectuer une recherche sur le web, inspecter la réponse, puis extraire du contenu à partir d’une URL connue.

Les clés API sont le moyen le plus rapide d’évaluer Web IQ. Pour les charges de travail de production, utilisez Microsoft Entra ID.

Prerequisites

Tip

Utilisez Web IQ Playground pour envoyer des requêtes à partir du navigateur et générer du code dans cURL, Python, JavaScript, C#, Java, Go et Ruby.

1. Stockez votre clé API

Placez la clé dans une variable d’environnement afin que les exemples de requête ne la répètent pas et ne l’incluent pas dans votre code source.

macOS ou Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

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

Warning

Ne commitez pas votre clé dans le contrôle de version et ne l’exposez pas dans le code côté navigateur ou côté client. Stockez les informations d’identification de production dans un gestionnaire de secrets.

2. Rechercher sur le web

Utilisez la recherche web lorsque vous avez une question ou une requête et souhaitez que Web IQ découvre et classe les pages pertinentes.

Nous vous recommandons de définir maxResults = 10, contentFormat = passageet maxLength = 3000 sur chaque requête en tant que point d’exploitation optimisé. À partir de là, vous pouvez affiner ces paramètres en fonction de votre cas d’usage.

Point de terminaison :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

Enregistrez cet exemple comme search.mjs et exécutez-le avec 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. Comprendre la réponse

Une recherche web réussie retourne un tableau webResults. Cet exemple abrégé montre les champs que vous utiliserez le plus souvent :

{
  "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 et url identifient la source.
  • content contient le passage pertinent pour la requête, car la requête utilisait contentFormat: "passage".
  • traceId aide web IQ Support à examiner une demande.

Dans les réponses REST et les résultats de l’outil MCP, les champs de modèle avec des valeurs null, de chaîne vide ("") ou de liste/tableau vide ([]) sont omis, y compris les champs d’objets de résultats imbriqués. Traitez un champ de chaîne absent comme indisponible et un champ de liste absent comme n’ayant aucun élément. Les chaînes contenant uniquement des espaces, false, 0, les dictionnaires vides, les entrées de tableau/dictionnaire individuelles et le JSON brut incorporé sont conservés. Les tableaux racines et les collections d’enveloppes de protocole telles que MCP content sont inchangés.

Consultez la référence de l’API Recherche web pour tous les paramètres et champs de réponse.

4. Choisir la recherche Web ou Parcourir

Commencez par Utiliser Ce que vous obtenez
Une question ou une requête de recherche Recherche web Pages classées avec du contenu pertinent pour la requête
Une URL spécifique Parcourir Contenu extrait de cette page

Un flux de travail de base courant utilise les deux points de terminaison API : recherchez des sources pertinentes, sélectionnez une URL de résultat, puis parcourez cette URL lorsque vous avez besoin d’un contenu de page plus complet.

5. Extraire du contenu d’une URL

Utilisez Browse lorsque vous connaissez déjà la page que vous souhaitez lire. liveCrawl: "fallback" demande à Web IQ d’analyser la page lorsqu’elle n’est pas déjà disponible dans l’index.

Point de terminaison :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

Enregistrez cet exemple comme browse.mjs et exécutez-le avec 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));

Une réponse réussie 200 inclut la page url, title, l’élément extrait content, et un traceId. Une analyse dynamique peut retourner 202 avec retryAfter; attendre cette durée, puis renvoyer la même requête. Consultez la référence de l’API Browse pour le contrat de réponse complet.

Troubleshooting

Status Que vérifier
401 Unauthorized Vérifiez que WEBIQ_API_KEY est défini et que la requête l’envoie dans l’en-tête x-apikey.
415 Unsupported Media Type Envoyer content-type: application/json.
429 Too Many Requests Attendez avant de réessayer et réduisez la fréquence des requêtes.
Parcourir 404 Not Found Vérifiez que l’URL est publique et valide. Utiliser liveCrawl: "fallback" lorsque le contenu indexé peut être indisponible.
Parcourir 202 Accepted Attendez la durée renvoyée retryAfter, puis réessayez la même requête.

Pour d’autres échecs, enregistrez le traceId et consultez la gestion des erreurs ou contactez le support Web IQ.

Étapes suivantes

  • Dernière mise à jour :