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

Tip

No Microsoft Ignite 2026?Encontre todos os recursos de Perguntas Frequentes da Web em um só lugar: documentação, treinamento, exemplos de código e como entrar em contato com a equipe.

Faça sua primeira chamada à API Web IQ da Microsoft em alguns minutos. Pesquise na Web, inspecione a resposta e extraia passagens focadas em consulta de uma URL conhecida. Exemplos adicionais mostram o Places Search e a recuperação automática de evidências.

Se você ainda não tiver um recurso de Qi da Web, crie um usando o portal do Azure ou CLI do Azure antes de continuar.

Escolha um exemplo de SDK ou REST na parte superior desta página para alternar todos os exemplos juntos. Os SDKs gerenciam a autenticação, as novas tentativas e os tipos de retorno para você.

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

Note

Se o aplicativo for executado na China, chame https://api.microsoftol.com/v3 em vez de https://api.microsoft.ai/v3 para pontos de extremidade de pesquisa. Nos exemplos REST, substitua a URL. Ao construir um cliente SDK, defina a mesma URL base com o argumento base_url do Python, a opção baseUrl do TypeScript, o WebIqClient::builder().base_url(...) do Rust, o WebIQClientOptions.builder().baseUrl(...) do Java ou a propriedade WebIQClientOptions.BaseUrl do .NET. Consulte a URL base.

Tip

Prefere um início guiado sem código? Siga Primeiros passos no Web IQ Developer Portal: selecione o perfil do seu aplicativo, crie uma chave de API, envie uma solicitação do Playground, copie o código gerado e verifique seu uso.

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 --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
  }'

Instale o SDK com python -m pip install webiq==1.2.1 (Python 3.11 ou posterior) e execute:

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)

Instale o SDK com npm install @microsoft/webiq@1.2.1 (Node.js 22.18+ em 22.x ou 24+). Salve este exemplo como search.mts e execute-o com 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;
});

Em um projeto rust 1.88 ou posterior, execute cargo add webiq@1.2.1 e cargo add tokio --features macros,rt-multi-thread. Salve este exemplo como src/main.rs e execute cargo run.

use webiq::{ContentFormat, WebIqClient, WebSearchOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
    let results = client.web().search(
        "latest developments in retrieval augmented generation",
        WebSearchOptions::new()
            .max_results(10)
            .content_format(ContentFormat::Passage)
            .max_length(3000),
    ).await?;
    for result in results.web_results.unwrap_or_default() {
        println!("{:?} {:?}", result.title, result.url);
    }
    Ok(())
}

Em um projeto maven configurado para Java 11 ou posterior, adicione essa dependência apom.xml:

<dependency>
    <groupId>com.microsoft.webiq</groupId>
    <artifactId>webiq</artifactId>
    <version>1.2.1</version>
</dependency>

Salve este exemplo como src/main/java/Search.java e execute mvn compile exec:java -Dexec.mainClass=Search.

import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.ContentFormat;
import com.microsoft.webiq.models.WebResponse;
import com.microsoft.webiq.models.WebResult;
import com.microsoft.webiq.resources.WebSearchOptions;

public class Search {
    public static void main(String[] args) {
        try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
            WebResponse results = client.web.search(
                    "latest developments in retrieval augmented generation",
                    WebSearchOptions.builder()
                            .maxResults(10)
                            .contentFormat(ContentFormat.PASSAGE)
                            .maxLength(3000)
                            .build());
            if (results.getWebResults() != null) {
                for (WebResult result : results.getWebResults()) {
                    System.out.println(result.getTitle() + " " + result.getUrl());
                }
            }
        }
    }
}

Em um projeto de console .NET 8 ou posterior, execute dotnet add package Microsoft.WebIQ --version 1.2.1. Salve este exemplo como Program.cs e execute dotnet run.

using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;

string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
    ?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);

var results = await client.Web.SearchAsync(
    "latest developments in retrieval augmented generation",
    request =>
    {
        request.MaxResults = 10;
        request.ContentFormat = ContentFormat.Passage;
        request.MaxLength = 3000;
    });
