Início Rápido: Fazer suas primeiras chamadas à API Web IQ

Faça sua primeira chamada à API REST do Microsoft Web IQ em alguns minutos. Você pesquisará na Web, inspecionará a resposta e extrairá conteúdo de uma URL conhecida.

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

Prerequisites

Tip

Use o Web IQ Playground para enviar solicitações pelo navegador e gerar código em cURL, Python, JavaScript, C#, Java, Go e Ruby.

1. Armazene sua chave de API

Coloque a chave em uma variável de ambiente para que os exemplos de solicitação não a repitam nem a coloque no 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ça commit da sua chave no controle de versão nem a exponha no navegador ou no código do lado do cliente. Armazene as credenciais de produção em um gerenciador de segredos.

2. Pesquisar na Web

Use a Pesquisa na Web quando você tiver uma pergunta ou consulta e quiser que o IQ da Web descubra e classifique páginas relevantes.

É recomendável definir maxResults = 10, maxLength = 3000 e contentFormat = passage em cada solicitação, como um ponto operacional otimizado. A partir daí, você pode ajustar essas configurações com base no seu caso de uso.

Ponto de extremidade: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

Salve 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. Entender a resposta

Uma pesquisa na Web bem-sucedida retorna um webResults array. Este exemplo abreviado mostra os campos que você 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 à consulta porque a solicitação usou contentFormat: "passage".
  • traceId ajuda o Suporte do Web IQ a investigar uma solicitação.

Entre as respostas REST e os resultados da ferramenta MCP, os campos de modelo com null, string vazia ("") ou lista/matriz vazia ([]) são omitidos, incluindo campos de objetos de resultado aninhados. Trate um campo de cadeia de caracteres ausente como indisponível e um campo de lista ausente como sem itens. Cadeias de caracteres somente de espaço em branco, false, 0, dicionários vazios, entradas individuais de array/dicionário e JSON bruto inserido são preservados. Arrays raiz e coleções de envelopes de protocolo, como MCP content, não são alteradas.

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

4. Escolha Pesquisa na Web ou Navegar

Começar com Usar O que você obtém
Uma pergunta ou pesquisa Pesquisa na Web Páginas classificadas com conteúdo relevante à consulta
Uma URL específica Navegar Conteúdo extraído dessa página

Um fluxo de trabalho de fundamentação comum usa ambos os endpoints: pesquise fontes relevantes, selecione uma URL de resultado e acesse essa URL quando precisar de conteúdo de página mais completo.

5. Extrair conteúdo de uma URL

Use Navegar quando você já souber qual página deseja ler. liveCrawl: "fallback" solicita que o Web IQ rastreie a página quando ela ainda não estiver disponível no índice.

Ponto de extremidade: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

Salve 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, titleextraída contente um traceId. Um rastreamento ao vivo pode retornar 202 com retryAfter; aguarde esse período e envie a mesma solicitação novamente. Consulte a referência da Browse API para o contrato de resposta completo.

Troubleshooting

Status O que verificar
401 Unauthorized Confirme WEBIQ_API_KEY se está definido e a solicitação o envia no x-apikey cabeçalho.
415 Unsupported Media Type Enviar content-type: application/json.
429 Too Many Requests Aguarde antes de tentar novamente e reduza a frequência de solicitação.
Procurar... 404 Not Found Confirme se a URL é pública e válida. Use liveCrawl: "fallback" quando o conteúdo indexado pode estar indisponível.
Procurar... 202 Accepted Aguarde a duração retornada em retryAfter e tente novamente a mesma solicitação.

Para outras falhas, salve o traceId e veja Tratamento de Erros ou contate o Suporte do Web IQ.

Próximas Etapas 

  • Última atualização em