Otomatik REST API başvurusu

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.