foreach (var result in results.WebResults ?? [])
    Console.WriteLine($"{result.Title} {result.Url}");
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))

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 respostas REST e resultados da ferramenta MCP, os campos de modelo com null ou valores de cadeia de caracteres vazias ("") são omitidos, incluindo campos de objetos de resultado aninhados; campos de lista/matriz vazios ([]) são mantidos, exceto em Locais, onde campos de lista também podem estar ausentes. Trate um campo ausente como indisponível e uma lista vazia ou 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 um endpoint

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
Uma consulta local ou de empresa local Locais Detalhes do local estruturado, como endereços e horário de funcionamento
Uma consulta que precisa de tipos de resposta selecionados automaticamente Auto via REST ou SDKs 1.2.1 e posteriores Evidência textual com citações com escopo de resultado
Uma consulta de compra ou produto Commerce (versão prévia privada) por meio do REST Produtos classificados com ofertas de vendedor, preços e detalhes do produto

Um fluxo de trabalho de fundamentação comum usa ambos os pontos de extremidade: pesquisar fontes relevantes, selecionar uma URL de resultado e navegar até essa URL para extrair passagens relevantes para uma pergunta de acompanhamento.

5. Extrair conteúdo de uma URL

Use Navegar quando você já souber qual página deseja ler. Defina contentFormat como query e forneça um passage não vazio para recuperar as partes da página mais relevantes para sua pergunta.

liveCrawl: "fallback" solicita que o Web IQ rastreie a página quando ela ainda não estiver disponível no índice. O rastreamento ao vivo está sujeito a restrições de cortesia do publicador e à disponibilidade; fallback não garante um rastreamento real.

Todos os exemplos solicitam passagens com foco na consulta, o formato recomendado para fundamentação. A seleção query deve ser não vazia e não mais do que 1000 caracteres; maxLength controla separadamente a quantidade de conteúdo retornado. Formatos de documento completo (texte htmlmarkdown) exigem acesso completo ao documento.

Ponto de extremidade:POST https://api.microsoft.ai/v3/browse

curl --request POST "https://api.microsoft.ai/v3/browse" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    "query": "How fast is Web IQ",
    "contentFormat": "passage",
    "maxLength": 3000,
    "liveCrawl": "fallback"
  }'

Instale o SDK com python -m pip install webiq==1.2.1 (Python 3.11 ou posterior) e execute:

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://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
        query="How fast is Web IQ",
        content_format=BrowseContentFormat.passage,
        max_length=3000,
        live_crawl="fallback",
    )
    print(page.content)

Instale o SDK com npm install @microsoft/webiq@1.2.1 (Node.js 22.18+ em 22.x ou 24+). Salve este exemplo como browse.mts e execute-o com node browse.mts.

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

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

  try {
    const page = await client.browse.fetch(
      "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
      {
        query: "How fast is Web IQ",
        contentFormat: BrowseContentFormat.PASSAGE,
        maxLength: 3000,
        liveCrawl: LiveCrawlMode.FALLBACK,
      },
    );
    console.log(JSON.stringify(page, null, 2));
  } finally {
    await client.close();
  }
}

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

Em um projeto rust 1.88 ou posterior, execute cargo add webiq@1.2.1 e cargo add tokio --features macros,rt-multi-thread. Salve este exemplo como src/main.rs e execute cargo run.

use webiq::{BrowseContentFormat, BrowseOptions, LiveCrawlMode, WebIqClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
    let page = client.browse().fetch(
        "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
        BrowseOptions::new()
            .query("How fast is Web IQ")
            .content_format(BrowseContentFormat::Passage)
            .max_length(3000)
            .live_crawl(LiveCrawlMode::Fallback),
    ).await?;
    println!("{}", page.content.unwrap_or_default());
    Ok(())
}

Em um projeto maven configurado para Java 11 ou posterior, adicione essa dependência apom.xml:

<dependency>
    <groupId>com.microsoft.webiq</groupId>
    <artifactId>webiq</artifactId>
    <version>1.2.1</version>
</dependency>

Salve este exemplo como src/main/java/Browse.java e execute mvn compile exec:java -Dexec.mainClass=Browse.

import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.BrowseContentFormat;
import com.microsoft.webiq.models.BrowseResponse;
import com.microsoft.webiq.models.LiveCrawlMode;
import com.microsoft.webiq.resources.BrowseFetchOptions;

