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.
Microsoft Web IQ'daki kapsamlar, URL'leri, siteleri ve etki alanlarını Web Araması, Haber Araması ve Otomatik sonuçlara dahil ederek veya dışlayarak grounding API isteklerinde ince ayar yapmanızı sağlar.
Geliştiriciler ve kurumsal yöneticiler, yapay zeka deneyimlerini onaylı ve tercih edilen web kaynaklarına dayandırmak için Kapsamları kullanabilir. Temel alma aramalarınızın hangi kaynakları döndürebileceğini denetlemek için URL'ler, etki alanları ve yollar için yeniden kullanılabilir ekleme ve dışlama listeleri tanımlayın.
Kapsam, ekleme ve dışlama kurallarının adlandırılmış bir yapılandırmasıdır. Ödeme hesabı için Web IQ portalında veya Müşteri Yönetimi API'sinde oluşturun, ardından Web Araması, Haber Arama veya Otomatik isteklerinizde adıyla seçin. Her iki yönetim seçeneği de aynı adlandırılmış kapsamlarla çalışır. Bu arama kapsamları Microsoft Entra OAuth izin kapsamları değildir.
Warning
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 scopeAppliedtrue olsa bile bunun dışında sonuçlar içerebilir.
İş senaryoları ve yaygın kullanım örnekleri
| Scenario | Örnek kullanım örneği | Kapsamları kullanma |
|---|---|---|
| Küratörlü araştırma | Bir araştırma asistanını, onaylı tıbbi yayınlar gibi kuruluşunuz tarafından gözden geçirilmiş kaynaklara dayandırın. | Onaylanan etki alanlarını, alt etki alanlarını veya tek tek sayfaları ekleyin. |
| Kuruluş kaynak ilkeleri | Kuruluşunuz tarafından kısıtlanan etki alanlarını Web Araması ve Haber Araması dayanak sonuçlarından hariç tutun. | Bir dışlama listesi oluşturun ve her istekte kapsamı seçin. |
| Sahip olunan sitelerde arama | Destek yardımcısını veya çalışana yönelik arama deneyimini herkese açık ürün, yardım veya şirket sitelerinizle sınırlayın. | Size ait alan adlarınızı ve ilgili belge yollarını ekleyin. |
| Seçilmiş haber izleme | Haber özetlerini seçili bir yayımcı kümesine dayandırın. | Yayımcı etki alanlarını ekleyin ve Haber Arama isteklerinde kapsamı seçin. |
Kapsamlar, seçili arama uç noktası için kullanılabilen içeriği filtreler. Eklenen bir kaynak, eşleşen içeriğin dizine eklendiğini veya döndürüldüğünü garanti etmez.
Prerequisites
- Etkin bir Web IQ ödeme hesabı.
- API ile kapsamlar oluşturmak için mevcut bir Microsoft Entra uygulaması, uygulamanın kiracı kimliği ve uygulama (istemci) kimliği ile OAuth 2.0 istemci kimlik bilgileri akışı için kimlik bilgileri gereklidir. İş yükü kimliğinin etkin olması ve hedeflenen Web IQ ödeme hesabında
CustomerApiAccesssahip olması gerekir.
Important
Arama API'lerine ve Web IQ yönetim API'sine ayrı olarak erişim verilir. Web IQ çalışma zamanı profiline bağlı çalışan bir arama API'si anahtarı veya Entra uygulaması kapsam oluşturma izni vermez. İş yükünün ayrı bir faturalama hesabı yönetim yetkisine ihtiyacı vardır.
Portal erişimini denetlemek için Kapsamlar'ı açın ve hedeflenen ödeme hesabını ve Yeni kapsam denetimini arayın. Sayfa, hesap veya oluşturma denetimi kullanılamıyorsa, hesap yöneticinizden erişiminizi denetlemesini veya Web IQ Desteği'ne başvurmasını isteyin.
Kapsamınızı adlandırıp kaynakları seçin
Başındaki ve sonundaki boşluklar kaldırıldıktan sonra en fazla 128 karakter içeren bir kapsam adı seçin. Desteklenen karakterler ASCII harfler, basamaklar, nokta (.), alt çizgi (_) ve kısa çizgidir (-). Boşluklar ve eğik çizgiler desteklenmez. Adlar kapsam koleksiyonu içinde büyük/küçük harfe duyarsız olarak benzersizdir.
Kapsamlar, bir Web IQ faturalama hesabındaki Web IQ AppID'leri arasında, bu hesaba atanmış kapsam koleksiyonu aracılığıyla paylaşılır. Bunlar her AppID için ayrı yapılandırmalar değildir. Faturalama hesapları bir koleksiyonu paylaşıyorsa, aynı kapsamları ve adları paylaşır.
- Dahil etme, sonuçları kapsamın dahil etme listesindeki en az bir girdiye uyan kaynaklarla sınırlar. Liste boşsa, dışlanmayan tüm kaynaklar uygun sayılır.
- Dışlama , kapsamın dışlanan listesindeki herhangi bir girişle eşleşen sonuçları, bir ekleme kuralıyla da eşleşse bile kaldırır. Dışlama her zaman önceliklidir.
Etki alanlarını, URL yollarını veya tek tek web sayfalarını dahil edebilir veya hariç tutabilirsiniz. Her bir girişe seçici denir:
| Selector | Example | Eşleşmeler |
|---|---|---|
| Domain | example.com |
Etki alanı ve onun altındaki tüm alt etki alanları |
| Dizin ön eki | docs.example.org/products |
Belirtilen yol ve bu konak üzerindeki alt yolları, ancak gibi yollar değil /products-old |
| Tam URL adresi | https://docs.example.org/products/guide |
Bu tam HTTPS URL'si, yolun altındaki her sayfa değil |
https:// eklemek, seçicinin bir etki alanı veya yol ön eki yerine tam bir URL ile eşleşmesini sağlar.
*.example.com gibi joker karakterler, açıkça belirtilen bağlantı noktaları, sorgu dizeleri ve parçalar desteklenmez. Yoldaki büyük/küçük harf kullanımı korunur. Adlandırılmış kapsam seçicilerinin alt dizin derinliğinde ayrı bir sınırı yoktur, ancak kırpmadan önce ve normalleştirmeden sonra her seçicinin 2.048 karaktere sığması gerekir.
API girdileri normalleştirir, sıralar ve yinelenenleri kaldırıyor. Kabul edilen seçici, eşleşen içeriğin dizine eklendiğini veya döndürüldüğünü garanti etmez.
Portalda bir kapsam oluşturun
- Web IQ portalında Kapsamlar'ı açın.
- Hedeflenen Faturalama hesabını seçin.
-
Yeni kapsamı seçin.
Yeni kapsam oluştur bölümünde,
ProductDocsgirin, örneğin ve kapsamı oluşturun. - Dahil etmek üzere kaynak eklemek için kapsam ayrıntıları sayfasında Siteler ekle seçeneğini Dahil edilen sekmesinde kullanın.
Excluded sekmesinde, örneğin
ads.example.comgibi dışlanacak kaynakları eklemek için aynı düğmeyi kullanın. - Her iki listeyi de gözden geçirin, Yayımla'yı seçin ve Değişiklikler yayımlansın mı? ifadesini onaylayın.
Yayımladıktan sonra aramaya yayma işlemi genellikle yaklaşık 10 dakika sürer, ancak bazı durumlarda 30 dakikaya kadar sürebilir. Uygulamanızda bu kapsama güvenmeden önce kapsamı doğrulayın.
Arama isteklerinde kapsamı seçin
Çalışma zamanı arama kimlik doğrulamasını ayrı olarak yapılandırın. Seçilen Web IQ uygulama profili, koleksiyonu kapsamınızı içeren Web IQ ödeme hesabına ait olmalıdır.
POST https://api.microsoft.ai/v3/search/news, POST https://api.microsoft.ai/v3/auto veya POST https://api.microsoft.ai/v3/search/web için JSON istek gövdesinde aşağıdaki isteğe bağlı alanları ayarlayın. Üç uç nokta da aynı adlandırılmış kapsam ayarlarını kullanır.
| Parametre | Type | Behavior |
|---|---|---|
scopeName |
Dize | Mevcut bir kapsamın adı, örneğin ProductDocs. İçerme ve dışlama kuralları, isteğin sonuçlarını filtreler. 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 scopeApplied, true olsa bile bunun dışında sonuçlar içerebilir. Belirtilmezse veya null belirtilmezse adlandırılmış kapsam istenilmez. |
failOnMissingScope |
boolean |
Varsayılan değer true’dır; atlandığında veya null olduğunda da böyledir.
true olduğunda, bildirilen bir kapsam-uygulama hatası kapsamsız sonuçlar yerine bir hata döndürür.
false olduğunda, kapsam uygulanamazsa arama kapsam olmadan devam edebilir.
false yalnızca kapsamsız sonuçlar kabul edilebilirse kullanın.
scopeName olmadan hiçbir etkisi yoktur. |
Aşağıdaki örneklerde ayrı olarak yapılandırılmış bir çalışma zamanı API anahtarı kullanın.
Web Araması sonuçlarını filtreleme
ProductDocs tarafından izin verilen web sayfalarını aramak için şunu gönderin:
POST /v3/search/web HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json
{
"query": "product setup guide",
"scopeName": "ProductDocs",
"failOnMissingScope": true,
"maxResults": 10,
"contentFormat": "passage",
"maxLength": 3000
}
Haber Arama sonuçlarını filtreleme
Aynı kapsamda izin verilen haber makalelerini aramak için News Search endpoint'ini kullanın. Dizine eklenmiş haber içeriğine sahip dahil edilen kaynakları seçin; dahil edilen bir web sayfası, Haber Arama aracılığıyla kullanılabilir olmayabilir.
POST /v3/search/news HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json
{
"query": "product announcements",
"scopeName": "ProductDocs",
"failOnMissingScope": true,
"maxResults": 10,
"contentFormat": "passage",
"maxLength": 3000
}
Otomatik sonuçları filtrele
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 scopeAppliedtrue olduğunda bile bunun dışında sonuçlar içerebilir. Yalnızca kapsam dahilindeki Web ve Haber kanıtı istiyorsanız responseFilter: ["web", "news"] ekleyin:
POST /v3/auto HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json
{
"query": "product setup guide",
"scopeName": "ProductDocs",
"failOnMissingScope": true,
"mode": "lite",
"responseFilter": ["web", "news"]
}
Sonuçları yorumlama
Web Araması sonuçları webResults içinde döndürür, Haber Araması sonuçları newsResults içinde döndürür ve Otomatik, kanıt öğelerini results içinde döndürür (AutoEvidenceResponse). Geçerli bir kapsam, örneğin hem sorgu hem de kapsamın kurallarıyla eşleşen dizine alınmış içerik olmadığında eşleşen sonuç döndüremez.
Varsayılan olan failOnMissingScope: true ile, bildirilen bir kapsam-uygulama hatası kapsamsız sonuçlar yerine bir hata döndürür. Doğrulanmış bir eksik kapsam HTTP 400 (HandlerInvalidInput) döndürür; diğer kapsam-uygulama hataları HTTP 500 (ScopeFailedToApply) döndürür. Kurtarma kılavuzu için bkz. adlandırılmış kapsam hataları .
failOnMissingScope öğesini false olarak ayarlarsanız ve kapsam bulunamazsa, arama kapsam olmadan dizinin tamamına karşı çalışır ve yanıt "scopeApplied": false içerir. Ad yanlış olduğunda veya kapsam henüz isteği işleyen bölüme veya çoğaltmaya yayılmadığında bu durum oluşabilir.
İstenen kapsam bulunduğunda ve uygulandığında, yanıt failOnMissingScope öğesini içerir; false"scopeApplied": true olsa bile. Bu, en son tanımının kullanıldığını veya değişikliğin her bölüme veya çoğaltmaya ulaştığını değil, bu istek için kapsamın uygulanmasını onaylar. Hiçbir uygulama sonucu bildirilmezse yanıt scopeApplied öğesini atlar; eksik bir özelliği kapsamın uygulandığına dair bir kanıt olarak değerlendirmeyin.
scopeName öğesini atlarsanız veya bunu null olarak ayarlarsanız, adlandırılmış kapsam istenmez ve failOnMissingScope hiçbir etkisi olmaz. Adlandırılmış kapsamı olmayan istekler için, false öğesinin her zaman scopeApplied değerine sahip olarak mevcut olmasını beklemeyin.
Yalnızca uygulamanız kapsamsız sonuçları kabul edebilir ve yanıtı iade scopeApplied edebilirse kullanınfalse. Kapsam gerektiğinde, bunu kaldıran ve kısıtlanmamış bir isteği yeniden denenen bir geri dönüş uygulamayın. İstek parametreleri ve yanıt alanları için Web Araması, Haber Araması ve Otomatik referanslarına bakın.
API ile kapsam oluşturma
Tüm yönetim istekleri, ile başlayan /v1/customer/yollarda kullanılırhttps://api.microsoft.ai. Örneklerde <access-token> ve <billingAccountId> değerlerini hedeflenen hesap kimliği ve yalnızca uygulamaya özel erişim belirteci ile değiştirin.
Yetkili kaynaklar başvurusu ve kapsam yönetimi başvurusu, uç nokta sözleşmelerini açıklar.
Uygulamaya yönetim API erişimi verin
Ödeme hesabı veya müşteri yöneticisi erişim verir:
- Mevcut bir Microsoft Entra uygulama kaydını kullanın veya Azure portalına bir uygulama kaydedin.
- Web IQ portalında Hesap ayarlarını açın.
- Hedeflenen ödeme hesabını seçin.
- Yönetim API'sine erişim bölümünde Bir Entra uygulamasına erişim izni ver'i seçin.
- Bu ödeme hesabına bir Entra uygulamasına erişim verme iletişim kutusunda ödeme hesabı adını ve kimliğini onaylayın. Uygulamanın Kiracı Kimliği ve Uygulama (istemci) kimliğini ve gerekli Görünen ad için boş olmayan bir değer girin.
- Bu uygulamaya yönetim API'sine erişim ver'i ve ardından Erişim ver'i seçin.
Erişim verilmesi, mevcut bir kimliği yetkiler. Bir Entra uygulaması, gizli dizi, sertifika veya arama API'si anahtarı oluşturmaz. Bu yetkilendirme seçilen ödeme hesabına uygulanır.
İzin, CustomerApiAccess rolünü atar. Bu yalnızca kapsamlar veya salt okunur bir izin değildir: hesap keşfi, kapsam okuma ve yazma işlemleri ile çalışma zamanı profili Entra ID yönetimine izin verir. Uygulamanın diğer uygulamalara erişim izni vermesine izin vermez. Verme işlemini bu yönetim özelliklerine ihtiyaç duyan uygulamalarla sınırlayın.
Yalnızca uygulama belirteci alma
uygulamanızın mevcut kimlik bilgilerini ve istemci kimlik bilgileri akışını kullanarak Microsoft Entra erişim belirteci isteyin:
| Setting | Değer |
|---|---|
| Yetkili | https://login.microsoftonline.com/<tenant-id> |
| Belirteç isteği kapsamı | https://api.microsoft.ai/.default |
Oluşturduğunuz arama kapsamının adını değil, tam .default kapsamı kullanın. Belirteci her yönetim isteğinde gönderin:
Authorization: Bearer <access-token>
Bu yönetim çağrıları için arama API'si anahtarı kullanmayın. Erişim belirteçlerini ve uygulama kimlik bilgilerini kaynak denetimi ve tanılama raporlarının dışında tutun.
Ödeme hesabını keşfedin
Yalnızca uygulama belirtecinizle GET https://api.microsoft.ai/v1/customer/authorized-resources arayın. Oluşturma isteği için istenen hesabın billingAccounts[].billingAccountId öğesini seçin; ilk hesabı otomatik olarak seçmeyin.
Yanıt şeması, kimlik tanımları ve izin alanı yorumlaması için authorized-resources referansını kullanın.
Oluşturma isteğini gönderin
Seçili ödeme hesabı kimliğini kullanarak, kapsam adınız ve kurallarınızla POST /v1/customer/billing-accounts/{billingAccountId}/scopes gönderin. Örneğin:
{
"name": "ProductDocs",
"includeSites": ["example.com", "docs.example.org/products"],
"excludeSites": ["ads.example.com"]
}
Her iki diziyi de sağlayın; kasıtlı olarak boş bir liste için [] kullanın.
201 Created üzerinde, daha sonraki değişiklikler için döndürülen tanımı ve ETag'i kaydedin.
Üst bilgiler, doğrulama kuralları ve yanıt ayrıntıları için create-scope sözleşmesine bakın. Yeni bir kapsam oluşturmak yerine mevcut bir kapsamda değişiklik yapmak için güncelleştirme işlemlerini kullanın.
Kullanmadan önce kapsamı doğrulayın
- Kaydedilen kapsamı okuyun ve kurallarının hedeflenen kaynaklarınızla eşleşip eşleşmediğini onaylayın.
-
ile temsili
failOnMissingScope: trueçalıştırın. Bağımlı trafiği etkinleştirmeden önce dahil edilen ve hariç tutulan durumları denetleyin.
Important
Yayılma genellikle yaklaşık 10 dakika sürer, ancak bazı durumlarda 30 dakikaya kadar sürebilir. Yayma SLA'sı yoktur ve bu zamanlamalar garanti edilmemektedir. Başarılı bir yönetim yazma veya okuma işlemi, Publish veya scopeApplied: true en son tanımın etkin olduğunu kanıtlamaz. Hazırlık denetimi olarak geçen süreyi tek başına kullanmayın. Ayrıntılar için bkz. search propagation.
Değiştirilmiş bir tanımı yayımlama
Önceki tanımı geçici olarak kullanmak kabul edilemezse, örneğin ProductDocs-v2 gibi yeni bir ada sahip bir kapsam oluşturun. Arayanları değiştirmeden önce yukarıdaki doğrulama adımlarını tamamlayın ve arayanlar artık buna bağımlı olmayana kadar önceki kapsamı koruyun.
Bu, doğrulama sırasında eski adın anlamını değiştirmeden tutar; atomik genel geçiş sağlamaz.
Sonraki değişiklikler için eşzamanlılık korumasını koruyun
Düzenlemeden veya silmeden önce geçerli kapsamı okuyun ve alıntılanan ETag'ini If-Match içinde gönderin. Eşzamanlı düzenlemeleri mutabık tutarken veya bir yazmayı yeniden denerken eşzamanlılık ve belirsiz sonuç yönergelerini izleyin. Değişiklik geçmişine ihtiyacınız varsa, gözden geçirilmiş tanımları kendi tek doğru kaynağınızda tutun.
Oluşturma sorunlarını giderme
Hedeflenen hesap bulunamazsa yöneticiden iş yükünün kimliğini, yönetim iznini ve hesap uygunluk durumunu denetlemesini isteyin. Diğer hatalar için keşif durumu referansını veya kapsam yönetimi hata referansını kullanın.
Kalıcı hatalar için ödeme hesabı kimliği, kapsam adı, UTC'de işlem süresi, HTTP durumu ve kullanılabilir istek kimlikleri ile Web IQ Desteği'ne başvurun. Temizlenmiş beklenen ve gerçek davranışı, hiçbir zaman belirteçleri, API anahtarlarını veya uygulama kimlik bilgilerini dahil etme.