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.
Note
Otomatik ve Otomatik Gelişmiş genel olarak 17 Kasım 2026'dan itibaren her Web IQ AppID'de kullanılabilir. Tam belge erişimi olmayan appID'ler geçişler alır.
Bitiş noktası:POST https://api.microsoft.ai/v3/auto
Tüm istekler için bir API anahtarı veya Microsoft Entra ID erişim belirteci gerekir. Kurulum yönergeleri için bkz. Kimlik doğrulaması .
Numune isteği
curl -X POST "https://api.microsoft.ai/v3/auto" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "Microsoft AI announcements",
"language": "en",
"region": "US",
"location": "lat:47.6062;long:-122.3321",
"mode": "lite",
"maxResponseLength": 30000,
"maxCitations": 10,
"responseFilter": ["web", "news"]
}'
Kapsamlı istek örneği
Adlandırılmış bir kapsam kullanarak Otomatik'te Web ve Haber alımını filtrelemek için (bkz . Kapsamlarla sonuçları filtreleme), scopeName ve failOnMissingScopeekleyin:
curl -X POST "https://api.microsoft.ai/v3/auto" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "product setup guide",
"scopeName": "ProductDocs",
"failOnMissingScope": true,
"mode": "lite",
"responseFilter": ["web", "news"]
}'
Parameters
| Parametre | Required | Tür | Default | Description |
|---|---|---|---|---|
query |
Yes | string | - | 1 ile 1.000 karakter arası arama sorgusu. |
language |
No | string | en |
İki harfli ISO 639-1 arabirim dili. |
region |
No | string | US |
İki harfli pazar veya ülke/bölge kodu. |
mode |
No | string | lite |
lite hızı önceliklendirir; advanced kapsamlılığa öncelik sağlar. |
maxResponseLength |
No | integer | 30000 | Toplam yanıt uzunluğu için değil, web sonuçları için maksimum içerik uzunluğu. 1500'in altındaki değerler 1500'e sıkıştırılır; 500000'in üzerindeki değerler 500000'e sıkıştırılır. Tam belge erişimi olmayan AppID'ler için en fazla 30000'dir. |
maxCitations |
No | integer | 10 | 1 ile 50 arasında, istenecek en fazla web alıntısı sayısı. 1'in altındaki değerler 1'e sıkıştırılır; 50'nin üzerindeki değerler 50 ile eşlenir. |
location |
No | string | - | Biçimindeki lat:<latitude>;long:<longitude> coğrafi bağlam, örneğin lat:47.6062;long:-122.3321. |
responseFilter |
No | stringler dizisi | - | Uygun yanıt türleri: web, news, timezone, weather, images, videos. |
includeSites |
No | stringler dizisi | - | En fazla 250 giriş içeren uygun Web sonuçlarını bu sitelerle (isteğe bağlı yollara sahip etki alanları) kısıtlar. Haberler ve diğer yanıt türleri filtrelenmez. Listeyi kısa tutun ve en iyi sonuçlarla ilgili olun. Yollar en fazla iki segmenti destekler; daha derin yollar kesilir, bu nedenle example.com/a/b/c olarak example.com/a/bdeğerlendirilir. |
excludeSites |
No | stringler dizisi | - | En fazla 250 giriş ve ile aynı yol kuralları includeSitesile bu sitelerden (isteğe bağlı yollara sahip etki alanları) Web sonuçlarını atlar. Bir site her iki listede de görünürse, hariç tutulur. Haberler ve diğer yanıt türleri filtrelenmez. |
scopeName |
No | string | - | Seçili Web IQ AppID ödeme hesabına atanan koleksiyondan adlandırılmış bir kapsam. Boşluk olmadan 1-128 ASCII harf, rakam, ., _veya -kullanın. Otomatik için kapsamlar yalnızca Web ve Haber sonuçlarını kısıtlar. Diğer yanıt türleri kapsama göre filtrelenmez ve olduğunda bile scopeAppliedtruebunun dışında sonuçlar içerebilir. Atlanır veya null adlandırılmış kapsam istenilmez anlamına gelir. Bkz . Sonuçları Kapsamlarla filtreleme. |
failOnMissingScope |
No | boolean | true |
için scopeNamegeri dönüşü denetler; atlanır veya null anlamına gelir true. Hizmet kapsamın uygulanamadığını bildirirse, true doğrulanmış bir eksik kapsam için HTTP 400 (HandlerInvalidInput) veya diğer kapsam hataları için HTTP 500 (ScopeFailedToApply) döndürür.
false , kapsam olmadan ve scopeApplied: false bu sonuç bildirildiğinde aramaya izin verir. Her iki değerle de geçerli bir kapsam uygulanır; sıfır eşleşen sonuçlar bir kapsam hatası değildir. Adlandırılmış kapsam olmadan hiçbir etkisi yoktur. Bkz. Adlandırılmış kapsam hataları. |
Response
Başarılı bir kanıt yanıtı döndürür 200 OK. Her sonuç, bir türlenmiş kanıt nesnesi ve onu destekleyen alıntılar içerir. Desteklenmeyen veya yanlış biçimlendirilmiş kanıtlar, alıntılarıyla birlikte atlanır. Sağlanan her kanıt sonucu atlanırsa boş results olur.
AutoEvidenceResponse
| Field | Tür | Description |
|---|---|---|
results |
AutoEvidenceResult dizisi | Bu sonucun kapsamı alıntılarla eşleştirilmiş kanıt öğeleri. |
querySignals |
QuerySignals | Arama sorgusu için sorgu düzeyi derecelendirme sinyalleri. |
scopeApplied |
boole (isteğe bağlı) |
true , istenen kapsamın uygulandığı anlamına gelir, en son tanımı olması gerekmez.
false kapsamın uygulanmadığı anlamına gelir; failOnMissingScope: false bu kapsamsız yanıta izin verir. Hizmet bir uygulama sonucu bildirmediğinde atlanır. olmadan scopeNameadlandırılmış kapsam istenmiyor; alanın mevcut olduğunu veya her zaman falseolduğunu varsaymayın. Genel yayma değil geçerli isteği açıklar. |
traceId |
string | Hata ayıklama ve destek için bağıntı kimliği. |
QuerySignals
| Field | Tür | Description |
|---|---|---|
freshness |
boolean | Bu sorgu için yeni belgelerin diğer belgelere göre önceliklendirilip önceliklendirilmeyeceğini gösterir. |
AutoEvidenceResult
| Field | Tür | Description |
|---|---|---|
evidence |
AutoEvidence | Yazılan kanıt oluşturuldu. |
citations |
AutoEvidenceCitation dizisi | Yalnızca bu kanıt sonucunu destekleyen alıntılar. |
AutoEvidence
Kanıt nesnesinin kendi type ayırıcısı şemasını contentseçer. Karşılık gelen tanımı bulmak için kanıt türü dizinini kullanın.
| Field | Tür | Description |
|---|---|---|
type |
string | Kanıt şemasını tanımlayan ayrımcı. Değerler büyük/küçük harfe duyarlıdır, örneğin structured/timeZone. |
content |
dize veya nesne | Şekli öğesine typebağlı olan metin veya yapılandırılmış içerik. |
AutoEvidenceCitation
Alıntı alanları yanıt türüne ve kullanılabilir kaynak meta verilerine göre farklılık gösterir. Her alıntıda her alan mevcut değildir.
| Field | Tür | Description |
|---|---|---|
contentSource |
string | Alıntı kaynağı. |
source |
string | Alıntı yapılan sitenin adı. |
siteIcon |
string | Alıntı yapılan sitenin simge URL'si. |
title |
string | Alıntı başlığı. |
url |
string | Alıntı URL'si. |
publishedBy |
string | Alıntı yapılan içeriğin Publisher. |
hostPageUrl |
string | Alıntı yapılan içeriği barındıran sayfanın URL'si. |
lastUpdatedAt |
string | Son güncelleştirme zaman damgası. |
crawledAt |
string | Gezinme zaman damgası. |
language |
string | İçerik dili. |
isAdult |
boolean | Alıntının yetişkinlere açık içerik içerip içermediği. olduğunda açıkça truedöndürülür; atlanmış bir alanı olarak falseele alır. |
Yanıta özgü alıntılar aşağıdaki meta verileri de içerebilir:
| Field | Tür | Şunlar için geçerlidir: | Description |
|---|---|---|---|
observedAt |
string | Weather | Alıntı kaynağı tarafından sağlanan gözlem zaman damgası. |
Örnek yanıt
{
"results": [
{
"evidence": {
"type": "text",
"content": "Microsoft announced a new set of AI capabilities."
},
"citations": [
{
"contentSource": "web",
"url": "https://www.microsoft.com/en-us/ai",
"title": "Microsoft AI",
"language": "en"
}
]
}
],
"querySignals": { "freshness": true },
"traceId": "00000000000000000000000000000000"
}
Bu örnekte atlandığından isAdult istemciler bunu olarak falseele almalıdır.
Kanıt türleri
Bir kanıt nesnesinin content şemasını aramak için bu dizini kullanın. İsteğin responseFilter yanıtlarındaki yanıt kategorileri, yanıttaki kanıt ayırıcılarıyla aynı değildir: örneğin, timezone döndürülen kanıt türü olurken saat dilimi yanıtları istemektedir structured/timeZone.
| Yanıt kategorisi | Kanıt type |
İçerik tanımı |
|---|---|---|
web |
text |
Metin kanıtı: dize içeriği. |
news |
text/news |
Metin kanıtı: İsteğe bağlı küçük resim içeren dize içeriği. |
images |
media/image |
Görüntü kanıtı: görüntü boyutları, resim yazısı ve küçük resim resmi. |
videos |
media/video |
Video kanıtı: kayıttan yürütme meta verileri, küçük resim ve isteğe bağlı anlar. |
weather |
structured/weather |
Hava durumu nesnesi: koşullar, tahminler, uyarılar ve güneş ışığı verileri. |
timezone |
structured/timeZone |
Saat dilimi nesnesi: yerel saatler, UTC uzaklıkları ve karşılaştırmalar. |
Aşağıdaki tanımlarda genel alanlar açıklanmaktadır. Alanlar kullanılamadığında atlanabilir; atlanmış bir alan sıfır ölçüm veya boş bir yanıt anlamına gelmez. Kaynak meta veriler ve ilişkilendirme, her tanımda yinelenen bir yanıt zarfı yerine kapsayan sonucun alıntılarına aittir.
Örnekler tam yanıtlar değil, açıklayıcı evidence parçalardır. Kapsayan ve citations yapı için örnek yanıtaresults bakın.
Metin kanıtı
( text Web) ve text/news (Haber) content için, nesne yerine bir dizedir. Haber kanıtlarının yanı contentsıra bir thumbnail de bulunabilir.
| Field | Tür | Description |
|---|---|---|
content |
string | Sonuç için metin kanıtı. |
thumbnail |
object (isteğe bağlı) | (dize), (tamsayı) width ve height (tamsayı) içeren url haber küçük resmi. Boyutlar piksel cinsindendir. |
{
"type": "text/news",
"content": "An example news summary.",
"thumbnail": {
"url": "https://example.com/news-thumbnail.jpg",
"width": 320,
"height": 180
}
}
Görüntü kanıtı
content için media/imagebir görüntü nesnesidir. Kaynak görüntü URL'si, barındırma sayfası URL'si, başlık ve kaynak tarihler, kullanılabilir olduğunda sonucun alıntılarında sağlanır.
| İçerik alanı | Tür | Description |
|---|---|---|
caption |
string | Görüntünün oluşturulan açıklaması. |
width |
integer | Piksel cinsinden görüntü genişliği. |
height |
integer | Piksel cinsinden görüntü yüksekliği. |
thumbnailUrl |
string | Küçük resim resmi URL'si. |
lastUpdatedAt |
string | Kullanılabilir olduğunda ISO 8601 biçiminde kaynak tarihi. |
{
"type": "media/image",
"content": {
"caption": "An example city skyline.",
"width": 1920,
"height": 1080,
"thumbnailUrl": "https://example.com/skyline-thumbnail.jpg"
}
}
Video kanıtı
content için media/videobir video nesnesidir. Video başlığı, URL, yayımcı ve kaynak tarih gibi kaynak ayrıntıları, kullanılabilir olduğunda sonucun alıntılarında sağlanır.
| İçerik alanı | Tür | Description |
|---|---|---|
description |
string | Video içeriğinin açıklaması. |
summary |
string | Videonun kısa özeti veya vurgusu. |
viewCount |
integer | Video görüntüleme sayısı. |
length |
string | Video süresi biçimindedir HH:MM:SS . |
allowHttpsEmbedding |
boolean | HTTPS eklemeye izin verilip verilmeyeceği. |
allowMobileEmbedding |
boolean | Mobil eklemeye izin verilip verilmeyeceği. |
embeddingUrl |
string | Videoyu eklemek için URL. |
thumbnailUrl |
string | Video küçük resim URL'si. |
width |
integer | Piksel cinsinden video genişliği. |
height |
integer | Piksel cinsinden video yüksekliği. |
lastUpdatedAt |
string | Kullanılabilir olduğunda ISO 8601 biçiminde kaynak tarihi. |
bestMomentIndex |
integer | Uygun olduğunda en iyi anın veya vurgunun dizini. |
moments |
VideoMoment dizisi | Kullanılabilir olduğunda video segmentleri. Dizi boş olabilir. |
{
"type": "media/video",
"content": {
"viewCount": 1200,
"length": "00:02:30",
"thumbnailUrl": "https://example.com/video-thumbnail.jpg",
"moments": []
}
}
VideoMoment
| Field | Tür | Description |
|---|---|---|
title |
string | Segment başlığı. |
description |
string | Segmentin açıklaması. |
startTime |
string | Segment başlangıç zamanı biçimindedir d.hh:mm:ss . |
endTime |
string | Kesim bitiş saati d.hh:mm:ss biçimindedir. |
momentUrl |
string | Segmente doğrudan URL. |
Hava durumu nesnesi
Sorgu hava durumuyla ilgili olduğunda, Otomatik konum başına bir structured/weather sonuç döndürebilir. Alanlar kullanılabilir olduğunda eklenir. Sayısal ölçümleri ile unitsbirlikte okuyun; sabit birimli bir sistem olduğunu varsaymayın.
| İçerik alanı | Tür | Description |
|---|---|---|
location |
string | Konum adı, örneğin Seattle, Washington. |
url |
string | Konumun hava durumu ilişkilendirme URL'si. Sonucun alıntısında aynı URL vardır. |
units |
Obje | Birim sistemi (system) ve , speed, pressure, distance, heightve timeiçin temperaturebirimler. |
alerts |
WeatherAlert dizisi | Kullanıcının ülkesine veya bölgesine göre filtrelenmiş konum için etkin veya son hava durumu uyarıları. |
currentWeather |
Obje | , , , , , feelsLike, , universalThermalClimateIndex, humidity, dewPoint, , pressure, , uvuvLevelwindGustairQualitywindDirectionwindSpeedvisibilityve observedAt kullanılabilir olduğunda dahil olmak üzere conditiongeçerli koşullar. temperaturedayPeriod |
forecastedWeather |
nesne dizisi | , , condition, temperatureHigh, , temperatureLow, feelsLikeHigh, feelsLikeLow, , precipitationChance, yağmur ve kar miktarları ile günlük tahminlervalidDate, humidity, day, night, almanac, ve hourly kullanılabilir olduğunda tahminler. |
sunlight |
Obje | Sorgu bir tarih istediğinde belirli bir tarih için gün doğumu, gün batımı, ay ışığı, ay kümesi ve ay evresi. |
Current airQuality , , severityve primaryPollutantvalidAtiçerebilirindex. Günlük tahminler humidity ve lowiçerebilirhigh. Ve day alt tahminleri , , precipitationChancewindSpeedve windDirectioniçerebilircondition.night için almanac güneş ve ay verilerini validDateiçerir.
{
"type": "structured/weather",
"content": {
"location": "Seattle, Washington",
"units": {
"system": "Imperial",
"temperature": "F"
},
"currentWeather": {
"condition": "Cloudy",
"temperature": 50
}
}
}
WeatherAlert
| Field | Tür | Description |
|---|---|---|
id |
string | Kullanılabilir olduğunda sağlayıcıdan gelen uyarı tanımlayıcısı. |
name |
string | Hava durumu olay adı, örneğin Frost. |
severity |
string | Önem derecesi, örneğin Advisory, , Watchveya Warning. |
status |
string | Uyarı durumu, örneğin Ongoing. |
issuingAuthority |
string | Uyarıyı veren kuruluş, örneğin National Weather Service. |
url |
string | Veren yetkiliye bağlantı. Kaynak tarafından tedarik edildiğinde dahil. |
description |
string | Tehlike açıklaması ve etkilenen bölge. |
safetyGuidance |
string | Uygun olduğunda önerilen güvenlik eylemleri. |
issuedAt, effectiveAt, expiresAt |
string | Uyarı yayımlandığında geçerlilik kazanır ve süresi dolar. |
Saat dilimi nesnesi
content içinstructured/timeZone, yerel saatleri açıklar veya iki saat dilimini karşılaştırır. Konum araması döndürebilirtimeZones; karşılaştırma bunun yerine , endTimeZoneve timeDifferencedöndürebilirstartTimeZone. Her yanıtta bu alanların tümünü gerekli kmayın.
| İçerik alanı | Tür | Description |
|---|---|---|
description |
string | Kullanılabilir olduğunda, insan tarafından okunabilen yanıt özeti. |
timeZones |
TimeZoneEntry dizisi | Tek konumlu veya çok konumlu bir zaman yanıtı için girişler. |
startTimeZone |
TimeZoneEntry | Karşılaştırma için kaynak saat dilimi. |
endTimeZone |
TimeZoneEntry | Karşılaştırma için hedef saat dilimi. |
timeDifference |
string | Karşılaştırma için insan tarafından okunabilen zaman farkı açıklaması. |
{
"type": "structured/timeZone",
"content": {
"timeZones": [
{
"timeZoneName": "Pacific Standard Time",
"timeZoneAbbreviation": "PST",
"location": "Seattle, Washington",
"utcOffset": -8,
"utcTime": "Monday, 2026-11-16T05:00:00Z",
"localTime": "Sunday, 2026-11-15T21:00:00-08:00"
}
]
}
}
TimeZoneEntry
| Field | Tür | Description |
|---|---|---|
timeZoneName |
string | Tam saat dilimi adı. |
timeZoneAbbreviation |
string | Kısaltma, örneğin PST veya IST. |
location |
string | Girişle ilişkili şehir, ülke veya bölge. |
utcOffset |
number | Saat cinsinden UTC uzaklığı. Kesirli olabilir, örneğin 5.5, veya kullanılamadığında atlanabilir. |
utcTime |
string | Biçimlendirilmiş dize olarak UTC saati. |
localTime |
string | Biçimlendirilmiş dize olarak yerel saat. |
Zaman dizeleri haftanın günü ön ekini içerebilir; bunların iso 8601 zaman damgaları olduğunu varsaymayın.
Hata kodları
| Durum kodu | Description |
|---|---|
| 200 | sonuç içermeyen geçerli bir arama da dahil olmak üzere istek başarılı oldu. |
| 400 | Geçersiz parametreler veya hatalı biçimlendirilmiş JSON. |
| 401 | Kimlik doğrulaması kimlik bilgileri eksik veya geçersiz. |
| 403 | Kimliği doğrulanmış Web IQ AppID, Otomatik için etkinleştirilmemiş. |
| 429 | Hız veya kota sınırı aşıldı. |
| 500 | İç hizmet hatası. |
| 503 | Gerekli bir hizmet kullanılamıyor. |
| 504 | İstek zaman aşımına uğradı. |
Paylaşılan hata şeması ve yeniden deneme kılavuzu için bkz. Hata işleme.