Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Os SDKs do Microsoft Web IQ disponibilizam clientes tipados para pesquisa Auto, web, notícias, vídeo, imagem e Locais, além de Browse. Escolha uma linguagem no topo desta página para alternar todos os comandos e exemplos de instalação em conjunto.
Estes exemplos utilizam as versões públicas do SDK 1.2.1 para pesquisa automática com evidências tipadas e citações delimitadas ao resultado. Atualize versões anteriores do SDK antes de as executar.
| Property | Python | TypeScript | Rust | Java | .NET |
|---|---|---|---|---|---|
| Package | webiq |
@microsoft/webiq |
webiq |
com.microsoft.webiq:webiq |
Microsoft.WebIQ |
| Versão utilizada | 1.2.1 | 1.2.1 | 1.2.1 | 1.2.1 | 1.2.1 |
| Runtime | Python 3.11+ | Node.js 22.13+ (22.x) ou 24+ | Rust 1.88+ | Java 11+ | .NET 8+ |
| License | MIT | MIT | MIT | MIT | MIT |
Precisa de uma chave API Web IQ ou de uma identidade Microsoft Entra com acesso ao Web IQ. Consulte Autenticação.
Installation
python -m pip install webiq==1.2.1
npm install @microsoft/webiq@1.2.1
Adicione o SDK e o runtime do Tokio ao seu projeto:
cargo add webiq@1.2.1
cargo add tokio --features macros,rt-multi-thread
Adicione a dependência do Maven Central ao pom.xml do seu projeto. Configure o projeto para compilar para Java 11 ou versões posteriores.
<dependency>
<groupId>com.microsoft.webiq</groupId>
<artifactId>webiq</artifactId>
<version>1.2.1</version>
</dependency>
Para o Gradle:
implementation "com.microsoft.webiq:webiq:1.2.1"
Estes exemplos utilizam o pacote público Microsoft.WebIQ 1.2.1 e requerem .NET 8 ou posterior. Execute este comando num projeto de consola .NET:
dotnet add package Microsoft.WebIQ --version 1.2.1
Início Rápido
Defina a variável de ambiente WEBIQ_API_KEY para o valor da sua chave API antes de executar o exemplo. Não coloques chaves API no código-fonte.
O exemplo chama Auto em modo advanced com um timeout de 60 segundos por tentativa, imprime cada resultado de evidência com as suas citações de apoio, depois chama Web, News, Video, Image e Places Search e recupera uma página com Browse. Auto devolve provas, não uma resposta final gerada. Consulte a referência Auto para tipos de evidência e opções de pedido.
Web, Notícias e Browse pedem passagens de pedido, o formato recomendado para fundamentação. O Browse também requer uma seleção query não em branco de até 1000 caracteres. Para formatos de documento completo, consulte Formatos de conteúdo.
import os
from webiq import WebIQClient
from webiq.types import BrowseContentFormat, ContentFormat, AutoMode
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
evidence = client.auto.search(
"What are the latest developments in retrieval-augmented generation?",
mode=AutoMode.advanced,
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)
web = client.web.search(
"Microsoft Web IQ",
max_results=5,
content_format=ContentFormat.passage,
)
for result in web.webResults or []:
print(result.title, result.url)
news = client.news.search(
"technology",
max_results=5,
content_format=ContentFormat.passage,
)
for item in news.newsResults or []:
print(item.title, item.source)
videos = client.videos.search("machine learning tutorial", max_results=5)
for video in videos.videoResults or []:
print(video.title, video.length)
images = client.images.search("golden gate bridge", max_results=5)
for image in images.imageResults or []:
print(image.title, image.url)
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)
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)
import { WebIQClient, BrowseContentFormat, ContentFormat, LiveCrawlMode, AutoMode } from '@microsoft/webiq';
async function main() {
const apiKey = process.env.WEBIQ_API_KEY;
if (!apiKey) throw new Error('Set WEBIQ_API_KEY before running this example.');
const client = new WebIQClient({ apiKey });
try {
const evidence = await client.auto.search(
'What are the latest developments in retrieval-augmented generation?',
{ mode: AutoMode.ADVANCED, 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);
}
const web = await client.web.search('Microsoft Web IQ', {
maxResults: 5,
contentFormat: ContentFormat.PASSAGE,
});
for (const result of web.webResults ?? []) console.log(result.title, result.url);
const news = await client.news.search('technology', {
maxResults: 5,
contentFormat: ContentFormat.PASSAGE,
});
for (const item of news.newsResults ?? []) console.log(item.title, item.source);
const videos = await client.videos.search('machine learning tutorial', { maxResults: 5 });
for (const video of videos.videoResults ?? []) console.log(video.title, video.length);
const images = await client.images.search('golden gate bridge', { maxResults: 5 });
for (const image of images.imageResults ?? []) console.log(image.title, image.url);
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);
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(page.content);
} finally {
await client.close();
}
}
main().catch(console.error);
use webiq::{
AutoSearchOptions, BrowseContentFormat, BrowseOptions, ContentFormat, ImageSearchOptions,
LiveCrawlMode, NewsSearchOptions, PlacesSearchOptions, VideoSearchOptions,
AutoMode, WebIqClient, WebSearchOptions,
};
#[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()
.mode(AutoMode::Advanced)
.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);
}
}
let web = client.web().search(
"Microsoft Web IQ",
WebSearchOptions::new()
.max_results(5)
.content_format(ContentFormat::Passage),
).await?;
for result in web.web_results.unwrap_or_default() {
println!("{:?} {:?}", result.title, result.url);
}
let news = client.news().search(
"technology",
NewsSearchOptions::new()
.max_results(5)
.content_format(ContentFormat::Passage),
).await?;
for item in news.news_results.unwrap_or_default() {
println!("{:?} {:?}", item.title, item.source);
}
let videos = client.videos().search(
"machine learning tutorial",
VideoSearchOptions::new().max_results(5),
).await?;
for video in videos.video_results.unwrap_or_default() {
println!("{:?} {:?}", video.title, video.length);
}
let images = client.images().search(
"golden gate bridge",
ImageSearchOptions::new().max_results(5),
).await?;
for image in images.image_results.unwrap_or_default() {
println!("{:?} {:?}", image.title, image.url);
}
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);
}
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(())
}
Guarda este exemplo como src/main/java/WebIqSample.java no teu projeto Maven e executa mvn compile exec:java -Dexec.mainClass=WebIqSample.
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.*;
import com.microsoft.webiq.resources.*;
public class WebIqSample {
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().mode(AutoMode.ADVANCED)
.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());
}
}
}
}
WebResponse web = client.web.search("Microsoft Web IQ",
WebSearchOptions.builder().maxResults(5)
.contentFormat(ContentFormat.PASSAGE).build());
if (web.getWebResults() != null) {
for (WebResult result : web.getWebResults()) {
System.out.println(result.getTitle() + " " + result.getUrl());
}
}
NewsResponse news = client.news.search("technology",
NewsSearchOptions.builder().maxResults(5)
.contentFormat(ContentFormat.PASSAGE).build());
if (news.getNewsResults() != null) {
for (NewsItem item : news.getNewsResults()) {
System.out.println(item.getTitle() + " " + item.getSource());
}
}
VideosResponse videos = client.videos.search("machine learning tutorial",
VideosSearchOptions.builder().maxResults(5).build());
if (videos.getVideoResults() != null) {
for (VideoItem video : videos.getVideoResults()) {
System.out.println(video.getTitle() + " " + video.getLength());
}
}
ImagesResponse images = client.images.search("golden gate bridge",
ImagesSearchOptions.builder().maxResults(5).build());
if (images.getImageResults() != null) {
for (ImageItem image : images.getImageResults()) {
System.out.println(image.getTitle() + " " + image.getUrl());
}
}
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());
}
}
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());
}
}
}
using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;
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.Mode = AutoMode.Advanced;
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}");
}
var web = await client.Web.SearchAsync("Microsoft Web IQ", request =>
{
request.MaxResults = 5;
request.ContentFormat = ContentFormat.Passage;
});
foreach (var result in web.WebResults ?? [])
Console.WriteLine($"{result.Title} {result.Url}");
var news = await client.News.SearchAsync("technology", request =>
{
request.MaxResults = 5;
request.ContentFormat = ContentFormat.Passage;
});
foreach (var item in news.NewsResults ?? [])
Console.WriteLine($"{item.Title} {item.Source}");
var videos = await client.Videos.SearchAsync("machine learning tutorial",
request => request.MaxResults = 5);
foreach (var video in videos.VideoResults ?? [])
Console.WriteLine($"{video.Title} {video.Length}");
var images = await client.Images.SearchAsync("golden gate bridge",
request => request.MaxResults = 5);
foreach (var image in images.ImageResults ?? [])
Console.WriteLine($"{image.Title} {image.Url}");
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}");
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);
Autenticação do Microsoft Entra ID
Em vez de uma chave API, passe uma credencial Azure Identity. Para desenvolvimento local, inicie sessão com uma ferramenta de desenvolvimento suportada, como a CLI do Azure. Para aplicações alojadas no Azure, use identidade gerida ou identidade de carga de trabalho. A sua identidade deve ter acesso ao Web IQ.
O âmbito padrão OAuth é https://api.microsoft.ai/.default.
Instale a dependência opcional de autenticação:
python -m pip install "webiq[entra]==1.2.1"
from azure.identity import DefaultAzureCredential
from webiq import WebIQClient
with DefaultAzureCredential() as credential:
with WebIQClient(credential=credential) as client:
response = client.web.search("Microsoft Web IQ")
print(response.webResults)
npm install "@azure/identity@>=4.13.1"
import { DefaultAzureCredential } from '@azure/identity';
import { WebIQClient } from '@microsoft/webiq';
const client = new WebIQClient({ credential: new DefaultAzureCredential() });
try {
const response = await client.web.search('Microsoft Web IQ');
console.log(response.webResults);
} finally {
await client.close();
}
O suporte ao Azure Identity está incluído no SDK. O SDK reexporta azure_identity, por isso não é necessária dependência adicional. Este exemplo utiliza uma credencial de programador após az login ou azd auth login:
use webiq::{azure_identity::DeveloperToolsCredential, WebIqClient};
let credential = DeveloperToolsCredential::new(None)?;
let client = WebIqClient::builder()
.credential(credential)
.build()?;
let response = client.web().search("Microsoft Web IQ", Default::default()).await?;
println!("{:?}", response.web_results);
Para aplicações alojadas, escolha ManagedIdentityCredential ou webiq::azure_identity de WorkloadIdentityCredential.
Adicione com.azure:azure-identity às suas dependências do Maven ou Gradle, usando uma versão compatível com as dependências do SDK do Azure do seu projeto.
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.WebIQClientOptions;
WebIQClientOptions options = WebIQClientOptions.builder()
.credential(new DefaultAzureCredentialBuilder().build())
.build();
try (WebIQClient client = new WebIQClient(options)) {
System.out.println(client.web.search("Microsoft Web IQ").getWebResults());
}
dotnet add package Azure.Identity
using Azure.Identity;
using Microsoft.WebIQ;
using var client = new WebIQClient(new WebIQClientOptions
{
Credential = new DefaultAzureCredential()
});
var response = await client.Web.SearchAsync("Microsoft Web IQ");
Console.WriteLine(response.WebResults?.Count);
Recursos e opções de solicitação
Use a referência REST para descrições de parâmetros, valores suportados, campos de resposta e limites de serviço.
| Resource | Method | Reference |
|---|---|---|
| Auto | client.auto.search(query, ...) |
Auto |
| Web | client.web.search(query, ...) |
Pesquisa na Web |
| Notícias | client.news.search(query, ...) |
Pesquisa de Notícias |
| Videos | client.videos.search(query, ...) |
Pesquisa de vídeos |
| Images | client.images.search(query, ...) |
Pesquisa de imagens |
| Locais | client.places.search(query, ...) |
Locais |
| Navegar | client.browse.fetch(url, ...) |
Navegar |
As opções de pedido usam snake_case; as propriedades de resposta usam camelCase. Usa enums do SDK para valores suportados. Por exemplo:
from webiq.types import ContentFormat, ImageAspectRatio, ImageSize, SafeSearch
web = client.web.search(
"search terms",
max_results=10,
language="en",
region="US",
location="lat:40.7;long:-74.0",
content_format=ContentFormat.passage,
max_length=3000,
)
news = client.news.search(
"search terms",
max_results=10,
content_format=ContentFormat.passage,
max_length=3000,
)
videos = client.videos.search(
"search terms", max_results=5, enable_playlist=True, freshness="month",
)
images = client.images.search(
"search terms",
max_results=5,
aspect_ratio=ImageAspectRatio.wide,
image_size=ImageSize.large,
safe_search=SafeSearch.strict,
watermark_free=True,
)
Os restantes fragmentos assumem um client aberto, a menos que o construam explicitamente.
| Resource | Method | Reference |
|---|---|---|
| Auto | client.auto.search(query, options) |
Auto |
| Web | client.web.search(query, options) |
Pesquisa na Web |
| Notícias | client.news.search(query, options) |
Pesquisa de Notícias |
| Videos | client.videos.search(query, options) |
Pesquisa de vídeos |
| Images | client.images.search(query, options) |
Pesquisa de imagens |
| Locais | client.places.search(query, options) |
Locais |
| Navegar | client.browse.fetch(url, options) |
Navegar |
As opções de pedido e as propriedades de resposta usam camelCase, como maxResults, contentFormat, liveCrawl, e aspectRatio. Passe opções como segundo argumento. Use enums do SDK para valores suportados, como mostrado no quickstart.
Os restantes snippets assumem client aberto e execução dentro de uma função assíncrona, a menos que construam explicitamente um cliente. Ao nível superior, await requer um módulo ES.
| Resource | Method | Reference |
|---|---|---|
| Auto | client.auto().search(query, options) |
Auto |
| Web | client.web().search(query, options) |
Pesquisa na Web |
| Notícias | client.news().search(query, options) |
Pesquisa de Notícias |
| Videos | client.videos().search(query, options) |
Pesquisa de vídeos |
| Images | client.images().search(query, options) |
Pesquisa de imagens |
| Locais | client.places().search(query, options) |
Locais |
| Navegar | client.browse().fetch(url, options) |
Navegar |
Opções de construção com AutoSearchOptions, WebSearchOptions, NewsSearchOptions, VideoSearchOptions, ImageSearchOptions, PlacesSearchOptions, , ou BrowseOptions. Os campos de resposta usam snake_case e os valores opcionais usam Option.
Os snippets restantes são executados dentro de uma função assíncrona que retorna Result, com um client aberto, a menos que construam um explicitamente. Usa a configuração de runtime do Tokio do quickstart.
| Resource | Method | Reference |
|---|---|---|
| Auto | client.auto.search(query, AutoSearchOptions) |
Auto |
| Web | client.web.search(query, WebSearchOptions) |
Pesquisa na Web |
| Notícias | client.news.search(query, NewsSearchOptions) |
Pesquisa de Notícias |
| Videos | client.videos.search(query, VideosSearchOptions) |
Pesquisa de vídeos |
| Images | client.images.search(query, ImagesSearchOptions) |
Pesquisa de imagens |
| Locais | client.places.search(query, PlacesSearchOptions) |
Locais |
| Navegar | client.browse.fetch(url, BrowseFetchOptions) |
Navegar |
Crie opções de pedido com métodos builder em camelCase como maxResults, contentFormat e maxLength. Leia propriedades de resposta através de getters como getWebResults() e getTraceId(). Campos de resposta opcionais podem ser null.
Os snippets restantes são executados dentro de um método, com um client aberto, a menos que construam um explicitamente. Coloque as importações no topo do seu ficheiro Java.
| Resource | Método assíncrono | Reference |
|---|---|---|
| Auto | client.Auto.SearchAsync(query, configure) |
Auto |
| Web | client.Web.SearchAsync(query, configure) |
Pesquisa na Web |
| Notícias | client.News.SearchAsync(query, configure) |
Pesquisa de Notícias |
| Videos | client.Videos.SearchAsync(query, configure) |
Pesquisa de vídeos |
| Images | client.Images.SearchAsync(query, configure) |
Pesquisa de imagens |
| Locais | client.Places.SearchAsync(query, configure) |
Locais |
| Navegar | client.Browse.FetchAsync(url, configure) |
Navegar |
As propriedades de pedido e resposta utilizam o PascalCase. Defina opções de solicitação no callback de configuração, ou passe diretamente um modelo de solicitação. Também estão disponíveis métodos síncronos Search e Fetch.
Os restantes fragmentos assumem um client aberto, a menos que o construam explicitamente.
Disponibilidade do Auto
O Auto está disponível em todos os cinco SDKs na versão 1.2.1. Python e Java expõem o Auto tanto através dos seus clientes síncronos como assíncronos; .NET fornece Search e SearchAsync; TypeScript e Rust usam chamadas assíncronas.
Escreva uma pergunta completa em linguagem natural e preserve as limitações que importam para a sua aplicação. Leia o evidence de cada resultado juntamente com o citations desse resultado; as citações suportam apenas o resultado em que estão incluídas. Para parâmetros, tipos de evidência e limites de serviço, consulte a referência da Auto API.
Suporte assíncrono
Emita pedidos independentes em simultâneo quando a sua aplicação precisar de vários tipos de resultados.
Uso WebIQAsyncClient com asyncio:
import asyncio
import os
from webiq import WebIQAsyncClient
async def main():
async with WebIQAsyncClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
web, news = await asyncio.gather(
client.web.search("Microsoft Web IQ"),
client.news.search("technology"),
)
print(web.webResults, news.newsResults)
asyncio.run(main())
const [web, news] = await Promise.all([
client.web.search('Microsoft Web IQ'),
client.news.search('technology'),
]);
console.log(web.webResults, news.newsResults);
let web_resource = client.web();
let news_resource = client.news();
let (web, news) = tokio::try_join!(
web_resource.search("Microsoft Web IQ", Default::default()),
news_resource.search("technology", Default::default()),
)?;
println!("{:?} {:?}", web.web_results, news.news_results);
Utilize WebIQAsyncClient; os seus métodos de recurso retornam CompletableFuture:
import com.microsoft.webiq.WebIQAsyncClient;
import com.microsoft.webiq.models.NewsResponse;
import com.microsoft.webiq.models.WebResponse;
import java.util.concurrent.CompletableFuture;
try (WebIQAsyncClient client = WebIQAsyncClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
CompletableFuture<WebResponse> web = client.web.search("Microsoft Web IQ");
CompletableFuture<NewsResponse> news = client.news.search("technology");
CompletableFuture.allOf(web, news).join();
System.out.println(web.join().getWebResults());
System.out.println(news.join().getNewsResults());
}
var webTask = client.Web.SearchAsync("Microsoft Web IQ");
var newsTask = client.News.SearchAsync("technology");
await Task.WhenAll(webTask, newsTask);
Console.WriteLine((await webTask).WebResults?.Count);
Console.WriteLine((await newsTask).NewsResults?.Count);
Configuration
Tempos limite e novas tentativas
Defina um timeout ao nível do cliente e depois substitua-o por pedido quando necessário. Os tempos de espera aplicam-se por tentativa, não ao tempo total gasto a tentar novamente.
Por defeito, os SDKs tentam novamente em caso de falhas de rede transitórias e HTTP 408, 500, 502, 520, 523 e 524 até duas vezes, com backoff exponencial e jitter. Um valor válido retryAfter no corpo de resposta tem prioridade sobre o backoff gerado. HTTP 429 e 430 nunca são retentados automaticamente: inspecione a orientação de retentativa do erro e aplique o seu próprio backoff. Os timeouts do lado do cliente não são repetidos.
import os
from webiq import WebIQClient, RetryPolicy
with WebIQClient(
api_key=os.environ["WEBIQ_API_KEY"],
timeout=10.0,
retry=RetryPolicy(max_retries=2, base_delay_s=0.25, max_delay_s=4.0),
) as client:
response = client.web.search("Microsoft Web IQ", timeout=30.0)
Os timeouts são em segundos. O valor padrão do cliente é de 10 segundos.
import { WebIQClient, RetryPolicy } from '@microsoft/webiq';
const client = new WebIQClient({
apiKey: process.env.WEBIQ_API_KEY,
timeout: 10_000,
retry: new RetryPolicy({
maxRetries: 2,
baseDelaySeconds: 0.25,
maxDelaySeconds: 4.0,
}),
});
try {
const response = await client.web.search('Microsoft Web IQ', { timeout: 30_000 });
console.log(response.webResults);
} finally {
await client.close();
}
Os timeouts são em milissegundos. O valor predefinido do cliente é 10.000 milissegundos.
use std::time::Duration;
use webiq::{RetryPolicy, WebIqClient, WebSearchOptions};
let client = WebIqClient::builder()
.api_key(std::env::var("WEBIQ_API_KEY")?)
.timeout(Duration::from_secs(10))
.retry(RetryPolicy::new().max_retries(2))
.build()?;
let response = client.web().search(
"Microsoft Web IQ",
WebSearchOptions::new().timeout(Duration::from_secs(30)),
).await?;
O valor padrão do cliente é de 10 segundos.
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.WebIQClientOptions;
import com.microsoft.webiq.resources.WebSearchOptions;
import com.microsoft.webiq.retry.RetryPolicy;
import java.time.Duration;
WebIQClientOptions options = WebIQClientOptions.builder()
.apiKey(System.getenv("WEBIQ_API_KEY"))
.timeout(Duration.ofSeconds(10))
.retry(RetryPolicy.builder().maxRetries(2).build())
.build();
try (WebIQClient client = new WebIQClient(options)) {
client.web.search("Microsoft Web IQ",
WebSearchOptions.builder().timeout(Duration.ofSeconds(30)).build());
}
O valor padrão do cliente é de 10 segundos.
using Microsoft.WebIQ;
using var client = new WebIQClient(new WebIQClientOptions
{
ApiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY"),
Timeout = TimeSpan.FromSeconds(30),
Retry = new RetryPolicy { MaxRetries = 2 }
});
var response = await client.Web.SearchAsync("Microsoft Web IQ",
timeout: TimeSpan.FromSeconds(10));
O padrão do cliente é de 30 segundos.
Clientes HTTP personalizados
Utilize um cliente HTTP personalizado para proxies, TLS ou configuração de pooling de conexões. Não desative a verificação de certificados.
Passe http_client e feche você mesmo o cliente HTTP do chamador. Usa httpx.AsyncClient com WebIQAsyncClient para pedidos assíncronos.
import os
import httpx
from webiq import WebIQClient
with httpx.Client(
base_url="https://api.microsoft.ai/v3",
proxy="http://proxy:8080",
) as http_client:
with WebIQClient(
api_key=os.environ["WEBIQ_API_KEY"],
http_client=http_client,
) as client:
response = client.web.search("Microsoft Web IQ")
Instale undici para suporte de proxy:
npm install undici
Passe um fetchFn personalizado. Conserve init para que os cabeçalhos, corpo e AbortSignal interno do SDK sejam encaminhados.
import { ProxyAgent } from 'undici';
import { WebIQClient } from '@microsoft/webiq';
const proxyAgent = new ProxyAgent('http://proxy:8080');
const client = new WebIQClient({
apiKey: process.env.WEBIQ_API_KEY,
fetchFn: (url, init) => {
const options = { ...init, dispatcher: proxyAgent };
return fetch(url, options);
},
});
try {
const response = await client.web.search('Microsoft Web IQ');
console.log(response.webResults);
} finally {
await client.close();
await proxyAgent.close();
}
Passe um reqwest::Client configurado para WebIqClient::builder().http_client(...). Se a sua aplicação instancia este cliente diretamente, adicione reqwest como uma dependência direta, com uma versão compatível com o SDK.
Passe um java.net.http.HttpClient configurado através de WebIQClientOptions.builder().httpClient(...). O SDK não fecha clientes do chamador; faça a gestão do seu ciclo de vida na sua aplicação.
Passe um HttpClient através de WebIQClientOptions.HttpClient. O SDK não liberta um cliente HTTP pertencente ao chamador; gira o respetivo ciclo de vida na sua aplicação.
Cancelamento
Para pedidos assíncronos, use asyncio o cancelamento de tarefas ou asyncio.timeout para impor um limite de tempo total que inclua esperas de retentativa. Um timeout do SDK por pedido limita cada tentativa HTTP.
Todos os métodos de recurso aceitam um AbortSignal através de options.signal. Abortar cancela o pedido em voo e a espera de retentar; a razão do sinal é relançada inalterada.
const response = await client.web.search('Microsoft Web IQ', {
signal: AbortSignal.timeout(5_000),
});
Para combinar o sinal de um pedido de entrada com um limite de relógio de parede, use AbortSignal.any([request.signal, AbortSignal.timeout(5_000)]).
Cancele ou descarte o future do pedido para interromper a operação, incluindo as esperas de repetição. Para um prazo da aplicação, use as utilidades de tempo do Tokio e ative a funcionalidade time do Tokio.
Use um timeout por chamada para limitar cada tentativa HTTP. O SDK 1.2.1 não expõe um token de cancelamento de pedido. Cancelar o CompletableFuture devolvido não garante o cancelamento do pedido HTTP subjacente ou as esperas de retentativa.
Passe a CancellationToken para cancelar a operação, incluindo as esperas de retentação:
using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var response = await client.Web.SearchAsync("Microsoft Web IQ",
cancellationToken: cancellation.Token);
Telemetry
Anexe uma função de callback de telemetria para registar cada tentativa de pedido, estado e tempo decorrido. A telemetria inclui também IDs de pedido e rastreamento, orientação para retentativas e informações sobre erros. Evite registar credenciais ou conteúdos de consulta sensíveis.
import os
from webiq import WebIQClient, TelemetryEvent
def on_request(event: TelemetryEvent):
print(f"{event.method} {event.path}: {event.status_code} ({event.elapsed_ms}ms)")
with WebIQClient(
api_key=os.environ["WEBIQ_API_KEY"],
telemetry_hook=on_request,
) as client:
response = client.web.search("Microsoft Web IQ")
Campos de telemetria usam snake_case, incluindo attempt, status_code, request_id, retry_aftertrace_id, elapsed_ms, , error, e error_body.
import { WebIQClient } from '@microsoft/webiq';
const client = new WebIQClient({
apiKey: process.env.WEBIQ_API_KEY,
telemetryHook: event => {
console.log(`${event.method} ${event.path}: ${event.statusCode} (${event.elapsedMs}ms)`);
},
});
try {
await client.web.search('Microsoft Web IQ');
} finally {
await client.close();
}
Campos de telemetria usam camelCase, incluindo attempt, statusCode, requestId, traceId, retryAfter, elapsedMs, , error, , e errorBody.
use std::sync::Arc;
use webiq::{TelemetryEvent, WebIqClient};
let client = WebIqClient::builder()
.api_key(std::env::var("WEBIQ_API_KEY")?)
.telemetry_hook(Arc::new(|event: &TelemetryEvent| {
println!("{} {}: {:?} ({:?}ms)",
event.method, event.path, event.status_code, event.elapsed_ms);
}))
.build()?;
client.web().search("Microsoft Web IQ", Default::default()).await?;
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.WebIQClientOptions;
WebIQClientOptions options = WebIQClientOptions.builder()
.apiKey(System.getenv("WEBIQ_API_KEY"))
.telemetryHook(event -> System.out.printf("%s %s: %s (%sms)%n",
event.getMethod(), event.getPath(),
event.getStatusCode(), event.getElapsedMs()))
.build();
try (WebIQClient client = new WebIQClient(options)) {
client.web.search("Microsoft Web IQ");
}
using Microsoft.WebIQ;
using var client = new WebIQClient(new WebIQClientOptions
{
ApiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY"),
TelemetryHook = telemetry => Console.WriteLine(
$"{telemetry.Method} {telemetry.Path}: " +
$"{telemetry.StatusCode} ({telemetry.ElapsedMilliseconds}ms)")
});
await client.Web.SearchAsync("Microsoft Web IQ");
Tratamento de erros
Trate de erros de autenticação, erros de permissão e limites de taxa separadamente das falhas transitórias. HTTP 429 e 430 surgem imediatamente, sem tentativas de repetição do SDK. Utilize as orientações de repetição devolvidas para decidir quando tentar novamente.
Todas as exceções SDK herdam de WebIQError. Os erros HTTP herdam de APIStatusError, incluindo AuthenticationError, PermissionDeniedError, e RateLimitError. Falhas de rede e timeouts originam APIConnectionError. A validação de pedidos em Python pode gerar pydantic.ValidationError antes de enviar um pedido.
from webiq import (
APIConnectionError, APIStatusError, AuthenticationError,
PermissionDeniedError, RateLimitError, WebIQError,
)
try:
response = client.web.search("Microsoft Web IQ")
except AuthenticationError as error:
print(f"Authentication failed: {error}")
except PermissionDeniedError as error:
print(f"Forbidden: {error}")
except RateLimitError as error:
print(f"Rate limited; retry after: {error.retry_after}")
except APIStatusError as error:
print(f"HTTP {error.status_code}: {error}")
if isinstance(error.body, dict):
print(error.body.get("errorCode"), error.body.get("traceId"))
except APIConnectionError as error:
print(f"Connection failed: {error}")
except WebIQError as error:
print(f"SDK error: {error}")
Inspecionar APIStatusError.body a resposta completa ao erro do servidor, incluindo errorCategory, errorCode, technicalDetails, retryAfter, e traceId.
Todos os erros do SDK herdam de WebIQError. Os erros HTTP herdam de APIStatusError, incluindo AuthenticationError, PermissionDeniedError, e RateLimitError. Falhas de rede e timeouts originam APIConnectionError.
import {
APIConnectionError, APIStatusError, AuthenticationError,
PermissionDeniedError, RateLimitError,
} from '@microsoft/webiq';
try {
await client.web.search('Microsoft Web IQ');
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Authentication failed:', error.message);
} else if (error instanceof PermissionDeniedError) {
console.error('Forbidden:', error.message);
} else if (error instanceof RateLimitError) {
console.error('Rate limited; retry after:', error.retryAfter);
} else if (error instanceof APIStatusError) {
console.error(`HTTP ${error.statusCode}:`, error.message);
if (error.body && typeof error.body === 'object') {
const body = error.body as Record<string, unknown>;
console.error(body.errorCode, body.traceId);
}
} else if (error instanceof APIConnectionError) {
console.error('Connection failed:', error.message);
} else {
throw error;
}
}
Inspecionar APIStatusError.body a resposta completa ao erro do servidor, incluindo errorCategory, errorCode, technicalDetails, retryAfter, e traceId.
Chamadas retornam Result<T, WebIqError>. Fazer correspondência com erros da API ou inspecionar os métodos de acesso ao erro para diagnósticos estruturados:
use webiq::WebIqError;
match client.web().search("Microsoft Web IQ", Default::default()).await {
Ok(response) => println!("{:?}", response.web_results),
Err(WebIqError::Authentication(details)) => eprintln!("401: {}", details.message),
Err(WebIqError::PermissionDenied(details)) => eprintln!("403: {}", details.message),
Err(WebIqError::RateLimit(details)) => {
eprintln!("Rate limited; retry after: {:?}", details.retry_after());
}
Err(error) => {
eprintln!("{error}");
eprintln!("Code: {:?}, trace: {:?}", error.error_code(), error.trace_id());
}
}
Erros de API expõem status_code(), error_category(), error_code(), user_message(), technical_details(), retry_after(), request_id(), , trace_id(), e body(). A ausência de campos opcionais retorna None.
Todas as exceções SDK herdam de WebIQException. As exceções de código de estado HTTP herdam de APIStatusException. Falhas de rede e timeouts originam APIConnectionException.
import com.microsoft.webiq.errors.*;
try {
client.web.search("Microsoft Web IQ");
} catch (AuthenticationException error) {
System.err.println("Authentication failed: " + error.getMessage());
} catch (PermissionDeniedException error) {
System.err.println("Forbidden: " + error.getMessage());
} catch (RateLimitException error) {
System.err.println("Rate limited; retry after: " + error.getRetryAfter());
} catch (APIStatusException error) {
System.err.println("HTTP " + error.getStatusCode() + ": " + error.getMessage());
System.err.println("Code: " + error.getErrorCode() + ", trace: " + error.getTraceId());
} catch (APIConnectionException error) {
System.err.println("Connection failed: " + error.getMessage());
}
Exceções de estado expõem getStatusCode(), getErrorCategory(), getErrorCode(), getUserMessage(), getTechnicalDetails(), getRetryAfter(), getRequestId(), getTraceId() e getBody(). A ausência de campos opcionais retorna null.
As exceções de código de estado HTTP herdam de ApiStatusException. Falhas de rede e timeouts originam ApiConnectionException.
using Microsoft.WebIQ;
try
{
await client.Web.SearchAsync("Microsoft Web IQ");
}
catch (AuthenticationException error)
{
Console.Error.WriteLine($"Authentication failed: {error.Message}");
}
catch (PermissionDeniedException error)
{
Console.Error.WriteLine($"Forbidden: {error.Message}");
}
catch (RateLimitException error)
{
Console.Error.WriteLine($"Rate limited; retry after: {error.RetryAfter}");
}
catch (ApiStatusException error)
{
Console.Error.WriteLine($"HTTP {error.StatusCode}: {error.Message}");
Console.Error.WriteLine($"Code: {error.ErrorCode}, trace: {error.TraceId}");
}
catch (ApiConnectionException error)
{
Console.Error.WriteLine($"Connection failed: {error.Message}");
}
Exceções de estado expõem ErrorCategory, ErrorCode, UserMessage, TechnicalDetails, RetryAfter, RequestId, TraceId, , e Body. Os campos opcionais em falta são null.
O Browse pode devolver HTTP 202 Accepted quando um rastreamento está pendente. Esta é uma resposta normal, não uma exceção, e o SDK não faz sondagens automáticas. Use a URL de resposta e o carimbo temporal UTC retryAfter para tentar novamente mais tarde. Respostas parciais HTTP 200 podem incluir um truncationReason, como "encumbrance".
Depuração e próximos passos
- Inclua
traceIdao contactar o suporte. Rust usatrace_id, Java usagetTraceId(), e .NET usaTraceId. - Utilize telemetria para correlacionar tentativas, códigos de resposta e tempo decorrido.
- Inspecione o corpo estruturado do erro antes de considerar um erro como passível de repetição. Ver Gestão de erros.
- Adicione instrumentação de clique e citação ao exibir ou citar resultados de pesquisa.