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

Tip

No Microsoft Ignite 2026?Encontre todos os recursos Web IQ num só lugar: documentação, formação, exemplos de código e como contactar a equipa.

Faça a sua primeira chamada para a API Microsoft Web IQ dentro de alguns minutos. Pesquise na web, inspecione a resposta e extraia passagens focadas em consultas a partir de uma URL conhecida. Exemplos adicionais mostram Places Search e Auto evidence retrieval.

Se ainda não tens um recurso Web IQ, cria um usando o portal Azure ou o CLI do Azure antes de continuar.

Escolha um SDK ou exemplo REST no topo desta página para alternar todos os exemplos juntos. Os SDKs tratam da autenticação, novas tentativas e tipos de resposta por si.

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

Note

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

Tip

Prefere um início guiado sem código? Siga Introdução no Portal Web IQ para Desenvolvedores: selecione o perfil da sua aplicação, crie uma chave API, envie um pedido do Playground, copie o código gerado e verifique o seu uso.

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"

PowerShell do Windows

$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.

Endpoint: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 depois 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)

Instala o SDK com npm install @microsoft/webiq@1.2.1 (Node.js 22.18+ no 22.x, ou 24+). Guarde 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;
});

Num projeto Rust 1.88 ou posterior, execute cargo add webiq@1.2.1 e cargo add tokio --features macros,rt-multi-thread. Guarde 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(())
}

Num projeto Maven configurado para Java 11 ou posterior, adicione esta dependência a pom.xml:

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

Guarde 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());
                }
            }
        }
    }
}

Num projeto de consola .NET 8 ou posterior, execute dotnet add package Microsoft.WebIQ --version 1.2.1. Guarde 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))

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

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 Procurar Conteúdo extraído dessa página
Uma consulta de lugar ou empresa local Locais Detalhes estruturados do local, como moradas e horários de funcionamento
Uma consulta que necessita de tipos de resposta selecionados automaticamente Auto por REST ou SDKs 1.2.1 e posteriores Evidência escrita com citações ao nível do resultado
Uma consulta de compras ou de produto Comércio (pré-visualização privada) através do REST Produtos classificados com ofertas dos vendedores, preços e detalhes do produto

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 para extrair passagens relevantes para uma pergunta de seguimento.

5. Extrair conteúdo de uma URL

Usa Procurar quando já souberes qual a página que queres ler. Defina contentFormat para passage e forneça um espaço não em branco query para recuperar as partes da página mais relevantes para a sua questão.

liveCrawl: "fallback" pede ao Web IQ para rastrear a página quando ainda não está disponível no índice. O rastreamento ao vivo está sujeito a restrições de acesso impostas pelo editor e à disponibilidade; fallback não garante um rastreamento real.

Todos os exemplos pedem passagens focadas em consultas, o formato recomendado para fundamentação. A seleção query deve ser não em branco e não ultrapassar 1000 caracteres; maxLength controla separadamente a quantidade de conteúdo devolvido. Os formatos de documento completo (text, html, e markdown) requerem acesso total ao documento.

Endpoint: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 depois 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)

Instala o SDK com npm install @microsoft/webiq@1.2.1 (Node.js 22.18+ no 22.x, ou 24+). Guarde 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;
});

Num projeto Rust 1.88 ou posterior, execute cargo add webiq@1.2.1 e cargo add tokio --features macros,rt-multi-thread. Guarde 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(())
}

Num projeto Maven configurado para Java 11 ou posterior, adicione esta dependência a pom.xml:

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

Guarde 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());
        }
    }
}

Num projeto de consola .NET 8 ou posterior, execute dotnet add package Microsoft.WebIQ --version 1.2.1. Guarde 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))

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://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, title, conteúdo extraído content e um traceId. Um rastreamento em tempo real pode devolver 202 com retryAfter, um carimbo de data ISO 8601 UTC; espere até esse momento e depois envie novamente o mesmo pedido. Consulte a referência Browse API para o contrato de resposta completo.

6. Procurar locais (opcional)

Utilize a Pesquisa de Locais para obter informações estruturadas sobre negócios locais e outros locais. Os exemplos do SDK utilizam os pacotes 1.2.1 instalados no passo 2.

