Web Araması REST API başvurusu

Bitiş noktası:POST https://api.microsoft.ai/v3/search/web

Örnek İstek:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "latest trends in LLM RAG",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Parameters

Parametre	Required	Tür	Default	Description
query	Yes	string	-	Arama sorgusu dizesi. Uzunluk üst sınırı 1000 karakterdir. "site:" ve "-site:" işleçlerini, sonuçları belirli sitelerden (örneğin, "sorgu site:example.com") dahil etmek veya dışlamak için destekler. Bu işleçleri yalnızca gerektiğinde kullanın, doğal olarak sonuç ilgi düzeyini azaltırlar.
maxResults	No	integer	10	Döndürülecek en fazla sonuç sayısı. Varsayılan değer 10, maksimum değer ise 50'dir.
language	No	string	"en"	Arama sonuçlarında arabirim dili için 2 harfli ISO 639-1 dil kodu. Tam liste için bkz . Desteklenen Diller .
region	No	string	"US"	Sonuçların nereden gelmesi gerektiği için 2 harfli ülke/bölge kodu (ör. "ABD", "JP", "GB", vb.). Tam liste için bkz . Desteklenen Bölgeler .
location	No	string	-	"lat:<float>; long:<float>", örn. "lat:40.753250; long:-74.003807". Belirtilmezse, sorgudaki konum çıkarılır.
contentFormat	No	string	"passage" ("html" ve tam belge erişimi)	passage her sonucun sorguyla en ilgili bölümlerini döndürür (topraklama için önerilir). text markdown ve html tam belgeyi döndürerek yalnızca tam belge erişimine sahip uygulamalara uygulayın; bkz. Geçişler ve içerik biçimleri. Her istekte ayarlayın. Not: Web API'si bir snippet alan döndürmez.
maksimumUzunluk	No	integer	3000 (tam belge erişimine sahip 10000)	Sonuç başına en fazla karakter content sayısı 1 ile 500000 arasıdır. Tam belge erişimi olmadan en content fazla 3000 karakterdir. Bkz. Varsayılanlar ve sınırlar. Her istekte ayarlayın.
safeSearch	No	string	"katı"	Güvenli arama filtreleme düzeyi. Değerler: "off", "strict". Varsayılan değer "katı"dır.

İçerik biçimleri

Her sonucun sorguyla en ilgili bölümlerini en çok maxLength karakter olacak şekilde ayarlayınpassagecontentFormat = (3000 iyi bir başlangıç noktasıdır). Topraklama için önerilen biçimdir; SSS bölümünde , nedir passageve neden kullanılır? bölümüne bakın. Tam belge erişimine sahip uygulamalar, belgenin tamamını textolarak html da isteyebilir veya markdowndiğer uygulamalar için bu biçimler HTTP 403 döndürür. Bkz . Geçişler ve içerik biçimleri.

Güvenli Arama

Güvenli Arama modları, sonuçlar döndürülmeden önce Web API'sinin ne kadar hassas web içeriğini filtreleyebilmesini denetlemenize olanak sağlar. Hassas içerik şiddet, kendine zarar verme ve diğer kategorileri içerir. Varsayılan değer strict olarak belirlenmiştir.

Value	Description	Önerilen:
strict	Yetişkinlere yönelik, müstehcen, şiddet, nefret ve kendine zarar verme konularına ilişkin içerikleri engeller.	Çocuk güvenliği, eğitim, tüketici/muhafazakar dağıtımlar.
off	Yine de geçersiz içeriği engeller. Zararlı olabilecek diğer içerikler için son filtreleme sorumluluğunu kullanıcıya kaydırıyor.	Araştırma, analiz, işletmeyi kabul etme, gelişmiş 3P kullanım örnekleri.

Note

Sorgu işlecini site: kullanırsanız, yanıt değerden safeSearch bağımsız olarak yetişkin içeriği içerebilir. Yalnızca sitedeki içeriğin farkındaysanız ve senaryonuz yetişkinlere yönelik içerik olasılığını destekliyorsa kullanın site: .

İstek Üst Bilgileri

Field	Tür	Description
host	string	Microsoft AI API'leri için konak: api.microsoft.ai.
x-apikey veya Yetkilendirme	string	Kimlik doğrulaması için API anahtarınız veya Entra ID erişim belirteciniz.
içerik türü	string	İstek gövdesinin MIME türü. application/json adresini kullanın.

Response

Web Yanıtı