public class Browse {
    public static void main(String[] args) {
        try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
            BrowseResponse page = client.browse.fetch(
                    "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
                    BrowseFetchOptions.builder()
                            .query("How fast is Web IQ")
                            .contentFormat(BrowseContentFormat.PASSAGE)
                            .maxLength(3000)
                            .liveCrawl(LiveCrawlMode.FALLBACK)
                            .build());
            System.out.println(page.getContent());
        }
    }
}

Em um projeto de console .NET 8 ou posterior, execute dotnet add package Microsoft.WebIQ --version 1.2.1. Salve este exemplo como Program.cs e execute dotnet run.

using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;

string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
    ?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);

var page = await client.Browse.FetchAsync(
    "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    request =>
    {
        request.ContentFormat = BrowseContentFormat.Passage;
        request.Query = "How fast is Web IQ";
        request.MaxLength = 3000;
        request.LiveCrawl = LiveCrawlMode.Fallback;
    });
Console.WriteLine(page.Content);
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://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
        "query": "How fast is Web IQ",
        "contentFormat": "passage",
        "maxLength": 3000,
        "liveCrawl": "fallback",
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

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://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    query: "How fast is Web IQ",
    contentFormat: "passage",
    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 retryAfterum carimbo de data/hora UTC ISO 8601; aguarde até esse momento e envie a mesma solicitação novamente. Consulte a referência da Browse API para o contrato de resposta completo.

6. Pesquisar locais (opcional)

Use a Pesquisa de Locais para obter informações estruturadas sobre empresas locais e outros locais. Os exemplos do SDK usam os pacotes 1.2.1 instalados na etapa 2.

Ponto de extremidade:POST https://api.microsoft.ai/v3/search/places

curl --request POST "https://api.microsoft.ai/v3/search/places" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "coffee in Seattle",
    "maxResults": 5,
    "language": "en",
    "region": "US",
    "location": "lat:47.6062;long:-122.3321"
  }'
import os
from webiq import WebIQClient

with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
    places = client.places.search(
        "coffee in Seattle",
        max_results=5,
        language="en",
        region="US",
        location="lat:47.6062;long:-122.3321",
    )
    for place in places.placeResults or []:
        print(place.name, place.businessUrl)

Salve este exemplo como places.mts e execute-o com node places.mts.

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

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

  try {
    const places = await client.places.search("coffee in Seattle", {
      maxResults: 5,
      language: "en",
      region: "US",
      location: "lat:47.6062;long:-122.3321",
    });
    for (const place of places.placeResults ?? []) {
      console.log(place.name, place.businessUrl);
    }
  } finally {
    await client.close();
  }
}

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

Use a configuração do Tokio da etapa 2. Salve este exemplo como src/main.rs e execute cargo run.

use webiq::{PlacesSearchOptions, WebIqClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
    let places = client.places().search(
        "coffee in Seattle",
        PlacesSearchOptions::new()
            .max_results(5)
            .language("en")
            .region("US")
            .location("lat:47.6062;long:-122.3321"),
    ).await?;
    for place in places.place_results.unwrap_or_default() {
        println!("{:?} {:?}", place.name, place.business_url);
    }
    Ok(())
}

Salve este exemplo como src/main/java/Places.java no projeto Maven da etapa 2 e execute mvn compile exec:java -Dexec.mainClass=Places.

import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.PlaceItem;
import com.microsoft.webiq.models.PlacesResponse;
import com.microsoft.webiq.resources.PlacesSearchOptions;

public class Places {
    public static void main(String[] args) {
        try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
            PlacesResponse places = client.places.search("coffee in Seattle",
                    PlacesSearchOptions.builder().maxResults(5)
                            .language("en").region("US")
                            .location("lat:47.6062;long:-122.3321").build());
            if (places.getPlaceResults() != null) {
                for (PlaceItem place : places.getPlaceResults()) {
                    System.out.println(place.getName() + " " + place.getBusinessUrl());
                }
            }
        }
    }
}

No projeto de console .NET da etapa 2, salve este exemplo como Program.cs e execute dotnet run.

