SDKs

Os SDKs do Microsoft Web IQ fornecem clientes tipados para pesquisa Auto, web, notícias, vídeo, imagem e pesquisa de locais, além de Browse. Escolha um idioma na parte superior desta página para alternar todos os comandos e exemplos de instalação juntos.

Esses exemplos usam as versões públicas do SDK 1.2.1 para pesquisa automática com evidências tipadas e citações com escopo de resultado. Atualize as versões anteriores do SDK antes de executá-las.

Property Python TypeScript Rust Java .NET
Package webiq @microsoft/webiq webiq com.microsoft.webiq:webiq Microsoft.WebIQ
Versão usada 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

Você precisa de uma chave de API de IQ da Web ou uma identidade de Microsoft Entra com acesso ao IQ da Web. 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 a ser compilado para Java 11 ou posterior.

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

Para Gradle:

implementation "com.microsoft.webiq:webiq:1.2.1"

Esses exemplos usam o pacote público Microsoft.WebIQ 1.2.1 e exigem .NET 8 ou posterior. Execute este comando em um projeto de console .NET:

dotnet add package Microsoft.WebIQ --version 1.2.1

Início Rápido

Defina a variável de WEBIQ_API_KEY ambiente para sua chave de API antes de executar o exemplo. Não coloque chaves de API no código-fonte.

O exemplo chama Auto no advanced modo com um tempo limite de 60 segundos por tentativa, imprime cada resultado de evidência com suas citações de suporte, chama Web, Notícias, Vídeo, Imagem e Places Search e recupera uma página com Browse. Auto retorna evidências, não uma resposta final gerada. Consulte a referência do Auto para tipos de evidência e opções de solicitação.

As passagens de solicitação de Web, News e Browse são o formato recomendado para grounding. Procurar também requer uma seleção não vazia query de até 1000 caracteres. Para formatos de documentos completos, 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(())
}

Salve este exemplo como src/main/java/WebIqSample.java em seu projeto maven e execute 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 de API, passe uma credencial do Azure Identity. Para desenvolvimento local, faça login com uma ferramenta de desenvolvedor com suporte, como o CLI do Azure. Para aplicativos hospedados Azure, use identidade gerenciada ou identidade de carga de trabalho. Sua identidade deve ter acesso ao Web IQ.

O escopo OAuth padrão é https://api.microsoft.ai/.default.

Instale a dependência de autenticação opcional:

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 à identidade do Azure está incluído no SDK. O SDK reexporta azure_identity, portanto, nenhuma dependência extra é necessária. Este exemplo usa uma credencial de desenvolvedor 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 aplicativos hospedados, escolha ManagedIdentityCredential ou WorkloadIdentityCredential de webiq::azure_identity.

Adicione com.azure:azure-identity às dependências do Maven ou do Gradle usando uma versão compatível com as dependências SDK do Azure do 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

Consulte a referência REST para descrições de parâmetro, valores com suporte, campos de resposta e limites de serviço.

Resource Método 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 por vídeo
Images client.images.search(query, ...) Pesquisa por imagem
Places client.places.search(query, ...) Locais
Navegar client.browse.fetch(url, ...) Navegar

As opções de solicitação usam snake_case; as propriedades de resposta usam camelCase. Use enumerações do SDK para valores com suporte. 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 snippets restantes pressupõem um client aberto, a menos que construam um explicitamente.

Resource Método 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 por vídeo
Images client.images.search(query, options) Pesquisa por imagem
Places client.places.search(query, options) Locais
Navegar client.browse.fetch(url, options) Navegar

As opções de solicitação e as propriedades de resposta usam camelCase, como maxResults, contentFormat, liveCrawl, e aspectRatio. Passe opções como o segundo argumento. Use enumerações do SDK para valores com suporte, conforme mostrado no quickstart.

Os snippets restantes pressupõem um client aberto e execução dentro de uma função assíncrona, a menos que construam um cliente explicitamente. O await de nível superior await requer um módulo ES.

Resource Método 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 por vídeo
Images client.images().search(query, options) Pesquisa por imagem
Places client.places().search(query, options) Locais
Navegar client.browse().fetch(url, options) Navegar

