Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
Tavsiye
Microsoft Ignite 2026'da mısınız?Tüm Web IQ kaynaklarını tek bir yerde bulabilirsiniz: belgeler, eğitim, kod örnekleri ve ekiple iletişim kurma.
Birkaç dakika içinde ilk Microsoft Web IQ API çağrınızı yapın. Web'de arama yapıp yanıtı inceleyin ve bilinen bir URL'den sorgu odaklı bölümleri ayıklayın. Ek örnekler, Places Search ve Otomatik kanıt almayı gösterir.
Henüz bir Web IQ kaynağınız yoksa devam etmeden önce Azure portalını veya Azure CLI kullanarak bir kaynak oluşturun.
Tüm örnekleri birlikte değiştirmek için bu sayfanın üst kısmından bir SDK veya REST örneği seçin. SDK'lar kimlik doğrulamasını, yeniden denemeleri ve yanıt türlerini sizin için işler.
API anahtarları, Web IQ'yu değerlendirmenin en hızlı yoludur. Üretim iş yükleri için Microsoft Entra ID kullanın.
Prerequisites
- Profil Yönetimi'nden bir Web IQ API anahtarı.
Uyarı
Uygulamanız Çin'de çalışıyorsa arama uç noktaları için https://api.microsoftol.com/v3 yerine https://api.microsoft.ai/v3 çağrısı yapın. REST örneklerinde URL'yi değiştirin. Bir SDK istemcisi oluştururken, aynı temel URL'yi Python'ın baseUrl bağımsız değişkeni, TypeScript'in base_url seçeneği, Rust'ın WebIqClient::builder().base_url(...), Java'nın WebIQClientOptions.builder().baseUrl(...) veya .NET'in WebIQClientOptions.BaseUrl özelliğiyle ayarlayın. Bkz.: Temel URL.
Tavsiye
Kod olmadan kılavuzlu bir başlangıç mı tercih ediyorsunuz? Web IQ Geliştirici Portalı'nda Kullanmaya başlayın'ı izleyin: Uygulama profilinizi seçin, BIR API anahtarı oluşturun, Playground'dan istek gönderin, oluşturulan kodu kopyalayın ve kullanımınızı denetleyin.
1. API anahtarınızı depolayın
Anahtarı bir ortam değişkenine yerleştirin; böylece istek örneklerinde tekrarlanmaz ve kaynak kodunuza yerleştirilmez.
macOS veya Linux
export WEBIQ_API_KEY="your-api-key"
Windows PowerShell
$env:WEBIQ_API_KEY="your-api-key"
Warning
Anahtarınızı kaynak denetimine işlemeyin veya tarayıcıda veya istemci tarafı kodunda kullanıma sunmayın. Üretim kimlik bilgilerini gizli yönetimi aracında depolayın.
2. Web'de arama
Bir sorunuz veya sorgunuz varsa ve Web IQ'nin ilgili sayfaları bulmasını ve derecelendirmesini istiyorsanız Web Search kullanın.
Her istekte, contentFormat = passage, maxLength = 3000 ve maxResults = 10 ayarlarını optimum çalışma noktası için ayarlamanızı öneririz. Buradan, bu ayarlarda kullanım örneğiniz temelinde ince ayarlar yapabilirsiniz.
Uç nokta:POST https://api.microsoft.ai/v3/search/web
curl --request POST "https://api.microsoft.ai/v3/search/web" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"query": "latest developments in retrieval augmented generation",
"maxResults": 10,
"contentFormat": "passage",
"maxLength": 3000
}'
SDK'yı python -m pip install webiq==1.2.1 ile (Python 3.11 veya üzeri) yükleyin, ardından çalıştırın:
import os
from webiq import WebIQClient
from webiq.types import ContentFormat
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
results = client.web.search(
"latest developments in retrieval augmented generation",
max_results=10,
content_format=ContentFormat.passage,
max_length=3000,
)
for result in results.webResults or []:
print(result.title, result.url)
npm install @microsoft/webiq@1.2.1 ile SDK'yı yükleyin (22.x için Node.js 22.18+ veya 24+). Bu örneği search.mts olarak kaydedin ve node search.mts ile çalıştırın.
import { WebIQClient, ContentFormat } from "@microsoft/webiq";
async function main() {
const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });
try {
const results = await client.web.search(
"latest developments in retrieval augmented generation",
{
maxResults: 10,
contentFormat: ContentFormat.PASSAGE,
maxLength: 3000,
},
);
for (const result of results.webResults ?? []) {
console.log(result.title, result.url);
}
} finally {
await client.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
Rust 1.88 veya sonraki bir sürüm kullanan bir projede, cargo add tokio --features macros,rt-multi-thread ve cargo add webiq@1.2.1 komutlarını çalıştırın. Bu örneği src/main.rs olarak kaydedin ve cargo run çalıştırın.
use webiq::{ContentFormat, WebIqClient, WebSearchOptions};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
let results = client.web().search(
"latest developments in retrieval augmented generation",
WebSearchOptions::new()
.max_results(10)
.content_format(ContentFormat::Passage)
.max_length(3000),
).await?;
for result in results.web_results.unwrap_or_default() {
println!("{:?} {:?}", result.title, result.url);
}
Ok(())
}
Java 11 veya üzeri için yapılandırılmış bir Maven projesinde, bu bağımlılığı pom.xml öğesine ekleyin:
<dependency>
<groupId>com.microsoft.webiq</groupId>
<artifactId>webiq</artifactId>
<version>1.2.1</version>
</dependency>
Bu örneği src/main/java/Search.java olarak kaydedin ve mvn compile exec:java -Dexec.mainClass=Search çalıştırın.
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.ContentFormat;
import com.microsoft.webiq.models.WebResponse;
import com.microsoft.webiq.models.WebResult;
import com.microsoft.webiq.resources.WebSearchOptions;
public class Search {
public static void main(String[] args) {
try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
WebResponse results = client.web.search(
"latest developments in retrieval augmented generation",
WebSearchOptions.builder()
.maxResults(10)
.contentFormat(ContentFormat.PASSAGE)
.maxLength(3000)
.build());
if (results.getWebResults() != null) {
for (WebResult result : results.getWebResults()) {
System.out.println(result.getTitle() + " " + result.getUrl());
}
}
}
}
}
.NET 8 veya sonraki bir konsol projesinde dotnet add package Microsoft.WebIQ --version 1.2.1 komutunu çalıştırın. Bu örneği Program.cs olarak kaydedin ve dotnet run çalıştırın.
using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;
string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);
var results = await client.Web.SearchAsync(
"latest developments in retrieval augmented generation",
request =>
{
request.MaxResults = 10;
request.ContentFormat = ContentFormat.Passage;
request.MaxLength = 3000;
});
foreach (var result in results.WebResults ?? [])
Console.WriteLine($"{result.Title} {result.Url}");
import os
import json
import requests
response = requests.post(
"https://api.microsoft.ai/v3/search/web",
headers={
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
},
json={
"query": "latest developments in retrieval augmented generation",
"maxResults": 10,
"contentFormat": "passage",
"maxLength": 3000,
},
timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Bu örneği search.mjs olarak kaydedin ve node search.mjs ile çalıştırın.
const response = await fetch("https://api.microsoft.ai/v3/search/web", {
method: "POST",
headers: {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
query: "latest developments in retrieval augmented generation",
maxResults: 10,
contentFormat: "passage",
maxLength: 3000,
}),
});
if (!response.ok) {
throw new Error(`Web Search failed: ${response.status} ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));
3. Yanıtı anlama
Başarılı bir Web Araması, webResults dizisi döndürür. Bu kısaltılmış örnek, en sık kullanacağınız alanları gösterir:
{
"webResults": [
{
"title": "Example result",
"url": "https://example.com/article",
"content": "The query-relevant passage extracted from the page...",
"crawledAt": "2026-07-18T12:00:00Z"
}
],
"traceId": "00000000000000000000000000000000"
}
-
titleveurlkaynağı tanımlar. -
content, istekcontentFormat: "passage"kullandığı için sorguyla ilgili bölümü içerir. -
traceIdWeb IQ Desteği'nin bir isteği araştırmasını sağlar.
REST yanıtlarında ve MCP aracı sonuçlarında, iç içe sonuç nesnelerinin alanları da dahil olmak üzere dize ("") değerleri olan null veya boş olan model alanları atlanır; liste alanlarının da bulunmadığı Yerler dışında boş liste/dizi ([]) alanları tutulur. Eksik bir alanı mevcut değil, boş veya eksik bir listeyi ise öğe içermiyor olarak değerlendirin. Yalnızca boşluk dizeleri, false, 0, boş sözlükler, tek tek dizi/sözlük girdileri ve eklenmiş ham JSON korunur. Kök diziler ve MCP content gibi protokol zarf koleksiyonları değişmeden kalır.
Tüm parametreler ve yanıt alanları için Bkz. Web Araması API'si başvurusu .
4. Uç nokta seçin
| Şununla başla | Use | Ne elde edersiniz? |
|---|---|---|
| Soru veya arama sorgusu | Web Search | Sorguyla ilgili içeriğe sahip sıralanmış sayfalar |
| Belirli bir URL | Göz at | Bu sayfadan ayıklanan içerik |
| Yer veya yerel işletme sorgusu | Yerler | Adresler ve açılış saatleri gibi yapılandırılmış yer ayrıntıları |
| Otomatik olarak seçilen yanıt türleri gerektiren bir sorgu | Auto, REST veya 1.2.1 ve sonraki SDK sürümleri aracılığıyla | sonuç kapsamındaki atıflarla türlendirilmiş kanıt |
| Alışveriş veya ürün sorgusu | REST aracılığıyla Commerce (özel önizleme) | Satıcı tekliflerine, fiyatlarına ve ürün ayrıntılarına sahip sıralanmış ürünler |
Ortak bir temel oluşturma iş akışı her iki uç noktayı da kullanır: ilgili kaynakları arayın, bir sonuç URL'si seçin ve ardından bir izleme sorusuyla ilgili bölümleri ayıklamak için bu URL'ye göz atın.
5. URL'den içerik ayıklama
Okumak istediğiniz sayfayı zaten biliyorsanız Gözat'ı kullanın. Sorunuzla en ilgili sayfa bölümlerini almak için passage öğesini contentFormat olarak ayarlayın ve boş olmayan bir query sağlayın.
liveCrawl: "fallback" Web IQ'dan, sayfa dizinde zaten mevcut değilse sayfayı taramasını ister. Canlı tarama, yayıncıya saygı kısıtlamalarına ve kullanılabilirliğe tabidir; fallback gerçek bir taramayı garanti etmez.
Tüm örnekler, temellendirme için önerilen biçim olan sorgu odaklı pasajlar istemektedir. Seçimin query boş olmaması ve 1000 karakterden uzun olmaması gerekir; maxLength döndürülen içerik miktarını ayrı ayrı denetler. Tam belge biçimleri (text, htmlve markdown) tam belge erişimi gerektirir.
Uç nokta:POST https://api.microsoft.ai/v3/browse
curl --request POST "https://api.microsoft.ai/v3/browse" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
"query": "How fast is Web IQ",
"contentFormat": "passage",
"maxLength": 3000,
"liveCrawl": "fallback"
}'
SDK'yı python -m pip install webiq==1.2.1 ile (Python 3.11 veya üzeri) yükleyin, ardından çalıştırın:
import os
from webiq import WebIQClient
from webiq.types import BrowseContentFormat
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
page = client.browse.fetch(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
query="How fast is Web IQ",
content_format=BrowseContentFormat.passage,
max_length=3000,
live_crawl="fallback",
)
print(page.content)
npm install @microsoft/webiq@1.2.1 ile SDK'yı yükleyin (22.x için Node.js 22.18+ veya 24+). Bu örneği browse.mts olarak kaydedin ve node browse.mts ile çalıştırın.
import { WebIQClient, BrowseContentFormat, LiveCrawlMode } from "@microsoft/webiq";
async function main() {
const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });
try {
const page = await client.browse.fetch(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
{
query: "How fast is Web IQ",
contentFormat: BrowseContentFormat.PASSAGE,
maxLength: 3000,
liveCrawl: LiveCrawlMode.FALLBACK,
},
);
console.log(JSON.stringify(page, null, 2));
} finally {
await client.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
Rust 1.88 veya sonraki bir sürüm kullanan bir projede, cargo add tokio --features macros,rt-multi-thread ve cargo add webiq@1.2.1 komutlarını çalıştırın. Bu örneği src/main.rs olarak kaydedin ve cargo run çalıştırın.
use webiq::{BrowseContentFormat, BrowseOptions, LiveCrawlMode, WebIqClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
let page = client.browse().fetch(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
BrowseOptions::new()
.query("How fast is Web IQ")
.content_format(BrowseContentFormat::Passage)
.max_length(3000)
.live_crawl(LiveCrawlMode::Fallback),
).await?;
println!("{}", page.content.unwrap_or_default());
Ok(())
}
Java 11 veya üzeri için yapılandırılmış bir Maven projesinde, bu bağımlılığı pom.xml öğesine ekleyin:
<dependency>
<groupId>com.microsoft.webiq</groupId>
<artifactId>webiq</artifactId>
<version>1.2.1</version>
</dependency>
Bu örneği src/main/java/Browse.java olarak kaydedin ve mvn compile exec:java -Dexec.mainClass=Browse çalıştırın.
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.BrowseContentFormat;
import com.microsoft.webiq.models.BrowseResponse;
import com.microsoft.webiq.models.LiveCrawlMode;
import com.microsoft.webiq.resources.BrowseFetchOptions;
public class Browse {
public static void main(String[] args) {
try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
BrowseResponse page = client.browse.fetch(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
BrowseFetchOptions.builder()
.query("How fast is Web IQ")
.contentFormat(BrowseContentFormat.PASSAGE)
.maxLength(3000)
.liveCrawl(LiveCrawlMode.FALLBACK)
.build());
System.out.println(page.getContent());
}
}
}
.NET 8 veya sonraki bir konsol projesinde dotnet add package Microsoft.WebIQ --version 1.2.1 komutunu çalıştırın. Bu örneği Program.cs olarak kaydedin ve dotnet run çalıştırın.
using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;
string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);
var page = await client.Browse.FetchAsync(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
request =>
{
request.ContentFormat = BrowseContentFormat.Passage;
request.Query = "How fast is Web IQ";
request.MaxLength = 3000;
request.LiveCrawl = LiveCrawlMode.Fallback;
});
Console.WriteLine(page.Content);
import os
import json
import requests
response = requests.post(
"https://api.microsoft.ai/v3/browse",
headers={
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
},
json={
"url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
"query": "How fast is Web IQ",
"contentFormat": "passage",
"maxLength": 3000,
"liveCrawl": "fallback",
},
timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Bu örneği browse.mjs olarak kaydedin ve node browse.mjs ile çalıştırın.
const response = await fetch("https://api.microsoft.ai/v3/browse", {
method: "POST",
headers: {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
url: "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
query: "How fast is Web IQ",
contentFormat: "passage",
maxLength: 3000,
liveCrawl: "fallback",
}),
});
if (!response.ok) {
throw new Error(`Browse failed: ${response.status} ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));
Başarılı bir 200 yanıtı, title sayfasını, content ayıklanan traceId ve bir url içerir. Canlı gezinme, ISO 8601 UTC zaman damgası ile retryAfter dönebilir 202; o zamana kadar bekleyin ve aynı isteği yeniden gönderin. Yanıt sözleşmesinin tamamı için Browse API referansına göz atın.
6. Yerleri arayın (isteğe bağlı)
Yerel işletmeler ve diğer yerler hakkında yapılandırılmış bilgiler için Yerler Arama'yı kullanın. SDK örnekleri, 2. adımda yüklü olan 1.2.1 paketlerini kullanır.
Uç nokta:POST https://api.microsoft.ai/v3/search/places
curl --request POST "https://api.microsoft.ai/v3/search/places" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"query": "coffee in Seattle",
"maxResults": 5,
"language": "en",
"region": "US",
"location": "lat:47.6062;long:-122.3321"
}'
import os
from webiq import WebIQClient
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
places = client.places.search(
"coffee in Seattle",
max_results=5,
language="en",
region="US",
location="lat:47.6062;long:-122.3321",
)
for place in places.placeResults or []:
print(place.name, place.businessUrl)
Bu örneği places.mts olarak kaydedin ve node places.mts ile çalıştırın.
import { WebIQClient } from "@microsoft/webiq";
async function main() {
const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });
try {
const places = await client.places.search("coffee in Seattle", {
maxResults: 5,
language: "en",
region: "US",
location: "lat:47.6062;long:-122.3321",
});
for (const place of places.placeResults ?? []) {
console.log(place.name, place.businessUrl);
}
} finally {
await client.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
2. adımdaki Tokio kurulumunu kullanın. Bu örneği src/main.rs olarak kaydedin ve cargo run çalıştırın.
use webiq::{PlacesSearchOptions, WebIqClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
let places = client.places().search(
"coffee in Seattle",
PlacesSearchOptions::new()
.max_results(5)
.language("en")
.region("US")
.location("lat:47.6062;long:-122.3321"),
).await?;
for place in places.place_results.unwrap_or_default() {
println!("{:?} {:?}", place.name, place.business_url);
}
Ok(())
}
Bu örneği 2. adımdaki Maven projesinde src/main/java/Places.java olarak kaydedin ve mvn compile exec:java -Dexec.mainClass=Places komutunu çalıştırın.
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.PlaceItem;
import com.microsoft.webiq.models.PlacesResponse;
import com.microsoft.webiq.resources.PlacesSearchOptions;
public class Places {
public static void main(String[] args) {
try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
PlacesResponse places = client.places.search("coffee in Seattle",
PlacesSearchOptions.builder().maxResults(5)
.language("en").region("US")
.location("lat:47.6062;long:-122.3321").build());
if (places.getPlaceResults() != null) {
for (PlaceItem place : places.getPlaceResults()) {
System.out.println(place.getName() + " " + place.getBusinessUrl());
}
}
}
}
}
2. adımdaki .NET konsol projesinde bu örneği Program.cs olarak kaydedin ve dotnet run komutunu çalıştırın.
using Microsoft.WebIQ;
string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);
var places = await client.Places.SearchAsync("coffee in Seattle", request =>
{
request.MaxResults = 5;
request.Language = "en";
request.Region = "US";
request.Location = "lat:47.6062;long:-122.3321";
});
foreach (var place in places.PlaceResults ?? [])
Console.WriteLine($"{place.Name} {place.BusinessUrl}");
import os
import json
import requests
response = requests.post(
"https://api.microsoft.ai/v3/search/places",
headers={
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
},
json={
"query": "coffee in Seattle",
"maxResults": 5,
"language": "en",
"region": "US",
"location": "lat:47.6062;long:-122.3321",
},
timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Bu örneği places.mjs olarak kaydedin ve node places.mjs ile çalıştırın.
const response = await fetch("https://api.microsoft.ai/v3/search/places", {
method: "POST",
headers: {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
query: "coffee in Seattle",
maxResults: 5,
language: "en",
region: "US",
location: "lat:47.6062;long:-122.3321",
}),
});
if (!response.ok) {
throw new Error(`Places failed: ${response.status} ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));
placeResults'den sonuçları okuyun. Liste ve tek tek alanlar eksik olabilir, bu nedenle adresleri, açılış saatlerini veya diğer ayrıntıları kullanmadan önce eksik değerleri denetleyin.
Places API referansına bakın.
7. Auto ile kanıt alma
Web IQ'un alma kaynaklarını seçmesini ve destekleyici alıntılarla birlikte türlendirilmiş kanıt döndürmesini istediğinizde Auto'yu kullanın. Tarihler, konumlar ve birimler gibi ilgili kısıtlamaları koruyarak tam bir doğal dil sorusu sorun. Bu örneklerde, varsayılanı kullanmak ve istek girişimi başına 60 saniyeye izin vermek için mode atlanır.
Karmaşık sorular için daha kapsamlı alma gerektiğinde advanced değerini Auto Advanced olarak mode ayarlayın.
Otomatik, uygulamanızın kullanması için kanıt döndürür, oluşturulan son yanıtı döndürmez. Her kanıt sonucunu kendi alıntılarıyla okuyun; bir sonuçtaki alıntıları başka bir sonuç için destek olarak değerlendirmeyin. SDK örnekleri, 2. adımda yüklenen beş SDK'nın da 1.2.1 sürümünü kullanır.
Uç nokta:POST https://api.microsoft.ai/v3/auto
curl --request POST "https://api.microsoft.ai/v3/auto" \
--max-time 60 \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"query": "What are the latest developments in retrieval-augmented generation?",
"maxResponseLength": 30000,
"maxCitations": 5
}'
import os
from webiq import WebIQClient
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
evidence = client.auto.search(
"What are the latest developments in retrieval-augmented generation?",
max_response_length=30000,
max_citations=5,
timeout=60.0,
)
for result in evidence.results or []:
print(result.evidence)
for citation in result.citations or []:
print(citation.title, citation.url)
Bu örneği auto.mts olarak kaydedin ve node auto.mts ile çalıştırın.
import { WebIQClient } from "@microsoft/webiq";
async function main() {
const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });
try {
const evidence = await client.auto.search(
"What are the latest developments in retrieval-augmented generation?",
{ maxResponseLength: 30000, maxCitations: 5, timeout: 60_000 },
);
for (const result of evidence.results ?? []) {
console.log(result.evidence);
for (const citation of result.citations ?? []) {
console.log(citation.title, citation.url);
}
}
} finally {
await client.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
2. adımdaki Tokio kurulumunu kullanın. Bu örneği src/main.rs olarak kaydedin ve cargo run çalıştırın.
use webiq::{AutoSearchOptions, WebIqClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
let evidence = client.auto().search(
"What are the latest developments in retrieval-augmented generation?",
AutoSearchOptions::new()
.max_response_length(30000)
.max_citations(5)
.timeout(std::time::Duration::from_secs(60)),
).await?;
for result in evidence.results.unwrap_or_default() {
println!("{:?}", result.evidence);
for citation in result.citations.unwrap_or_default() {
println!("{:?} {:?}", citation.title, citation.url);
}
}
Ok(())
}
Bu örneği 2. adımdaki Maven projesinde src/main/java/Auto.java olarak kaydedin ve mvn compile exec:java -Dexec.mainClass=Auto komutunu çalıştırın.
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.AutoEvidenceCitation;
import com.microsoft.webiq.models.AutoEvidenceResult;
import com.microsoft.webiq.models.SearchAutoEvidenceResponse;
import com.microsoft.webiq.resources.AutoSearchOptions;
public class Auto {
public static void main(String[] args) {
try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
SearchAutoEvidenceResponse evidence = client.auto.search(
"What are the latest developments in retrieval-augmented generation?",
AutoSearchOptions.builder()
.maxResponseLength(30000).maxCitations(5)
.timeout(java.time.Duration.ofSeconds(60)).build());
if (evidence.getResults() != null) {
for (AutoEvidenceResult result : evidence.getResults()) {
System.out.println(result.getEvidence());
if (result.getCitations() != null) {
for (AutoEvidenceCitation citation : result.getCitations()) {
System.out.println(citation.getTitle() + " " + citation.getUrl());
}
}
}
}
}
}
}
2. adımdaki .NET konsol projesinde bu örneği Program.cs olarak kaydedin ve dotnet run komutunu çalıştırın.
using Microsoft.WebIQ;
using System.Text.Json;
string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);
var evidence = await client.Auto.SearchAsync(
"What are the latest developments in retrieval-augmented generation?",
request =>
{
request.MaxResponseLength = 30000;
request.MaxCitations = 5;
}, timeout: TimeSpan.FromSeconds(60));
foreach (var result in evidence.Results ?? [])
{
Console.WriteLine(JsonSerializer.Serialize(result.Evidence));
foreach (var citation in result.Citations ?? [])
Console.WriteLine($"{citation.Title} {citation.Url}");
}
import os
import json
import requests
response = requests.post(
"https://api.microsoft.ai/v3/auto",
headers={
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
},
json={
"query": "What are the latest developments in retrieval-augmented generation?",
"maxResponseLength": 30000,
"maxCitations": 5,
},
timeout=60,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Bu örneği auto.mjs olarak kaydedin ve node auto.mjs ile çalıştırın.
const response = await fetch("https://api.microsoft.ai/v3/auto", {
method: "POST",
signal: AbortSignal.timeout(60_000),
headers: {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
query: "What are the latest developments in retrieval-augmented generation?",
maxResponseLength: 30000,
maxCitations: 5,
}),
});
if (!response.ok) {
throw new Error(`Auto failed: ${response.status} ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));
Başarılı bir yanıt bir results dizi içerir. Her sonuç, tip belirtilmiş bir evidence nesnesini onu destekleyen citations ile eşleştirir. Boş veya olmayan results bir dizinin işlenmek için kanıtı yoktur. Kanıt türleri, yanıt örnekleri ve istek sınırları için Otomatik API başvurusuna bakın.
8. Commerce ile ürün arama (isteğe bağlı)
Alışveriş sorgusu için ürün ve satıcı tekliflerini bulmak için Ticaret API'lerini kullanın: Arama, birincil satıcı teklifleriyle dereceli ürünleri döndürür, Teklifler bir ürün için daha fazla teklif döndürür ve Ürün Ayrıntıları bir ürünün başlığını, açıklamasını ve derecelendirmesini döndürür.
Uyarı
Ticaret API'leri özel önizleme aşamasındadır ve tam belge erişimine sahip AppID'lerle sunulur. Erişim her uç nokta için ayrı ayrı etkinleştirilir. AppID'nizde yoksa, AppID'nizle bir Web IQ Destek isteği (sorun türü Kimlik Doğrulaması ve Erişim) açın.
Uç noktalar:POST https://api.microsoft.ai/v3/search/commerce/products, POST https://api.microsoft.ai/v3/fetch/commerce/products/offersve POST https://api.microsoft.ai/v3/fetch/commerce/products/details
Bu adım REST çağrılarını gösterir. Bunları görmek için sayfanın üst kısmındaki cURL, Python (REST) veya JavaScript (REST) seçeneğini belirleyin.
Ürünleri arayın:
curl --request POST "https://api.microsoft.ai/v3/search/commerce/products" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"query": "wireless headphones",
"maxResults": 3,
"language": "en",
"region": "US"
}'
Yanıttaki ilk üründen, id öğesini, skuId öğesini ve ilk teklifinin id öğesini kopyalayın. Aşağıda SKU_ID, OFFER_ID ve PRODUCT_ID öğelerini değiştirin, ardından daha fazla teklif ve ürün ayrıntılarını arayın. Bazı ürünler, skuId veya id olmadan yalnızca bir teklif döndürür: Teklifler için yalnızca offerId gönderin ve ürün veya SKU kimliği gerektiren Ürün Ayrıntıları'nı atlayın.
curl --request POST "https://api.microsoft.ai/v3/fetch/commerce/products/offers" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"productId": "PRODUCT_ID",
"skuId": "SKU_ID",
"offerId": "OFFER_ID",
"language": "en",
"region": "US"
}'
curl --request POST "https://api.microsoft.ai/v3/fetch/commerce/products/details" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"productId": "PRODUCT_ID",
"skuId": "SKU_ID",
"language": "en",
"region": "US"
}'
import json
import os
import requests
BASE_URL = "https://api.microsoft.ai/v3"
HEADERS = {
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
}
MARKET = {"language": "en", "region": "US"}
def post(path, body):
response = requests.post(BASE_URL + path, headers=HEADERS, json=body, timeout=30)
response.raise_for_status()
return response.json()
search = post("/search/commerce/products", {"query": "wireless headphones", "maxResults": 3, **MARKET})
products = search.get("products") or []
if not products:
print("No matching products.")
else:
product = products[0]
first_offer = (product.get("offers") or [{}])[0]
ids = {"productId": product.get("id"), "skuId": product.get("skuId")}
ids = {key: value for key, value in ids.items() if value}
offer_ids = {**ids, "offerId": first_offer.get("id")} if first_offer.get("id") else ids
offers = post("/fetch/commerce/products/offers", {**offer_ids, **MARKET})
# Product Details needs a product id or SKU id; some products return only an offer.
details = post("/fetch/commerce/products/details", {**ids, **MARKET}) if ids else None
print(json.dumps({"product": product, "offers": offers, "details": details}, indent=2))
Bu örneği commerce.mjs olarak kaydedin ve node commerce.mjs ile çalıştırın.
const baseUrl = "https://api.microsoft.ai/v3";
const headers = {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
};
const market = { language: "en", region: "US" };
async function post(path, body) {
const response = await fetch(`${baseUrl}${path}`, {
method: "POST",
headers,
body: JSON.stringify(body),
});
if (!response.ok) {
throw new Error(`${path} failed: ${response.status} ${await response.text()}`);
}
return response.json();
}
const search = await post("/search/commerce/products", {
query: "wireless headphones",
maxResults: 3,
...market,
});
const product = search.products?.[0];
if (!product) {
console.log("No matching products.");
} else {
const ids = {};
if (product.id) ids.productId = product.id;
if (product.skuId) ids.skuId = product.skuId;
const offerId = product.offers?.[0]?.id;
const offerIds = offerId ? { ...ids, offerId } : ids;
const offers = await post("/fetch/commerce/products/offers", { ...offerIds, ...market });
// Product Details needs a product id or SKU id; some products return only an offer.
const details = Object.keys(ids).length
? await post("/fetch/commerce/products/details", { ...ids, ...market })
: null;
console.log(JSON.stringify({ product, offers, details }, null, 2));
}
Arama, ürünleri birincil satıcı teklifleriyle derece sırasına göre döndürür; maxResults teklifleri değil ürünleri sınırlar. Teklifler önce birincil teklifi, ardından ek teklifleri döndürür. Eşleşme içermeyen geçerli bir istek, boş bir offers veya 200 OK dizisiyle products döndürür. Fiyatlar, para biriminin küçük birimlerindeki tamsayılardır: 39999 USD, $399.99'dır.
Bir kullanıcıyı veya kullanıcı için hareket eden bir aracıyı bir teklife göndermek için teklifin clickUrl öğesini bu yanıtta döndürüldüğü şekliyle tam olarak kullanın. Yalnızca satıcıyı tanımlayan displayUrl öğesini kullanmayın ve bağlantıyı yeniden yazmayın, kısaltmayın veya yeniden kullanmayın. Bir modelin bunları yeniden oluşturması yerine uygulama kodunda bağlantılar oluşturun.
Bkz. Teklif bağlantıları ve atıf ile Ticaret kılavuzu.
Troubleshooting
| Statü | Denetlenecek şeyler |
|---|---|
401 Unauthorized |
WEBIQ_API_KEY ayarlandığını ve isteğin bunu x-apikey üst bilgisinde gönderdiğini onaylayın. |
415 Unsupported Media Type |
Gönderin content-type: application/json. |
429 Too Many Requests |
Yeniden denemeden önce bekleyin ve istek sıklığını azaltın. |
Gözat 404 Not Found |
URL'nin herkese açık ve geçerli olduğunu onaylayın. Dizine alınan içerik kullanılamayabileceğinde liveCrawl: "fallback" kullanın. |
Gözat 202 Accepted |
retryAfter içindeki zamana (ISO 8601 UTC zaman damgası) kadar bekleyin, ardından aynı isteği yeniden gönderin. |
Otomatik 403 Forbidden |
Profil Yönetimi'nde İzin Verilen Hizmetler altında Auto'nun listelendiğini denetleyin. Değilse AppID'nizle bir Web IQ Desteği isteği açın. |
Diğer hatalar için traceId öğesini kaydedin ve bkz. Hata İşleme.
Web IQ Desteği'ne başvurmak için, traceId ve AppID’nizi veya AppID’niz yoksa şirketinizin adını ve Web IQ kaynağınızın adını ekleyin.
Sonraki Adımlar
- Web Araması ve Gözat API başvurularını keşfedin.
- Places ile yapılandırılmış yerel işletme verilerini veya Auto ile otomatik olarak seçilen kanıtları alın.
- Ticaret kılavuzuyla alışveriş deneyimi oluşturun.
- Python, TypeScript, Rust, Java ve .NET SDK'larını kullanın.
- MCP sunucusunu Claude Code, cursor veya VS Code'a yükleyin.
- Microsoft Entra ID ile üretim kimlik doğrulamayı ayarlayın.
- GitHub'da Web IQ kod örnekleri içindeki eksiksiz örnekleri çalıştırın.
- Web IQ ile web tabanlı bilgileri aracınıza tümleştirme eğitim modülünü alın.
- Microsoft IQ Serisinin Web IQ bölümü olan Ajanları gerçek dünya zekâsıyla temellendirme'yi izleyin.