using Microsoft.WebIQ;

string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
    ?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);

var places = await client.Places.SearchAsync("coffee in Seattle", request =>
{
    request.MaxResults = 5;
    request.Language = "en";
    request.Region = "US";
    request.Location = "lat:47.6062;long:-122.3321";
});
foreach (var place in places.PlaceResults ?? [])
    Console.WriteLine($"{place.Name} {place.BusinessUrl}");
import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/search/places",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "query": "coffee in Seattle",
        "maxResults": 5,
        "language": "en",
        "region": "US",
        "location": "lat:47.6062;long:-122.3321",
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Salve este exemplo como places.mjs e execute-o com node places.mjs.

const response = await fetch("https://api.microsoft.ai/v3/search/places", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "coffee in Seattle",
    maxResults: 5,
    language: "en",
    region: "US",
    location: "lat:47.6062;long:-122.3321",
  }),
});

if (!response.ok) {
  throw new Error(`Places failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

Ler os resultados de placeResults. A lista e os campos individuais podem estar ausentes, portanto, verifique se há valores ausentes antes de usar endereços, horários de funcionamento ou outros detalhes. Consulte a referência da API Places.

7. Recuperar evidências com Auto

Use o Auto quando quiser que o Web IQ selecione fontes de recuperação e retorne evidências tipadas com citações de suporte. Faça uma pergunta completa em linguagem natural, mantendo restrições relevantes, como datas, locais e unidades. Esses exemplos omitem mode para usar o padrão e permitir 60 segundos para cada tentativa de solicitação. Defina mode para advanced no Auto Advanced quando precisar de recuperação mais abrangente para perguntas complexas.

Retorna automaticamente evidências para seu aplicativo usar, não uma resposta final gerada. Ler cada resultado de evidência com suas próprias citações; não trate citações de um resultado como suporte para outro. Os exemplos do SDK usam a versão 1.2.1 de todos os cinco SDKs, instalados na etapa 2.

Ponto de extremidade:POST https://api.microsoft.ai/v3/auto

curl --request POST "https://api.microsoft.ai/v3/auto" \
  --max-time 60 \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "What are the latest developments in retrieval-augmented generation?",
    "maxResponseLength": 30000,
    "maxCitations": 5
  }'
import os
from webiq import WebIQClient

with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
    evidence = client.auto.search(
        "What are the latest developments in retrieval-augmented generation?",
        max_response_length=30000,
        max_citations=5,
        timeout=60.0,
    )
    for result in evidence.results or []:
        print(result.evidence)
        for citation in result.citations or []:
            print(citation.title, citation.url)

Salve este exemplo como auto.mts e execute-o com node auto.mts.

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

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

  try {
    const evidence = await client.auto.search(
      "What are the latest developments in retrieval-augmented generation?",
      { maxResponseLength: 30000, maxCitations: 5, timeout: 60_000 },
    );
    for (const result of evidence.results ?? []) {
      console.log(result.evidence);
      for (const citation of result.citations ?? []) {
        console.log(citation.title, citation.url);
      }
    }
  } finally {
    await client.close();
  }
}

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

Use a configuração do Tokio da etapa 2. Salve este exemplo como src/main.rs e execute cargo run.

use webiq::{AutoSearchOptions, WebIqClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
    let evidence = client.auto().search(
        "What are the latest developments in retrieval-augmented generation?",
        AutoSearchOptions::new()
            .max_response_length(30000)
            .max_citations(5)
            .timeout(std::time::Duration::from_secs(60)),
    ).await?;
    for result in evidence.results.unwrap_or_default() {
        println!("{:?}", result.evidence);
        for citation in result.citations.unwrap_or_default() {
            println!("{:?} {:?}", citation.title, citation.url);
        }
    }
    Ok(())
}

Salve este exemplo como src/main/java/Auto.java no projeto Maven da etapa 2 e execute mvn compile exec:java -Dexec.mainClass=Auto.

import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.AutoEvidenceCitation;
import com.microsoft.webiq.models.AutoEvidenceResult;
import com.microsoft.webiq.models.SearchAutoEvidenceResponse;
import com.microsoft.webiq.resources.AutoSearchOptions;

public class Auto {
    public static void main(String[] args) {
        try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
            SearchAutoEvidenceResponse evidence = client.auto.search(
                    "What are the latest developments in retrieval-augmented generation?",
                    AutoSearchOptions.builder()
                            .maxResponseLength(30000).maxCitations(5)
                            .timeout(java.time.Duration.ofSeconds(60)).build());
            if (evidence.getResults() != null) {
                for (AutoEvidenceResult result : evidence.getResults()) {
                    System.out.println(result.getEvidence());
                    if (result.getCitations() != null) {
                        for (AutoEvidenceCitation citation : result.getCitations()) {
                            System.out.println(citation.getTitle() + " " + citation.getUrl());
                        }
                    }
                }
            }
        }
    }
}

No projeto de console .NET da etapa 2, salve este exemplo como Program.cs e execute dotnet run.

using Microsoft.WebIQ;
using System.Text.Json;

string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
    ?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);

var evidence = await client.Auto.SearchAsync(
    "What are the latest developments in retrieval-augmented generation?",
    request =>
    {
        request.MaxResponseLength = 30000;
        request.MaxCitations = 5;
    }, timeout: TimeSpan.FromSeconds(60));
foreach (var result in evidence.Results ?? [])
{
    Console.WriteLine(JsonSerializer.Serialize(result.Evidence));
    foreach (var citation in result.Citations ?? [])
        Console.WriteLine($"{citation.Title} {citation.Url}");
}
import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/auto",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "query": "What are the latest developments in retrieval-augmented generation?",
        "maxResponseLength": 30000,
        "maxCitations": 5,
    },
    timeout=60,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Salve este exemplo como auto.mjs e execute-o com node auto.mjs.

const response = await fetch("https://api.microsoft.ai/v3/auto", {
  method: "POST",
  signal: AbortSignal.timeout(60_000),
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "What are the latest developments in retrieval-augmented generation?",
    maxResponseLength: 30000,
    maxCitations: 5,
  }),
});

if (!response.ok) {
  throw new Error(`Auto failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

Uma resposta bem-sucedida contém um results array. Cada resultado emparelha um objeto tipado evidence com seu citations de suporte. Um array results vazio ou ausente não tem nenhuma evidência para processar. Consulte a referência da API Auto para tipos de evidência, exemplos de resposta e limites de solicitação.

8. Pesquisar produtos com Commerce (opcional)

Use as APIs de Comércio para encontrar ofertas de produtos e vendedores para uma consulta de compras: Search retorna produtos classificados com suas ofertas de vendedor primário, Offers retorna mais ofertas para um produto e Product Details retorna o título, a descrição e a classificação de um produto.

Note

As APIs de Comércio estão em versão prévia privada e estão incluídas com AppIDs que têm acesso total ao documento. O acesso é habilitado separadamente para cada ponto de extremidade. Se o AppID não os tiver, abra uma solicitação do Web IQ Support (tipo de problema Authentication & Access) com seu AppID.

Endpoints:POST https://api.microsoft.ai/v3/search/commerce/products, POST https://api.microsoft.ai/v3/fetch/commerce/products/offers, e POST https://api.microsoft.ai/v3/fetch/commerce/products/details

Esta etapa mostra as chamadas REST. Escolha cURL, Python (REST) ou JavaScript (REST) na parte superior da página para vê-los.

Pesquise por produtos:

curl --request POST "https://api.microsoft.ai/v3/search/commerce/products" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "wireless headphones",
    "maxResults": 3,
    "language": "en",
    "region": "US"
  }'

Do primeiro produto na resposta, copie seu id, seu skuIde a id primeira oferta. Substitua PRODUCT_ID, SKU_ID e OFFER_ID abaixo, depois consulte mais ofertas e os detalhes do produto. Alguns produtos retornam apenas uma oferta, sem id ou skuId: envie somente as ofertas offerId e ignore Product Details, que precisa de um produto ou ID de SKU.

curl --request POST "https://api.microsoft.ai/v3/fetch/commerce/products/offers" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "productId": "PRODUCT_ID",
    "skuId": "SKU_ID",
    "offerId": "OFFER_ID",
    "language": "en",
    "region": "US"
  }'