Crie opções com AutoSearchOptions, WebSearchOptions, NewsSearchOptions, VideoSearchOptions, ImageSearchOptions, PlacesSearchOptions ou BrowseOptions. Os campos de resposta usam snake_case e valores opcionais usam Option.

Os snippets restantes são executados dentro de uma função assíncrona retornando Result, com um client aberto, a menos que construam um explicitamente. Use a configuração de runtime do Tokio do guia de início rápido.

Resource Método 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 por vídeo
Images client.images.search(query, ImagesSearchOptions) Pesquisa por imagem
Places client.places.search(query, PlacesSearchOptions) Locais
Navegar client.browse.fetch(url, BrowseFetchOptions) Navegar

Criar opções de solicitação com métodos de construtor camelCase, como maxResults, contentFormate maxLength. Ler propriedades de resposta por meio 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 na parte superior do arquivo 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 por vídeo
Images client.Images.SearchAsync(query, configure) Pesquisa por imagem
Places client.Places.SearchAsync(query, configure) Locais
Navegar client.Browse.FetchAsync(url, configure) Navegar

As propriedades de solicitação e resposta usam PascalCase. Defina as opções de solicitação no retorno de chamada de configuração ou passe um modelo de solicitação diretamente. Métodos Search e Fetch síncronos também estão disponíveis.

Os snippets restantes pressupõem um client aberto, a menos que construam um 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 por meio de seus clientes síncronos e assíncronos; .NET fornece Search eSearchAsync; TypeScript e Rust usam chamadas assíncronas.

Escreva uma pergunta completa de linguagem natural e preserve as restrições que importam para seu aplicativo. Leia o evidence de cada resultado junto com o citations desse resultado; as citações dão suporte apenas ao resultado ao qual pertencem. Para parâmetros, tipos de evidência e limites de serviço, consulte a Auto API reference.

Suporte assíncrono

Emita solicitações independentes simultaneamente quando seu aplicativo precisa de vários tipos de resultados.

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

Use WebIQAsyncClient; 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 de espera e tentativas de repetição

Defina um tempo limite no nível do cliente e substitua-o por requisição quando necessário. Os tempos limite se aplicam por tentativa, não ao tempo total gasto repetindo tentativas.

Por padrão, os SDKs tentam novamente falhas transitórias de rede e HTTP408, 500, 502520e 524523até duas vezes, com backoff exponencial e jitter. Um valor válido retryAfter no corpo da resposta tem precedência sobre o backoff gerado. HTTP 429 e 430 nunca são repetidos automaticamente: inspecione as diretrizes de repetição do erro e aplique seu próprio backoff. Os timeouts do lado do cliente não passam por nova tentativa.

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 tempos limite são em segundos. O 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 tempos limite estão em milissegundos. O padrão 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 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 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

Use um cliente HTTP personalizado para configuração de proxy, TLS ou pool de conexões. Não desabilite a verificação de certificado.

Passe http_client e feche o cliente HTTP de propriedade do chamador por conta própria. Use httpx.AsyncClient com WebIQAsyncClient para solicitações assíncronas.

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 a proxy:

npm install undici

Passe um fetchFn personalizado. Preserve init para que os cabeçalhos, o corpo e o 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 seu aplicativo construir 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 por meio de WebIQClientOptions.builder().httpClient(...). O SDK não fecha clientes de propriedade do chamador; gerencie seu tempo de vida em seu aplicativo.

Passe um HttpClient por meio de WebIQClientOptions.HttpClient. O SDK não descarta um cliente HTTP de propriedade do chamador; gerencie seu tempo de vida em seu aplicativo.

Cancelamento

Para solicitações assíncronas, use asyncio para cancelamento de tarefas ou asyncio.timeout para impor um limite de tempo total que inclua esperas de repetição. Um tempo limite do SDK por solicitação limita cada tentativa HTTP.

Cada método de recurso aceita um AbortSignal até options.signal. Abortar cancela a solicitação em andamento e as esperas entre tentativas; o motivo do sinal é relançado inalterado.

const response = await client.web.search('Microsoft Web IQ', {
  signal: AbortSignal.timeout(5_000),
});

