Kapsam yönetimi REST API başvurusu

Microsoft Web IQ Müşteri Yönetimi API'si, bir Web IQ faturalama hesabı için adlandırılmış arama kapsamları oluşturur, okur, güncelleştirir ve siler. Uçtan uca portal veya API kılavuzu için bkz. Kapsamlarla sonuçları filtreleme.

Temel URL:https://api.microsoft.ai

Koleksiyon yolu:/v1/customer/billing-accounts/{billingAccountId}/scopes

Kimlik doğrulaması ve üst bilgiler

İş yüklerinin etkin bir Microsoft Entra kimliği ve CustomerApiAccess hedef ödeme hesabında olması gerekir. ile https://api.microsoft.ai/.defaultyalnızca uygulama belirteci isteyin. Seçmek billingAccountIdiçin yetkili kaynak bulma kullanın; bir müşteri kimliğini, Azure abonelik kimliğini, Web IQ AppID'yi veya Entra uygulaması (istemci) kimliğini kullanmayın.

Header Use
Authorization: Bearer <access-token> Her yönetim isteği için gereklidir. Arama API'leri anahtarları bu çağrılar için desteklenmez.
Content-Type: application/json JSON gövdesi gönderilirken gereklidir.
Accept: application/json JSON yanıtlarını iste.
If-Match: "<current-etag>" Değiştirme, artımlı düzenlemeler ve silme için gereklidir. Okuma veya yazma kapsamından tırnak işaretleri dahil olmak üzere tüm güçlü ETag'i kopyalayın.

Operations

Aşağıdaki yollar koleksiyon yoluna göredir.

Method Yol Success Description
POST Koleksiyon yolu 201, tanım, ETag, Location Adlandırılmış bir kapsam oluşturun.
GET Koleksiyon yolu 200, meta veri sayfası Kapsam adlarını, sayıları ve zaman damgalarını seçici dizileri olmadan listeleyin.
GET /{name} 200, tanımı, ETag Hem tam seçici dizilerini hem de meta verileri okuyun.
GET /{name}/summary 200, meta veriler, ETag Seçici dizileri olmadan sayıları ve zaman damgalarını okuma.
GET /{name}/includeSites veya /{name}/excludeSites 200, site sayfası, ETag Birinci sayfa seçici listesi.
PUT /{name} 200, tanımı, ETag Her iki diziyi de değiştirin; gerektirir If-Match.
POST /{name}/includeSites:add veya /{name}/excludeSites:add 204, ETag Bir listeye seçiciler ekleyin; gerektirir If-Match.
POST /{name}/includeSites:remove veya /{name}/excludeSites:remove 204, ETag Seçicileri bir listeden kaldırma; gerektirir If-Match.
DELETE /{name} 204 Kapsamı kalıcı olarak silme; gerektirir If-Match.

Kapsam adları, hesabın atanan kapsam koleksiyonundaki kaynakları tanımlar. Hesaptaki Web IQ AppID'leri bu koleksiyonu kullanır. Aynı koleksiyona atanan hesaplar adları, tanımları ve değişiklikleri paylaşır.

Kapsam oluşturma

POST /v1/customer/billing-accounts/<billingAccountId>/scopes HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "ProductDocs",
  "includeSites": ["example.com", "docs.example.org/products"],
  "excludeSites": ["ads.example.com"]
}
İstek alanı Required Türü Description
name Yes string Kırpmadan sonra 1-128 karakter; ASCII harfleri, basamaklar, ., _ve -. Koleksiyon içinde büyük/küçük harfe duyarlı olmayan benzersiz.
includeSites Yes stringler dizisi Dahil edilen seçiciler. Tüm dışlanmayan kaynaklara izin veren kasıtlı olarak boş ekleme için kullanın [] .
excludeSites Yes stringler dizisi Dışlanan seçiciler. Dışlama, özelliğe bakılmaksızın dahil edilmeye göre önceliklidir.

