Inicio rápido: Realización de las primeras llamadas api de Web IQ

Realice la primera llamada a la API REST de Microsoft Web IQ en unos minutos. Buscará en la web, inspeccionará la respuesta y, a continuación, extraerá contenido de una dirección URL conocida.

Las claves de API son la manera más rápida de evaluar Web IQ. En el caso de las cargas de trabajo de producción, use Microsoft Entra ID.

Prerequisites

Sugerencia

Usa Web IQ Playground para enviar solicitudes desde el explorador y generar código en cURL, Python, JavaScript, C#, Java, Go y Ruby.

1. Almacenar la clave de API

Coloque la clave en una variable de entorno para que los ejemplos de solicitud no la repitan ni la coloquen en el código fuente.

macOS o Linux

export WEBIQ_API_KEY="your-api-key"

PowerShell de Windows

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

Warning

No suba la clave al control de código fuente ni expórmela en el explorador o en el código del lado cliente. Almacene las credenciales de producción en un gestor de secretos.

2. Buscar en la web

Utiliza Web Search cuando tenga una pregunta o consulta y desee que Web IQ detecte y clasifique las páginas pertinentes.

Se recomienda establecer maxResults = 10, contentFormat = passagey maxLength = 3000 en cada solicitud como punto operativo optimizado. Desde allí, puede ajustar esta configuración en función de su caso de uso.

Punto final: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

Guarde este ejemplo como search.mjs y ejecútelo 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. Comprender la respuesta

Una búsqueda web correcta devuelve un webResults array. En este ejemplo abreviado se muestran los campos que usará con más frecuencia:

{
  "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 identifican el origen.
  • content contiene el pasaje pertinente para la consulta porque la solicitud usó contentFormat: "passage".
  • traceId ayuda al soporte técnico de Web IQ a investigar una solicitud.

En las respuestas REST y los resultados de la herramienta MCP, se omiten los campos de modelo con null, valores de cadena vacía ("") o lista o matriz vacía ([]), incluidos los campos de objetos de resultado anidados. Trate un campo de cadena ausente como no disponible y un campo de lista ausente como vacío. Se conservan las cadenas de solo espacios en blanco, false, 0, diccionarios vacíos, entradas individuales de arrays/diccionarios y JSON sin formato incrustado. Las matrices raíz y las colecciones de sobres de protocolo, como MCP content , no se modifican.

Consulte la referencia de Web Search API para todos los parámetros y campos de respuesta.

4. Elija Búsqueda web o Examinar

Comenzar con una Uso Lo que obtienes
Una pregunta o consulta de búsqueda Búsqueda web Páginas clasificadas con contenido relevante para la consulta
Una dirección URL específica Navegar Contenido extraído de esa página

Un flujo de trabajo de fundamentación común usa ambos endpoints: busque fuentes relevantes, seleccione una dirección URL de resultado y, a continuación, examine esa dirección URL cuando necesite contenido de página más completo.

5. Extraer contenido de una dirección URL

Utilice Browse cuando ya sepa qué página desea leer. liveCrawl: "fallback" pide a Web IQ que rastree la página cuando no está ya disponible en el índice.

Punto final: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

Guarde este ejemplo como browse.mjs y ejecútelo 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 respuesta satisfactoria 200 incluye la página url, title, extraído content y un traceId. Un rastreo en vivo puede devolver 202 con retryAfter; espere ese tiempo y, a continuación, envíe la misma solicitud de nuevo. Consulte la referencia de Browse API para obtener el contrato de respuesta completo.

Troubleshooting

Status Elementos que se deben comprobar
401 Unauthorized Confirme que WEBIQ_API_KEY está establecido y que la solicitud lo envía en el encabezado x-apikey.
415 Unsupported Media Type Envíe content-type: application/json.
429 Too Many Requests Espere antes de reintentar y reduzca la frecuencia de las solicitudes.
Explorar 404 Not Found Confirme que la dirección URL es pública y válida. Utilice liveCrawl: "fallback" cuando el contenido indizado podría no estar disponible.
Explorar 202 Accepted Espere durante el tiempo devuelto retryAfter y vuelva a intentar la misma solicitud.

En caso de otros fallos, guarde el traceId y consulte Control de errores o póngase en contacto con el soporte técnico de Web IQ.

Pasos siguientes

  • Se actualizó por última vez el