Para combinar o sinal de uma solicitação de entrada com um limite de relógio de parede, use AbortSignal.any([request.signal, AbortSignal.timeout(5_000)]).

Cancele ou descarte o future da solicitação para interromper a operação, incluindo esperas de repetição. Para um prazo limite da aplicação, use os utilitários de tempo do Tokio e habilite o recurso 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 solicitação. Cancelar o CompletableFuture retornado não garante o cancelamento da solicitação HTTP subjacente ou das esperas de repetição.

Passe um CancellationToken para cancelar a operação, incluindo esperas de repetição:

using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var response = await client.Web.SearchAsync("Microsoft Web IQ",
    cancellationToken: cancellation.Token);

Telemetry

Anexe um retorno de chamada de telemetria para registrar cada tentativa de solicitação, status e tempo decorrido. A telemetria também inclui IDs de solicitação e rastreamento, orientações sobre novas tentativas e informações de erro. Evite registrar credenciais em log ou conteúdo de consulta confidencial.

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")

Os campos de telemetria usam snake_case, incluindo attempt, , status_code, request_id, trace_id, , retry_after, elapsed_ms, , errore 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();
}

Os campos de telemetria usam camelCase, incluindo attempt, , statusCode, requestId, traceId, , retryAfter, elapsedMs, e errorerrorBody.

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

Manipular erros de autenticação, permissão e limite de taxa separadamente de falhas transitórias. HTTP 429 e 430 aparecem imediatamente, sem novas tentativas do SDK. Use as diretrizes de nova tentativa retornadas para decidir quando tentar novamente.

Todas as exceções do SDK herdam de WebIQError. Erros HTTP herdam de APIStatusError, incluindo AuthenticationError, PermissionDeniedErrore RateLimitError. Falhas de rede e tempos limite geram APIConnectionError. A validação de solicitação do Python pode gerar pydantic.ValidationError antes de enviar uma solicitação.

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}")

Inspecione APIStatusError.body para ver a resposta de erro completa do servidor, incluindo errorCategory, errorCode, technicalDetails, retryAfter e traceId.

Todos os erros do SDK herdam de WebIQError. Erros HTTP herdam de APIStatusError, incluindo AuthenticationError, PermissionDeniedErrore RateLimitError. Falhas de rede e tempos limite geram 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;
  }
}

Inspecione APIStatusError.body para ver a resposta de erro completa do servidor, incluindo errorCategory, errorCode, technicalDetails, retryAfter e traceId.

Chamadas retornam Result<T, WebIqError>. Faça correspondência com erros da API ou inspecione os acessadores de erro para diagnóstico estruturado:

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(). Os campos opcionais ausentes retornam None.

Todas as exceções do SDK herdam de WebIQException. Exceções de status HTTP herdam de APIStatusException. Falhas de rede e tempos limite geram 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 status expõem getStatusCode(), getErrorCategory(), getErrorCode(), getUserMessage(), getTechnicalDetails(), getRetryAfter(), getRequestId(), getTraceId() e getBody(). Os campos opcionais ausentes retornam null.

Exceções de status HTTP herdam de ApiStatusException. Falhas de rede e tempos limite geram 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 status expõem ErrorCategory, ErrorCode, UserMessage, TechnicalDetails, RetryAfter, RequestId, TraceId e Body. Os campos opcionais ausentes são null.

Browse pode retornar HTTP 202 Accepted quando um rastreamento está pendente. Essa é uma resposta normal, não uma exceção, e o SDK não faz polling automaticamente. Use a URL de resposta e o carimbo de data/hora UTC retryAfter para tentar novamente mais tarde. As respostas HTTP 200 parciais podem incluir um truncationReason, como "encumbrance".

Depuração e próximas etapas

  • Inclua traceId ao entrar em contato com o suporte. O Rust usa trace_id, Java usa getTraceId()e .NET usa TraceId.
  • Use a telemetria para correlacionar tentativas, códigos de resposta e tempo decorrido.
  • Inspecione o corpo do erro estruturado antes de tratar um erro como passível de repetição. Veja Tratamento de erros.
  • Adicione a instrumentação de clique e citação ao exibir ou citar os resultados da pesquisa.