curl --request POST "https://api.microsoft.ai/v3/fetch/commerce/products/details" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "productId": "PRODUCT_ID",
    "skuId": "SKU_ID",
    "language": "en",
    "region": "US"
  }'
import json
import os
import requests

BASE_URL = "https://api.microsoft.ai/v3"
HEADERS = {
    "x-apikey": os.environ["WEBIQ_API_KEY"],
    "content-type": "application/json",
}
MARKET = {"language": "en", "region": "US"}


def post(path, body):
    response = requests.post(BASE_URL + path, headers=HEADERS, json=body, timeout=30)
    response.raise_for_status()
    return response.json()


search = post("/search/commerce/products", {"query": "wireless headphones", "maxResults": 3, **MARKET})
products = search.get("products") or []
if not products:
    print("No matching products.")
else:
    product = products[0]
    first_offer = (product.get("offers") or [{}])[0]
    ids = {"productId": product.get("id"), "skuId": product.get("skuId")}
    ids = {key: value for key, value in ids.items() if value}
    offer_ids = {**ids, "offerId": first_offer.get("id")} if first_offer.get("id") else ids

    offers = post("/fetch/commerce/products/offers", {**offer_ids, **MARKET})
    # Product Details needs a product id or SKU id; some products return only an offer.
    details = post("/fetch/commerce/products/details", {**ids, **MARKET}) if ids else None
    print(json.dumps({"product": product, "offers": offers, "details": details}, indent=2))