Her iki dizi de mevcut olmalıdır. Özelliğin veya göndermenin null atlanması ile []eşdeğer değildir.

HTTP 201 Created , aşağıdaki normalleştirilmiş tanımı ve yanıt üst bilgilerini döndürür. Oluşturma bir güncelleştirme veya yeniden adlandırma değildir: yinelenen büyük/küçük harfe duyarsız ad döndürür 409 Conflict.

Yanıt üst bilgisi Description
ETag Güçlü, tırnak içinde yazma-eşzamanlılık belirteci. Gelecekteki If-Match istekler için tam değeri koruyun. Kullanıma hazır olma veya sunum sürümü belirteci değil.
Location İstenen faturalama hesabı yolunda oluşturulan kapsamın kök göreli URI'si.

Cevap alanları

Tam tanım aşağıdaki tüm alanları içerir. Meta veri yanıtı ve excludeSitesdeğerlerini atlarincludeSites.

Alan Türü Description
billingAccountId dize (UUID) İstekte kullanılan ödeme hesabı.
name string Görünüm büyük/küçük harf korumasının korunduğu kapsam adı. Arama büyük/küçük harfe duyarlı değildir.
includeSites stringler dizisi Tamamlanmış, normalleştirilmiş, eklenen seçiciler.
excludeSites stringler dizisi Tamamlanmış, normalleştirilmiş dışlanmış seçiciler.
includedSiteCount integer Normalleştirilmiş benzersiz dahil seçicilerin sayısı.
excludedSiteCount integer Normalleştirilmiş benzersiz dışlanan seçicilerin sayısı.
createdAt string (tarih-saat) UTC'de oluşturma zamanı.
updatedAt string (tarih-saat) UTC'deki son güncelleştirme zamanı.

Kapsamları listeleme ve okuma

Tanımın tamamı ve geçerli ETag'i için kullanın GET /v1/customer/billing-accounts/{billingAccountId}/scopes/{name} . Salt okunur meta verilerine ve sayılarına ekleyin /summary .

Kapsamları listelemek için kullanın GET /v1/customer/billing-accounts/{billingAccountId}/scopes?pageSize=50 . Yanıt, içindeki items meta veri nesnelerini ve isteğe bağlı nextContinuationTokenbir öğesini içerir.

Sorgu parametresi Şunlar için geçerlidir: Değerler
pageSize Kapsam listesi 1-100; varsayılan 50.
pageSize Dahil edilen veya dışlanan seçici listesi 1-1,000; varsayılan 100.
continuationToken İki liste türü de Bu listenin önceki sayfasından opak belirteç. Değiştirmeden geçirin ve HTTP istemcisi URL'sinin kodlamasına izin verin.

veya olmayana nullkadar nextContinuationToken devam edin. Kapsam meta verileri, eşzamanlı düzenlemeler sırasında garantili bir anlık görüntü olarak değil normalleştirilmiş ad sırasına göre listelenir.

Sayfa seçicileri için veya GET .../scopes/{name}/excludeSitesöğesini arayınGET .../scopes/{name}/includeSites. Her yanıt , , totalCountnextContinuationTokenve bir ETag üst bilgisi içerirsites. Seçici sayfaları kurallı seçici sırasını izler. Belirteçleri aynı kapsam ve listeye sahip tutun. Bir düzenleme seçici belirtecini eski yaparsa, istek döndürür 412; kısmi numaralandırmayı atıp ilk sayfadan yeniden başlatın.

Kapsamı güncelleştirme veya silme

PUT her iki tam diziyi de değiştirir ve kapsamı yeniden adlandırmaz:

PUT /v1/customer/billing-accounts/<billingAccountId>/scopes/ProductDocs HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json
If-Match: "<current-etag>"

{
  "includeSites": ["example.com"],
  "excludeSites": ["ads.example.com", "example.com/archive"]
}

