Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Die Microsoft Web IQ SDKs bieten typisierte Clients für Auto-, Web-, News-, Video-, Image- und Places-Suche sowie Browse. Wählen Sie oben auf dieser Seite eine Sprache aus, damit alle Installationsbefehle und Beispiele gleichzeitig umgeschaltet werden.
In diesen Beispielen werden die öffentlichen 1.2.1 SDK-Versionen für Auto search mit typisierten Nachweisen und ergebnisbezogenen Zitaten verwendet. Aktualisieren Sie frühere SDK-Versionen, bevor Sie sie verwenden.
| Property | Python | TypeScript | Rust | Java | .NET |
|---|---|---|---|---|---|
| Package | webiq |
@microsoft/webiq |
webiq |
com.microsoft.webiq:webiq |
Microsoft.WebIQ |
| Verwendete Version | 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) oder 24+ | Rust 1.88+ | Java 11+ | .NET 8+ |
| License | MIT | MIT | MIT | MIT | MIT |
Sie benötigen einen Web IQ-API-Schlüssel oder eine Microsoft Entra Identität mit Zugriff auf Web IQ. Siehe Authentifizierung.
Installation
python -m pip install webiq==1.2.1
npm install @microsoft/webiq@1.2.1
Fügen Sie das SDK und die Tokio-Laufzeit zu Ihrem Projekt hinzu:
cargo add webiq@1.2.1
cargo add tokio --features macros,rt-multi-thread
Fügen Sie die Maven Central-Abhängigkeit zur pom.xml Ihres Projekts hinzu. Konfigurieren Sie das Projekt so, dass es für Java 11 oder höher kompiliert wird.
<dependency>
<groupId>com.microsoft.webiq</groupId>
<artifactId>webiq</artifactId>
<version>1.2.1</version>
</dependency>
Für Gradle:
implementation "com.microsoft.webiq:webiq:1.2.1"
In diesen Beispielen wird das öffentliche Microsoft.WebIQ 1.2.1-Paket verwendet, und sie erfordern .NET 8 oder höher. Führen Sie diesen Befehl in einem .NET Konsolenprojekt aus:
dotnet add package Microsoft.WebIQ --version 1.2.1
Quickstart
Setzen Sie die Umgebungsvariable WEBIQ_API_KEY auf Ihren API-Schlüssel, bevor Sie das Beispiel ausführen. Fügen Sie KEINE API-Schlüssel in den Quellcode ein.
Im Beispiel wird "Auto" im advanced Modus mit einem Timeout von 60 Sekunden pro Versuch aufgerufen, jedes Beweisergebnis wird mit den zugehörigen Quellenangaben gedruckt, anschließend werden Web, Nachrichten, Video, Bild und Places Search aufgerufen und eine Seite mit "Durchsuchen" abgerufen. Auto gibt Belege zurück, keine generierte endgültige Antwort. Siehe die Auto reference für Nachweistypen und Anforderungsoptionen.
Anfragepassagen für Web, News und Browse, das empfohlene Format für Grounding. "Durchsuchen" erfordert auch eine nicht leere Auswahl query von bis zu 1000 Zeichen. Informationen zu Formaten für ganze Dokumente finden Sie unter Content formats.
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(())
}
Speichern Sie dieses Beispiel als src/main/java/WebIqSample.java in Ihrem Maven-Projekt, und führen Sie mvn compile exec:java -Dexec.mainClass=WebIqSample aus.
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);
Microsoft Entra ID-Authentifizierung
Übergeben Sie anstelle eines API-Schlüssels eine Azure-Identity-Anmeldeinformation. Melden Sie sich für die lokale Entwicklung mit einem unterstützten Entwicklertool an, z. B. dem Azure CLI. Verwenden Sie für Azure gehostete Anwendungen verwaltete Identität oder Workloadidentität. Ihre Identität muss Zugriff auf Web IQ haben.
Der Standard-OAuth-Scope ist https://api.microsoft.ai/.default.
Installieren Sie die optionale Authentifizierungsabhängigkeit:
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();
}
Azure Identitätsunterstützung ist im SDK enthalten. Das SDK exportiert azure_identity erneut, sodass keine zusätzliche Abhängigkeit erforderlich ist. In diesem Beispiel wird eine Entwickleranmeldeinformation nach azd auth login oder az login verwendet:
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);
Für gehostete Anwendungen wählen Sie ManagedIdentityCredential oder WorkloadIdentityCredential aus webiq::azure_identity.
Fügen Sie com.azure:azure-identity Ihren Maven- oder Gradle-Abhängigkeiten hinzu, und verwenden Sie eine Version, die mit den Azure SDK-Abhängigkeiten Ihres Projekts kompatibel ist.
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);
Ressourcen und Anforderungsoptionen
Verwenden Sie den REST-Verweis für Parameterbeschreibungen, unterstützte Werte, Antwortfelder und Dienstgrenzwerte.
| Resource | Methode | Reference |
|---|---|---|
| Auto | client.auto.search(query, ...) |
Auto |
| Web | client.web.search(query, ...) |
Websuche |
| Nachrichten | client.news.search(query, ...) |
Nachrichtensuche |
| Videos | client.videos.search(query, ...) |
Videosuche |
| Images | client.images.search(query, ...) |
Bildsuche |
| Orte | client.places.search(query, ...) |
Orte |
| Durchsuchen | client.browse.fetch(url, ...) |
Durchsuchen |
Anforderungsoptionen verwenden snake_case; Antworteigenschaften verwenden camelCase. Verwenden Sie SDK-Enumerationen für unterstützte Werte. Beispiele:
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,
)
Die restlichen Codeausschnitte gehen von einem offenen client aus, es sei denn, sie erstellen explizit eines.
| Resource | Methode | Reference |
|---|---|---|
| Auto | client.auto.search(query, options) |
Auto |
| Web | client.web.search(query, options) |
Websuche |
| Nachrichten | client.news.search(query, options) |
Nachrichtensuche |
| Videos | client.videos.search(query, options) |
Videosuche |
| Images | client.images.search(query, options) |
Bildsuche |
| Orte | client.places.search(query, options) |
Orte |
| Durchsuchen | client.browse.fetch(url, options) |
Durchsuchen |
Anforderungsoptionen und Antworteigenschaften verwenden camelCase, wie maxResults, contentFormat, liveCrawl und aspectRatio. Übergeben Sie Optionen als zweites Argument. Verwenden Sie SDK-Enumerationen für unterstützte Werte, wie in der Schnellstartanleitung gezeigt.
Die restlichen Codeausschnitte gehen von einem offenen client aus und werden innerhalb einer asynchronen Funktion ausgeführt, es sei denn, sie erstellen einen Client explizit. Für await auf oberster Ebene ist ein ES-Modul erforderlich.
| Resource | Methode | Reference |
|---|---|---|
| Auto | client.auto().search(query, options) |
Auto |
| Web | client.web().search(query, options) |
Websuche |
| Nachrichten | client.news().search(query, options) |
Nachrichtensuche |
| Videos | client.videos().search(query, options) |
Videosuche |
| Images | client.images().search(query, options) |
Bildsuche |
| Orte | client.places().search(query, options) |
Orte |
| Durchsuchen | client.browse().fetch(url, options) |
Durchsuchen |
Buildoptionen mit AutoSearchOptions, WebSearchOptions, VideoSearchOptions, NewsSearchOptions, ImageSearchOptions, BrowseOptions oder PlacesSearchOptions. Antwortfelder verwenden snake_case und optionale Werte verwenden Option.
Die verbleibenden Codeausschnitte werden in einer asynchronen Funktion ausgeführt, die Result zurückgibt, mit einem offenen client, sofern sie nicht explizit eines erstellen. Verwenden Sie das Tokio-Laufzeitsetup aus der Schnellstartanleitung.
| Resource | Methode | Reference |
|---|---|---|
| Auto | client.auto.search(query, AutoSearchOptions) |
Auto |
| Web | client.web.search(query, WebSearchOptions) |
Websuche |
| Nachrichten | client.news.search(query, NewsSearchOptions) |
Nachrichtensuche |
| Videos | client.videos.search(query, VideosSearchOptions) |
Videosuche |
| Images | client.images.search(query, ImagesSearchOptions) |
Bildsuche |
| Orte | client.places.search(query, PlacesSearchOptions) |
Orte |
| Durchsuchen | client.browse.fetch(url, BrowseFetchOptions) |
Durchsuchen |
Erstellen Sie Anforderungsoptionen mit camelCase-Builder-Methoden wie maxResults, contentFormat und maxLength. Lesen Sie Antworteigenschaften über Getter wie getWebResults() und getTraceId(). Optionale Antwortfelder können null sein.
Die restlichen Codeausschnitte werden innerhalb einer Methode mit einem offenen client ausgeführt, es sei denn, sie erstellen eines explizit. Platzieren Sie Importe am Anfang der Java Datei.
| Resource | Asynchrone Methode | Reference |
|---|---|---|
| Auto | client.Auto.SearchAsync(query, configure) |
Auto |
| Web | client.Web.SearchAsync(query, configure) |
Websuche |
| Nachrichten | client.News.SearchAsync(query, configure) |
Nachrichtensuche |
| Videos | client.Videos.SearchAsync(query, configure) |
Videosuche |
| Images | client.Images.SearchAsync(query, configure) |
Bildsuche |
| Orte | client.Places.SearchAsync(query, configure) |
Orte |
| Durchsuchen | client.Browse.FetchAsync(url, configure) |
Durchsuchen |
Eigenschaften für Anforderungen und Antworten verwenden PascalCase. Legen Sie Anforderungsoptionen im Konfigurationsrückruf fest, oder übergeben Sie ein Anforderungsmodell direkt. Synchrone Search Und Fetch Methoden sind ebenfalls verfügbar.
Die restlichen Codeausschnitte gehen von einem offenen client aus, es sei denn, sie erstellen explizit eines.
Auto-Verfügbarkeit
Auto ist in allen fünf SDKs ab Version 1.2.1 verfügbar. Python und Java stellen Auto sowohl über ihre synchronen als auch über ihre asynchronen Clients bereit; .NET bietet Search und SearchAsync; TypeScript und Rust verwenden asynchrone Aufrufe.
Schreiben Sie eine vollständige Frage in natürlicher Sprache, und behalten Sie die Einschränkungen bei, die für Ihre Anwendung wichtig sind. Lesen Sie zu jedem Ergebnis evidence zusammen mit dem zugehörigen citations; Zitate unterstützen nur das jeweilige Ergebnis, in dem sie enthalten sind. Parameter, Nachweistypen und Dienstgrenzwerte finden Sie in der Auto-API-Referenz.
Asynchrone Unterstützung
Stellen Sie unabhängige Anfragen gleichzeitig aus, wenn Ihre Anwendung mehrere Ergebnistypen benötigt.
Verwenden Sie WebIQAsyncClient mit 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);
Verwenden Sie WebIQAsyncClient; seine Ressourcenmethoden geben CompletableFuture zurück:
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
Timeouts und Wiederholungsversuche
Legen Sie ein Timeout auf Clientebene fest, und überschreiben Sie es bei Bedarf pro Anforderung. Timeouts gelten pro Versuch und nicht für die Gesamtzeit, die für Wiederholungen aufgewendet wurde.
Standardmäßig versuchen die SDKs bei vorübergehenden Netzwerkfehlern und HTTP-408, 500, 502, 520, 523 und 524 bis zu zweimal erneut, mit exponentiellem Backoff und Jitter. Ein gültiger retryAfter Wert im Antworttext hat Vorrang vor generiertem Backoff. HTTP 429 und 430 werden nie automatisch erneut versucht: Überprüfen Sie die Wiederholungsanleitungen des Fehlers, und wenden Sie Ihren eigenen Backoff an. Clientseitige Timeouts werden nicht erneut versucht.
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)
Timeouts sind in Sekunden. Der Standardwert für den Client beträgt 10 Sekunden.
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();
}
Timeouts sind in Millisekunden angegeben. Der Standardwert des Clients beträgt 10.000 Millisekunden.
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?;
Der Standardwert für den Client beträgt 10 Sekunden.
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());
}
Der Standardwert für den Client beträgt 10 Sekunden.
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));
Der Clientstandard ist 30 Sekunden.
Benutzerdefinierte HTTP-Clients
Verwenden Sie einen benutzerdefinierten HTTP-Client für proxy-, TLS- oder Verbindungspoolkonfigurationen. Deaktivieren Sie die Zertifikatüberprüfung nicht.
Übergeben Sie http_client und schließen Sie den im Besitz des Aufrufers befindlichen HTTP-Client selbst. Verwenden Sie WebIQAsyncClient mit httpx.AsyncClient für asynchrone Anfragen.
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")
Installieren Sie undici für Proxyunterstützung:
npm install undici
Übergeben Sie eine benutzerdefinierte fetchFn. Bewahren Sie init auf, damit die Kopfzeilen, der Textkörper und das interne AbortSignal des SDK weitergeleitet werden.
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();
}
Übergeben Sie eine konfigurierte reqwest::Client An WebIqClient::builder().http_client(...). Wenn Ihre Anwendung diesen Client direkt erstellt, fügen Sie reqwest als direkte Abhängigkeit mit einer Version hinzu, die mit dem SDK kompatibel ist.
Übergeben Sie eine konfigurierte java.net.http.HttpClient über WebIQClientOptions.builder().httpClient(...). Das SDK schließt keine anrufereigenen Clients; verwalten Sie ihre Lebensdauer in Ihrer Anwendung.
Übergeben Sie ein HttpClient über WebIQClientOptions.HttpClient. Das SDK entsorgt keinen aufrufereigenen HTTP-Client; verwalten Sie dessen Lebensdauer in Ihrer Anwendung.
Stornierung
Für asynchrone Anforderungen verwenden Sie asyncio für den Vorgangsabbruch oder asyncio.timeout, um ein Zeitbudget festzulegen, das Wartezeiten bei Wiederholungen einschließt. Ein SDK-Timeout pro Anforderung begrenzt jeden HTTP-Versuch.
Jede Ressourcenmethode akzeptiert eine von AbortSignal bis options.signal. Beim Abbrechen der In-Flight-Anforderung wird die In-Flight-Anforderung abgebrochen, und die Wartezeiten zwischen Wiederholungsversuchen werden abgebrochen; der Grund des Signals wird unverändert erneut ausgelöst.
const response = await client.web.search('Microsoft Web IQ', {
signal: AbortSignal.timeout(5_000),
});
Verwenden Sie AbortSignal.any([request.signal, AbortSignal.timeout(5_000)]), um das Signal einer eingehenden Anforderung mit einem Wall-Clock-Limit zu kombinieren.
Brechen Sie das Request-Future ab oder verwerfen Sie es, um den Vorgang einschließlich Wiederholungswartezeiten zu unterbrechen. Verwenden Sie für eine Anwendungs-Deadline die Zeitfunktionen von Tokio, und aktivieren Sie das time Feature von Tokio.
Verwenden Sie pro Aufruf timeout, um jeden HTTP-Versuch zu begrenzen. SDK 1.2.1 stellt kein Token zum Abbrechen von Anfragen bereit. Durch das Abbrechen des zurückgegebenen CompletableFuture Vorgangs wird nicht garantiert, dass die zugrunde liegende HTTP-Anforderung oder Wartezeiten zwischen Wiederholungsversuchen abgebrochen werden.
Übergeben Sie ein CancellationToken, um den Vorgang abzubrechen, einschließlich der Wartezeiten zwischen Wiederholungen:
using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var response = await client.Web.SearchAsync("Microsoft Web IQ",
cancellationToken: cancellation.Token);
Telemetry
Fügen Sie einen Telemetrierückruf an, um jeden Anforderungsversuch, status und verstrichene Zeit zu protokollieren. Telemetrie umfasst auch Anforderungs- und Ablaufverfolgungs-IDs, Wiederholungsanleitungen und Fehlerinformationen. Vermeiden Sie die Protokollierung von Anmeldeinformationen oder vertraulichen Abfrageinhalten.
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")
Telemetriefelder verwenden snake_case, einschließlich attempt, request_id, trace_id, retry_after, elapsed_ms, error, error_body und status_code.
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();
}
Telemetriefelder verwenden camelCase, einschließlich attempt, statusCode, requestId, traceId, retryAfter, elapsedMs, errorBody und error.
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");
Fehlerbehandlung
Behandeln Sie Authentifizierungs-, Berechtigungs- und Rate-Limit-Fehler getrennt von vorübergehenden Fehlern. HTTP 429 und 430 treten sofort auf, ohne SDK-Wiederholungen. Verwenden Sie die zurückgegebenen Hinweise für Wiederholungsversuche, um zu entscheiden, wann Sie es erneut versuchen möchten.
Alle SDK-Ausnahmen erben von WebIQError. HTTP-Fehler erben von APIStatusError, einschließlich AuthenticationError, PermissionDeniedError, und RateLimitError. Netzwerkfehler und Timeouts lösen APIConnectionError aus. Die Python-Anforderungsüberprüfung kann vor dem Senden einer Anforderung pydantic.ValidationError auslösen.
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}")
Überprüfen Sie APIStatusError.body auf die vollständige Serverfehlerantwort, einschließlich errorCategory, errorCode, technicalDetails, retryAfter und traceId.
Alle SDK-Fehler erben von WebIQError. HTTP-Fehler erben von APIStatusError, einschließlich AuthenticationError, PermissionDeniedError, und RateLimitError. Netzwerkfehler und Timeouts lösen APIConnectionError aus.
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;
}
}
Überprüfen Sie APIStatusError.body auf die vollständige Serverfehlerantwort, einschließlich errorCategory, errorCode, technicalDetails, retryAfter und traceId.
Aufrufe geben Result<T, WebIqError> zurück. Gleichen Sie API-Fehler ab oder überprüfen Sie die Fehleraccessoren für strukturierte Diagnosen:
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());
}
}
API-Fehler stellen status_code(), error_category(), error_code(), user_message(), technical_details(), retry_after(), request_id(), trace_id() und body() bereit. Bei fehlenden optionalen Feldern wird None zurückgegeben.
Alle SDK-Ausnahmen erben von WebIQException. HTTP-Status-Ausnahmen erben von APIStatusException. Netzwerkfehler und Timeouts lösen APIConnectionException aus.
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());
}
Statusausnahmen machen getStatusCode(), getErrorCategory(), getErrorCode(), getTechnicalDetails(), getUserMessage(), getRetryAfter(), getRequestId(), getTraceId() und getBody() verfügbar. Bei fehlenden optionalen Feldern wird null zurückgegeben.
HTTP-Status-Ausnahmen erben von ApiStatusException. Netzwerkfehler und Timeouts lösen ApiConnectionException aus.
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}");
}
Status exceptions expose ErrorCategory, ErrorCode, UserMessage, RetryAfter, TechnicalDetails, RequestId, TraceId und Body. Fehlende optionale Felder sind null.
Browse kann HTTP 202 Accepted zurückgeben, wenn ein Crawl aussteht. Dies ist eine normale Antwort, keine Ausnahme, und das SDK fragt nicht automatisch ab. Verwenden Sie die Antwort-URL und den UTC-Zeitstempel retryAfter, um es später erneut zu versuchen. Partielle HTTP-Antworten 200 können ein truncationReason enthalten, z. B. "encumbrance".
Debuggen und nächste Schritte
- Schließen Sie
traceIdbeim Kontaktieren des Supports ein. Rust verwendettrace_id, Java verwendetgetTraceId(), und .NET verwendetTraceId. - Verwenden Sie Telemetrie, um Versuche, Antwortcodes und verstrichene Zeit zu korrelieren.
- Überprüfen Sie den strukturierten Fehlertext, bevor Sie einen Fehler als wiederholbar behandeln. Weitere Informationen finden Sie unter Fehlerbehandlung.
- Fügen Sie Klick- und Zitatinstrumentation hinzu, wenn Suchergebnisse angezeigt oder zitiert werden.