Início Rápido: Faça as suas primeiras chamadas à Web IQ API

Faça a sua primeira chamada Microsoft Web IQ REST API em poucos minutos. Vais pesquisar na web, inspecionar a resposta e depois extrair conteúdo de uma URL conhecida.

As chaves API são a forma mais rápida de avaliar o Web IQ. Para cargas de trabalho de produção, use o Microsoft Entra ID.

Pré-requisitos

Tip

Use o Web IQ Playground para enviar pedidos a partir do navegador e gerar código em cURL, Python, JavaScript, C#, Java, Go e Ruby.

1. Armazene a sua chave API

Coloca a chave numa variável de ambiente para que os exemplos de pedido não a repitam nem a coloquem no teu código-fonte.

macOS ou Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

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

Warning

Não faças commit da tua chave no controlo de versões nem a exponhas em código do navegador ou do lado do cliente. Guarda as credenciais de produção num gestor de segredos.

2. Pesquise na internet

Utilize o Web Search quando tiver uma dúvida ou consulta e quiser que o Web IQ descubra e classifique páginas relevantes.

Recomendamos definir maxResults = 10, contentFormat = passage e maxLength = 3000 em cada solicitação como um ponto operacional otimizado. A partir daí, pode ajustar estas definições com base no seu caso de uso.

Ponto 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 exemplo como search.mjs e execute-o com 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. Compreender a resposta

Uma pesquisa web bem-sucedida devolve um webResults array. Este exemplo abreviado mostra os campos que irá usar com mais frequência:

{
  "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 identificam a origem.
  • content contém a passagem relevante para a consulta porque o pedido usou contentFormat: "passage".
  • traceId ajuda o Suporte Web IQ a investigar um pedido.

Em respostas REST e resultados da ferramenta MCP, os campos de modelo com valores nulos (null), string vazia ("") ou lista/array vazia ([]) são omitidos, incluindo campos de objetos de resultado aninhados. Trate um campo de string ausente como indisponível e um campo de lista ausente como sem itens. As strings apenas de espaços em branco, false, 0, dicionários vazios, entradas individuais de array/dicionário e JSON bruto incorporado são preservados. Os arrays raiz e as coleções de envelopes de protocolo, como o MCP content , mantêm-se inalteradas.

Consulte a referência da Web Search API para todos os parâmetros e campos de resposta.

4. Escolha Pesquisa na Web ou Navegue

Comece com Use O que obtém
Uma pergunta ou consulta de pesquisa Pesquisa na Web Páginas classificadas por relevância com conteúdo relevante para a consulta
Um URL específico Navegar Conteúdo extraído dessa página

Um fluxo de trabalho comum de grounding usa ambos os endpoints: procura fontes relevantes, seleciona uma URL de resultado e depois navega por essa URL quando precisas de conteúdo de página mais completo.

5. Extrair conteúdo de uma URL

Usa Procurar quando já souberes qual a página que queres ler. liveCrawl: "fallback" pede ao Web IQ para rastrear a página quando ainda não está disponível no índice.

Ponto 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 exemplo como browse.mjs e execute-o com 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));

Uma resposta bem-sucedida 200 inclui a página url, title, conteúdo extraído content e um traceId. Um rastreamento ao vivo pode devolver 202 com retryAfter; esperar durante esse tempo e depois enviar o mesmo pedido novamente. Consulte a referência Browse API para o contrato de resposta completo.

Troubleshooting

Status O que deve verificar
401 Unauthorized Confirme que WEBIQ_API_KEY está definido e o pedido envia-o no cabeçalho x-apikey.
415 Unsupported Media Type Enviar content-type: application/json.
429 Too Many Requests Espere antes de tentar novamente e reduza a frequência dos pedidos.
Procurar 404 Not Found Confirma que o URL é público e válido. Utilize liveCrawl: "fallback" quando o conteúdo indexado pode não estar disponível.
Procurar 202 Accepted Aguarde pela duração devolvida retryAfter e depois tente novamente a mesma solicitação.

Para outras falhas, guarde o registo traceId e consulte a Gestão de Erros ou contacte o Suporte Web IQ.

Passos seguintes

  • Última atualização a