Bir listeyi diğerini değiştirmeden değiştirmek için karşılık gelen :add veya :remove yolu bir sites diziyle kullanın:

POST /v1/customer/billing-accounts/<billingAccountId>/scopes/ProductDocs/excludeSites:add HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json
If-Match: "<current-etag>"

{
  "sites": ["example.com/archive"]
}

1-10.000 gönderilen girdi sağlayın. Sonuçta elde edilen listenin benzersiz seçici ve tanım boyutu sınırlarını karşılaması gerekir. Zaten mevcut bir kurallı seçici eklemek veya eksik seçiciyi kaldırmak no-op. Tamamen no-op bir istek ETag'i korur. Başarılı artımlı mutasyonlar geçerli ETag ile geri döner 204 ve JSON gövdesi yoktur.

Kapsamı kalıcı olarak silmek için ile kullanın DELETE .../scopes/{name}If-Match . Önce arayanlardan bağımlılıkları kaldırın. Geçici silme veya geri yükleme uç noktası yoktur ve silme işlemi zaman uyumsuz olarak yayılır. Paylaşılan koleksiyon için silme işlemi, atanan tüm hesapları etkiler.

Eşzamanlılık ve belirsiz sonuçlar

Değiştirme, artımlı düzenlemeler ve silme işlemleri için geçerli güçlü ETag gerekir. Tırnak işaretlerini kaldırmayın, zaman damgalarından oluşturmayın veya zayıf, joker karakter veya birden çok etiket kullanmayın.

üzerinde 412 Precondition Faileden son tanımı okuyun, hedeflenen değişikliği diğer yazarların değişiklikleriyle mutabık bırakın ve en son ETag ile yeniden deneyin. En son tanımın üzerine körü körüne yazmayın. 428 Precondition Required ortalamalar If-Match eksikti.

Yazma zaman aşımına uğradıysa veya bağlantı düşerse, yeniden denemeden önce kaynağı okuyun. Oluşturma işlemi zaman aşımından önce başarılı olmuş ve yeniden deneme dönüşünü 409yapmış olabilir; düzenleme ETag'i değiştirerek yeniden deneme dönüşünü 412yapmış olabilir. Silmeyi denetlerken, orijinal devamsızlığı yetkilendirme hatasından ayırt edin.

Sınırlar ve seçici doğrulaması

Kısıtlama Sınır veya davranış
Name Kırpmadan sonra 1-128 karakter; ASCII harfleri, basamaklar, ., _ve -.
Her seçici listesi 10.000'e kadar normalleştirilmiş benzersiz seçici. Dizi başına en fazla 10.000 ayrı girdi gönderin.
Her seçici Kırpmadan önce ve normalleştirmeden sonra en fazla 2.048 karakter.
Yol derinliği Seçici uzunluğuna ve birleşik tanım boyutuna bağlı olarak ayrı alt dizin veya segment sayısı sınırı yoktur.
Birleşik tanım Hem listeler hem de meta veriler dahil olmak üzere serileştirilmiş sunum tanımından tahmin edilen varsayılan 3.670.016 bayt (3,5 MiB). Ham HTTP istek gövdesi boyutu değil.
Artımlı gövde ekleme/kaldırma içinde 1-10.000 girdi sitesgönderildi.

Koleksiyonun kapsam sayısı sınırı da vardır. 409 tükenmiş kapasiteyi ve yinelenen bir adı gösterebilir; hatasını ve mevcut envanteri denetleyin. Hesabınızın etkin kapasitesi için Web IQ Desteği'ne başvurun.

Desteklenen seçiciler DNS etki alanlarını (example.com ve tüm alt etki alanlarını), IPv4 konaklarını (192.0.2.10), yol ön eklerini (example.com/products/guides söz konusu konak için yol kesimi sınırlarında) ve tam HTTPS URL'lerini (https://example.com/products/guide) içerir. Düzen eklemek, yol ön eklerini tam URL'ye değiştirir.