Endpoint: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)

Guarde 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;
});

Usa a configuração de Tokio do passo 2. Guarde 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(())
}

Guarde este exemplo como src/main/java/Places.java no projeto Maven do passo 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 consola .NET do passo 2, guarde 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))

Guarde 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));

Leia os resultados de placeResults. A lista e os campos individuais podem estar ausentes, por isso verifique se há valores em falta 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 Auto quando quiser que o Web IQ selecione fontes de recuperação e devolva evidência tipificada com citações de apoio. Faça uma pergunta completa em linguagem natural, mantendo restrições relevantes como datas, locais e unidades. Estes exemplos omitem mode para usar o predefinido e permitem 60 segundos por tentativa de pedido. Defina mode para advanced Auto Avançado quando precisar de uma recuperação mais completa para questões complexas.

A opção Automático devolve evidência para a sua aplicação utilizar, não uma resposta final gerada. Leia cada resultado de evidência com as suas próprias citações; não trate as citações de um resultado como suporte para outro. Os exemplos de SDK usam a versão 1.2.1 de todos os cinco SDKs, instalada no passo 2.

Endpoint: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)

Guarde 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;
});

Usa a configuração de Tokio do passo 2. Guarde 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(())
}

Guarde este exemplo como src/main/java/Auto.java no projeto Maven do passo 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 consola .NET do passo 2, guarde 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))

Guarde 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 o respetivo citations de suporte. Um results array vazio ou ausente não tem qualquer evidência a processar. Consulte a referência Auto API para tipos de evidência, exemplos de resposta e limites de pedidos.

8. Pesquisar produtos com Commerce (opcional)

Utilize as APIs de Comércio para encontrar produtos e ofertas de vendedor para uma consulta de compras: A Pesquisa devolve produtos classificados com as suas ofertas principais do vendedor, Ofertas devolve mais ofertas para um produto, e Detalhes do Produto devolve o título, descrição e classificação do produto.

Note

As APIs de Comércio estão em pré-visualização privada e estão incluídas com AppIDs que têm acesso completo aos documentos. O acesso está ativado separadamente para cada endpoint. Se o seu AppID não os tiver, abra um pedido de Suporte Web IQ (tipo de problema Autenticação e Acesso) indicando o 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

Este passo mostra as chamadas REST. Escolha cURL, Python (REST) ou JavaScript (REST) no topo da página para os ver.

Pesquisar 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 o seu id, o seu skuId, e o id da sua primeira oferta. Substitua PRODUCT_ID, SKU_ID, e OFFER_ID abaixo, depois procure mais ofertas e os detalhes do produto. Alguns produtos devolvem apenas uma oferta, sem id ou skuId: envie apenas offerId as Ofertas e ignore Detalhes do Produto, que requer um ID de produto ou 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))

Guarde 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 devolve produtos por ordem de classificação com as suas ofertas de vendedor principal; maxResults limita produtos, não ofertas. Ofertas devolve primeiro a oferta principal, seguida de quaisquer ofertas adicionais. Um pedido válido sem correspondência retorna 200 OK com um array products ou offers vazio. Os preços são inteiros nas unidades menores da moeda: 39999 USD é $399.99.

Para enviar um utilizador, ou um agente que atua em nome do utilizador, para uma oferta, utilize a oferta clickUrl exatamente como devolvida nessa resposta. Não use displayUrl, que apenas identifica o comerciante, e não reescreva, encurta ou reutilize o link. Construa links em código de aplicação em vez de deixar um modelo reproduzi-los. Consulte Ligações de ofertas e atribuição e o guia de Comércio.

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 Espere até à hora em retryAfter (um carimbo temporal UTC ISO 8601) e depois envie novamente o mesmo pedido.
Auto 403 Forbidden Verifique se Auto está listado em Serviços Permitidos na Gestão de Perfis. Se não estiver, abra um pedido de Suporte Web IQ com o seu AppID.

Para outras falhas, guarde o traceId e veja Gestão de Erros. Para contactar o Suporte Web IQ, inclua o traceId e o seu AppID, ou o nome da sua empresa e o nome do seu recurso Web IQ, caso não tenha o AppID.

Passos seguintes