Salve este exemplo como commerce.mjs e execute-o com node commerce.mjs.

const baseUrl = "https://api.microsoft.ai/v3";
const headers = {
  "x-apikey": process.env.WEBIQ_API_KEY,
  "content-type": "application/json",
};
const market = { language: "en", region: "US" };

async function post(path, body) {
  const response = await fetch(`${baseUrl}${path}`, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    throw new Error(`${path} failed: ${response.status} ${await response.text()}`);
  }
  return response.json();
}

const search = await post("/search/commerce/products", {
  query: "wireless headphones",
  maxResults: 3,
  ...market,
});
const product = search.products?.[0];
if (!product) {
  console.log("No matching products.");
} else {
  const ids = {};
  if (product.id) ids.productId = product.id;
  if (product.skuId) ids.skuId = product.skuId;
  const offerId = product.offers?.[0]?.id;
  const offerIds = offerId ? { ...ids, offerId } : ids;

  const offers = await post("/fetch/commerce/products/offers", { ...offerIds, ...market });
  // Product Details needs a product id or SKU id; some products return only an offer.
  const details = Object.keys(ids).length
    ? await post("/fetch/commerce/products/details", { ...ids, ...market })
    : null;
  console.log(JSON.stringify({ product, offers, details }, null, 2));
}

A pesquisa retorna produtos em ordem de classificação com suas ofertas de vendedor primário; maxResults limita produtos, não ofertas. As ofertas retornam a oferta primária primeiro, seguidas por ofertas adicionais. Uma solicitação válida sem correspondência retorna 200 OK com uma matriz offers ou products vazia. Os preços são inteiros nas unidades secundárias da moeda: 39999 USD é de US$ 399,99.

Para enviar um usuário, ou um agente que atua para o usuário, para uma oferta, use o clickUrl da oferta exatamente como retornado nessa resposta. Não use displayUrl, que identifica apenas o comerciante e não reescreva, reduza ou reutilize o link. Crie links no código do aplicativo em vez de fazer com que um modelo os reproduza. Confira Links e atribuição da oferta e o guia de Comércio.

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 até o horário em retryAfter (um carimbo de data/hora UTC ISO 8601) e envie a mesma solicitação novamente.
Automático 403 Forbidden Verifique se o Auto está listado em Serviços Permitidos no Gerenciamento de Perfil. Se não estiver, abra uma solicitação de suporte do Web IQ com seu AppID.

Para outras falhas, salve o traceId e consulte Tratamento de Erros. Para entrar em contato com o Suporte do Web IQ, inclua o traceId e seu AppID, ou o nome da sua empresa e o nome do recurso do Web IQ se você não tiver o AppID.

Próximas Etapas