Joker karakterler, açık bağlantı noktaları, sorgu dizeleri, parçalar, kullanıcı bilgileri, IPv6, nokta kesimleri ve kodlanmış yol ayırıcıları reddedilir. Ham ASCII olmayan yol karakterleri utf-8 yüzde kodlanmış olmalıdır.

Normalleştirme, çevre boşluğu kısaltır, konakları küçük harfe çevirir, yol büyük/küçük harflerini korur, kurallı seçicileri sıralar ve her listeyi bağımsız olarak yinelenenleri kaldırır. Her iki listede de bir girdi görüntülenebilir; dışlama her zaman kazanır. Boş ekleme, dışlanmayan tüm kaynaklara izin verir. Her iki dizi de boş, kapsamın kendisinin site kısıtlaması uygulamaması anlamına gelir.

Durum kodları ve hatalar

Yönetim hataları , v3 arama hatası yanıtından farklı bir sözleşme kullanır.

Statü Meaning Action
400 Geçersiz ad, gövde, seçiciler, sayfalandırma, tanım boyutu veya If-Match biçim. Girişi düzeltin; değiştirmeden yeniden denemeyin.
401 Eksik veya geçersiz kimlik doğrulaması. Belirteç süre sonunu ve https://api.microsoft.ai/.default belirteç isteği kapsamını denetleyin.
403 Sorumlu veya hesap yetkilendirmesi reddedildi. İş yükünün etkin kimliğini ve CustomerApiAccess hesapta doğrulayın.
404 İstenen kapsam veya ödeme hesabı bulunamadı. Hesabı ve adı denetleyin. Yetkilendirme, varlığı açıklanmadan önce isteği reddedebilir.
409 Yinelenen ad veya tükenmiş koleksiyon kapasitesi. Mevcut envanteri ve hata ayrıntılarını okuyun; oluşturma işlemini körü körüne yeniden denemeyin.
412 Eski ETag veya eski seçici-sayfa belirteci. Düzenlemeyi yeniden okuyun ve uzlaştırın veya seçici sayfalandırmayı yeniden başlatın.
428 Gerekli If-Match eksik. Kaynağı okuyun ve geçerli teklif edilen güçlü ETag'ini gönderin.
500 Hizmet veya bağımlılık hatası. Okumalar için sınırlanmış yeniden denemeler kullanın; önce belirsiz yazmaları mutabık kıl.

Kapsam doğrulama, bulunamadı, çakışma ve eşzamanlılık hataları şu JSON şeklini kullanır:

{
  "code": "NotFound",
  "message": "The requested scope was not found."
}

Kararlı code değerler , , NotFound, ConflictPreconditionFailedve PreconditionRequireddeğerlerini içerirInvalidRequest. Bir subCode de mevcut olabilir. Tanılamada messagedeğil, HTTP durumunda codedallanır ve bilinmeyen kodlarla alanları kabul edilir. Hatalı biçimlendirilmiş veya geçersiz istek gövdeleri bunun yerine doğrulama ayrıntılarını döndürebilir application/problem+json . 401 ve 403 gövdesi yoktur; bağımlılık hataları farklı bir şekil kullanabilir.

Arama yayma

Başarılı bir yönetim yazma veya okuma işlemi, aramada en son tanımın etkin olduğunu kanıtlamaz. Yayılma eşzamansızdır. Tam küresel yayma genellikle yaklaşık 10 dakika sürer, ancak bazı durumlarda 30 dakikaya kadar sürebilir. Şu anda yayma SLA'sı yoktur ve bu zamanlamalar garanti edilmemektedir. Henüz hazır olma uç noktası veya kapsam sürümü oluşturma yok. Yazma ETag'i ve çalışma zamanı scopeApplied: true , o anda sunulan sürümü tanımlamaz.

Hazırlık denetimleri ve yeni ad değiştirme stratejisi için bkz. Kullanmadan önce kapsamı doğrulama.