Field	Tür	Description
webResults	webResult dizisi	Web sayfası sonuçlarının listesi.
querySignals	querySignals	Arama sorgusu için sorgu düzeyi derecelendirme sinyalleri.
riskLevel	string	Sorgu için değerlendirilen güvenlik riski düzeyi. Olası değerler: low, moderate, high, veryHigh.
instrumentationClickBase	string	Tıklama ping istekleri için temel URL. instrumentationSuffix Tam ping URL'sini oluşturmak için sonuç öğesinden bir değer ekleyin. Yalnızca EnableInstrumentationPing profil bayrağına sahip uygulamalar için sunulur. Not: Kullanıcı tıklamaları URL yeniden yönlendirmesi kullanılarak da günlüğe kaydedilebilir. Yeniden yönlendirme etkinleştirildiğinde, Kullanıcı tıklamalarını günlüğe kaydetmek için hiçbir eylem gerekmez ve instrumentationClickBase yanıta dahil edilmeyecektir. Kurulum yönergeleri için İzleme kılavuzuna bakın.
instrumentationCitationBase	string	LLM günlük ping istekleri için temel URL. Tam ping URL'sini oluşturmak için bir VERİ yükü ekleyin. Yalnızca EnableInstrumentationPing profil bayrağına sahip uygulamalar için sunulur.
traceId	string	Hata ayıklama için izleme 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.

webResult

Field	Tür	Description
title	string	Web sayfasının başlığı.
url	string	Web sayfasının kaynak URL'si. URL yeniden yönlendirmesi etkinleştirilmiş Çin kullanıcıları için, bu alan bunun yerine ile aynı yeniden yönlendirme URL'sini clickUrliçerir.
domain	string	Sonucun hedef ana bilgisayarı. Yalnızca URL yeniden yönlendirmesi etkinleştirilmiş Çin kullanıcıları için döndürülür.
içerik	string	Web sayfasının ayrıntılı içeriği (diğer adıyla topraklama).
crawledAt	string	Web sayfasının son gezinme tarihi, ISO8601 biçimi izler.
lastUpdatedAt	string	Web sayfasının son güncelleştirme tarihi, ISO8601 biçimi izler.
language	string	Web sayfasının dili ISO 639-1 dil kodunu kullanır.
isAdult	boolean	Sonucun yetişkinlere yönelik içerik içerip içermediğini gösterir.
clickUrl	string	Tıklamayı Bing'e yönlendiren URL'yi yeniden yönlendirin. Yalnızca tıklama yeniden yönlendirme etkinleştirildiğinde bulunur.
instrumentationSuffix	string	Bu sonuç öğesi için izleme ping URL'si tabanına eklenecek son ek. Hem izleme ping URL'si clickUrl hem de yeniden yönlendirme için K değeri olarak kullanılır. İzleme ping'i etkinleştirildiğinde bulunur.
contentTier	string	İçerik kaynağının ticari erişim özelliklerini açıklayan sonucun içerik katmanı. Olası değerler: standard (varsayılan hizmet teklifi kapsamında tüm müşteriler tarafından sağlanan standart içerik), entitled (müşterilerin doğrudan yayımcılardan lisansladığı Kendi Lisansını Getir (KLG) içeriği dahil olmak üzere mevcut müşteri lisans sözleşmeleri aracılığıyla sağlanan içerik ve kendi sözleşme düzenlemeleri aracılığıyla erişim sağlama), premium (standart teklifin ötesinde ek değer sağlayan ve faturalamaya tabi olan premium içerik).

Note

ve lastUpdatedAt alanlarının crawledAt değerleri isteğe bağlıdır. Yani, kapsamları 100%değildir. Bu alanlar için boş değerler görebilirsiniz.

Hata Kodları

Durum Kodu	Hata Kategorisi	Description	Olası Nedenler
200	Success	İstek başarılı oldu.	-
400	Hatalı İstek	Geçersiz istek parametreleri.	Eksik gerekli alanlar, geçersiz parametre değerleri, hatalı biçimlendirilmiş JSON
401	Yetkisiz	Kimlik doğrulaması başarısız oldu veya eksik.	Geçersiz API anahtarı, eksik x-apikey üst bilgisi
403	Yasak	Geçerli kimlik bilgileri ancak izinler yetersiz.	API anahtarında gerekli izinler yok
410	Gitti	HTTPS gereklidir.	İSTEK HTTPS yerine HTTP üzerinden yapıldı
415	Desteklenmeyen Medya Türü	İçerik türü desteklenmiyor.	Eksik veya yanlış içerik türü üst bilgisi
429	Çok Fazla İstek Var	Hız sınırı aşıldı.	Zaman penceresinde çok fazla istek var
500	İç Sunucu Hatası	Beklenmeyen sunucu hatası.	Geçici sunucu sorunu
503	Hizmet Kullanılamıyor	Hizmet geçici olarak kullanılamıyor.	Bakım veya geçici kesinti
504	Ağ Geçidi Zaman Aşımı	İstek zaman aşımına uğradı.	Yukarı akış hizmeti zaman aşımı

Ayrıntılı hata işleme kılavuzu için bkz. Hata İşleme.

---

Ayrıca bkz:Videolar Arama | Haber | Arama | Görüntüleri Arama | MCP