Fark sorgu | Grafik API'si kavramları
Uygulandığı öğe: Graph API | Azure Active Directory
Bu konu, Azure AD Graph API fark sorgu özelliğini açıklar. İki ardışık istekleri arasındaki süre boyunca belirtilen varlıklara yapılan tüm değişiklikler fark sorgu isteği döndürür. Örneğin, bir saat sonra önceki fark sorgu isteği isteği fark bir sorgu yaparsanız, yalnızca bu saatte yapılan değişiklikler döndürülür. Bir uygulamanın verilerinin ile eşitleme Kiracı dizin verilerini depolar bu işlev özellikle yararlıdır.
Bir kiracının dizini için değişim sorgu isteği yapmak için uygulamanızın Kiracı tarafından yetkilendirilmelidir. Daha fazla bilgi için bkz: Azure Active Directory Tümleştirme uygulamalarla.
Önemli
Kullanmanız önerilir Microsoft Graph Azure Active Directory kaynaklara erişmek için Azure AD Graph API yerine. Geliştirme çalışmalarımızı artık Microsoft Graph yoğunlaşmıştır ve herhangi bir geliştirme için Azure AD Graph API planlanmaktadır. Senaryolar için Azure AD Graph API hala uygun olabilir, çok sınırlı sayıda vardır; Daha fazla bilgi için bkz: Microsoft Graph veya Azure AD grafik Office Geliştirici Merkezi blog postasına.
Fark sorgu isteği
Bu bölümde fark sorgu isteği açıklanmaktadır. Tüm istekleri aşağıdaki bileşenleri gerektirir:
Grafik uç noktası Kiracı ve geçerli sorgu dizesi parametreleri için de dahil olmak üzere geçerli istek URL'si.
Azure Active Directory tarafından verilen geçerli erişim belirteçle birlikte bir authorization üstbilgisi. Grafik API'si için kimlik doğrulaması ile ilgili daha fazla bilgi için bkz: Azure AD için kimlik doğrulama senaryoları.
Fark sorgu istek URL'si
Aşağıdaki değişiklikleri sorgu isteği için URL biçimi gösterir; köşeli ayraçlar [] isteğe bağlı öğeleri gösterir.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
URL sorgu dizesi parametreleri anahtar-değer çiftleri olarak ifade edilen bir dizi arkasından hiyerarşik bir segment oluşur.
URL: Hiyerarşik kesimleri
| Kesim | Description |
|---|---|
| tenantId | Sorgu karşı yürütülmesi gereken Kiracı benzersiz tanımlayıcısı. Bu genellikle doğrulanmış etki alanlarından biri olur (verifiedDomains özelliği) Kiracı ancak kiracının nesne kimliği olabilir (objectID özelliği). Duyarlı değildir. |
| resourceSet | Kiracı kaynaklarına karşı bu sorgunun yürütülmesi gereken belirli kümesi. Hangi kaynaklara sorgu yanıtta döndürülen belirler. Desteklenen değerler: "directoryObjects", "kullanıcılar", "Kişiler" veya "grupları". Değerleri büyük/küçük harfe duyarlıdır. |
URL: Sorgu dizesi parametreleri
| Parametre | Description |
|---|---|
| api-sürümü | İstek karşı verildiği grafik API'si sürümünü belirtir. Gerekli. Sürüm 1.5 ile başlayarak, değer sayısal sürüm numarası ifade edilir; Örneğin, API sürümü 1.5 =. Önceki sürümler için, YYYY-AA-GG biçiminde bir dize değeridir; Örneğin, API sürümü 2013-04-05 =. (Kullanımını değiştirir x-ms-dirapi-data-contract-version grafik API'si önizleme sürümünü üstbilgisinde.) |
| deltaLink | Belirteç döndürdü ya da deltaLink özelliği veya nextLink son yanıt özelliği. Gerekli, ancak ilk isteği boş olacaktır. (Değiştirir skipToken sorgu dizesi parametresi grafik API'si Önizleme sürümünde.) |
| $filter | Hangi varlık türleri yanıt olarak eklenmesi gerektiğini gösterir. İsteğe bağlı. Desteklenen varlık türleri şunlardır: kullanıcı, Grup ve başvurun. Yalnızca geçerli olduğunda, ltresourceSet & gt olan "directoryObjects"; Aksi takdirde & ltresourceSet & gt filtresi geçersiz kılar. Örneğin, varsa & ltresourceSet & gt "kullanıcılar" olduğundan ve $filter parametresi de belirtilen yalnızca değişiklikler kullanıcılar için filtre değer'de belirtilen bağımsız olarak döndürülür. Varsa & ltresourceSet & gt "directoryObjects" olduğundan ve $filter olan belirtilmezse, tüm desteklenen varlık türleri (kullanıcı, Grup ve ilgili kişi) için değişiklikleri döndürülür. Tek bir varlık türünü belirtmek için aşağıdakilerden birini kullanın:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Değiştirir objectScope sorgu dizesi parametresi grafik API'si Önizleme sürümünde.) Önemli sürüm 1.5, grafik API'si ile başlayan ad alanı için Microsoft.DirectoryServices Microsoft.WindowsAzure.ActiveDirectory değiştirilir. Grafik API'si önceki sürümlerinde, önceki ad alanı kullanmaya devam etmek; Örneğin, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Hangi özelliklerin yanıta dahil belirtir. Varsa * $select ^ belirtilmezse, tüm özellikler dahil. Tam olarak nitelenmiş ya da nitelikli olmayan özellikler belirtilebilir. Birden çok özellik virgüller ile sınırlandırılmıştır.
|
Not: Sorgu dizesinde anahtar-değer çiftleri büyük/küçük harfe duyarlıdır, ancak bunların sırası önemli değildir.
En basit fark sorgunun bir örnek verilmiştir. Bu ilk eşitleme sırasında kullanılır.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Bir sonraki istek örneği verilmiştir.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Fark sorgu yanıtları
Bu bölümde bir fark sorgu isteği yapıldığında, döndürülen bir fark sorgu yanıtı içeriğini açıklar. Aşağıdaki listede, bir yanıt içeriğini açıklanmaktadır:
200 sıfıra DirectoryObject varlıklar, her biri belirli bir değişiklik içeren kullanıcı, grup, veya kişi nesnesi.
3000 sıfıra DirectoryLinkChange varlıklar, her biri belirli bir değişiklik içeren üye veya Yöneticisi bağlantı.
Ya da bir deltaLink veya nextLink özelliği. Her iki durumda da, dizinde oluşmuş kalan değişikliklerini göre istemciye döndürülen dizin değişikliklerini kümesi ile ilgili durum bilgisini katıştırır büyük küçük harfe duyarlı, URL kodlanmış bir dize değeri olduğu. Bu dize (veya belirteç) dahil edilmesi gereken deltaLink sorgu dizesi parametresi sonraki fark sorgu isteği.
Varsa deltaLink özelliği döndürülür, bir uygulamanın bu yanıt sonra eşitlemek sol daha fazla dizin değişiklik yoktur. Uygulama sonraki fark sorgu isteği vermek için kendi gereksinimlerine göre önceden belirlenmiş bir süre bekleyebilirsiniz.
Varsa nextLink özelliği döndürülür, sonra bu yanıt eşitlemek uygulamanın kalan dizin değişiklik yoktur. Uygulamanın kendi erken kolaylık sonraki fark sorgu isteğiyle yayımlamalısınız.
Yanıtları her zaman JSON biçiminde döndürülür.
Fark sorgu kullanmayla ilgili konular
Aşağıdaki listede ile ilgili önemli noktalar fark sorgu kullanan uygulamaları vurgular:
Değişiklikler fark sorgu tarafından döndürülen yanıt aynı anda dizin nesneleri durumunu temsil eder. Uygulamanız bu değişiklikleri yeniden yürütme için işlem günlüklerini olarak kabul gerekir.
Değişiklikleri gerçekleşen sırada görünür. Nesne birden çok kez güncelleştirilmiş olsa bile en son değiştirilen nesneler son görüntülenir. İstemci değişiklikleri alındığında sıralarına göre de etkilenmez. Sonuç olarak, nasıl başlangıçta dizinde oluşma için karşılaştırıldığında değişikliklerin bozuk sunulması için mümkündür.
Uygulamanız aynı değişikliği sonraki yanıtları görüntülendiğinde oluşan yürütmelerini için hazırlanması gerekir. Bunlar, fark sorgu yürütmelerini azaltmak için bir en iyi çaba olmasını sağlarken hala mümkündür.
Uygulamanızı farkında olmayan bir nesne için bir silme değişikliği işlemek için hazırlanması gerekir.
Fark sorgu henüz diğer yanıtlar tarafından döndürülen olmayan bir kaynak veya hedef nesnesi için bir bağlantı geri dönebilirsiniz.
Bkz: ek fark sorgu özellikleri bölümünde aşağıda performansını artırmak için sorgularınızı sınırlamak için istek üstbilgilerini kullanma hakkında daha fazla bilgi için.
İstek ve yanıt örnekleri
İlk fark sorgu isteği örneği verilmiştir:
GET https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink= HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net
Bir artımlı fark sorgu isteği bir örnek verilmiştir:
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U
HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net
Not: hem de bu örnek istekleri $filter sorgu parametresi yalnızca tanıtım amacıyla gösterilir. Filtre tüm olası hedef türleri belirttiğinden farklar için sorgu (kullanıcı, Grup ve ilgili kişi), kullanılmayabilir ve sorgu değişiklikleri tüm bu varlık türleri için varsayılan olarak döndürür.
Aşağıdaki örnek yanıt döndürülen JSON gösterir:
{
"odata.metadata": "https://graph.windows.net/contoso.com/$metadata#directoryObjects",
# This is the deltaLink to be used for the next query
"aad.deltaLink": "https://graph.windows.net/contoso.com/directoryObjects?deltaLink=XARBN7ivjcS6QIhSZDQR3OkT15SO1eeY-01BZSS0sOct6sh5oEyqOLLKRVhRmBMLHhePUF... [Truncated]",
"value": [
# User object for John Smith
{
"odata.type": "Microsoft.WindowsAzure.ActiveDirectory.User",
"objectType": "User",
"objectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
"accountEnabled": true,
"displayName": "John Smith",
"givenName": "John",
"mailNickname": "johnsmith",
"passwordPolicies": "None",
"surname": "Smith",
"usageLocation": "US",
"userPrincipalName": "johnsmith@contoso.com"
},
# Group object for IT Administrators
{
"odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Group",
"objectType": "Group",
"objectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
"description": "IT Administrators",
"displayName": "Administrators",
"mailNickname": "Administrators",
"mailEnabled": false,
"securityEnabled": true
},
# Contact object for Jane Smith
{
"odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Contact",
"objectType": "Contact",
"objectId": "d711a1f8-21cf-4dc0-834a-5583e5324c44",
"displayName": "Jane Smith",
"givenName": "Jane",
"mail": "johnsmith@contoso.com",
"mailNickname": "johnsmith",
"proxyAddresses": [
"SMTP:janesmith@fabrikam.com"
],
"surname": "Smith"
},
# Member link indicating John Smith is a member of IT Admin Group
{
"odata.type": "Microsoft.WindowsAzure.ActiveDirectory.DirectoryLinkChange",
"objectType": "DirectoryLinkChange",
"objectId": "00000000-0000-0000-0000-000000000000",
"associationType": "Member",
"sourceObjectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
"sourceObjectType": "Group",
"sourceObjectUri": "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8",
"targetObjectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
"targetObjectType": "User",
"targetObjectUri": "https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2"
}
]
}
Ek fark sorgu özellikleri
Fark sorgular artık yalnızca güncelleştirilmiş özellikleri ve bağlantıları döndürebilir – bu daha hızlı işleme ve değişiklikleri sorgu çağrıları için azaltılmış yüklerini sağlar. Üstbilgi ayarlayarak bu seçenek etkinleştirildiğinde ocp-aad-dq-include-only-changed-properties Bu örnekte gösterildiği gibi true.
GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= furK18V1T….
HTTP /1.1
ocp-aad-dq-include-only-changed-properties : true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK
Örneğin yalnızca kullanıcı "displayName" özelliğini değişti. Döndürülen nesne şuna benzer olacaktır:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
"Şu andan itibaren" eşitlemek için değişiklikleri eşitleme Destek -isteyen özel üstbilgi belirtilebilir, bu belirteç güncel bir deltaToken sonraki sorgularında kullanılabilir yalnızca get için "Şimdi" yalnızca değişikliklerden döndürecektir. Örnek arama şöyledir:
GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= smLYT8V1T…
HTTP /1.1
ocp-aad-dq-include-only-delta-token: true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK
Yanıt içerecek deltaLink, ancak buna benzer değiştirilmiş nesneleri yoktur:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Silinmiş bir öğeyi algılama – yanıt silinmiş bir öğeyi algılamak için de kullanılabilir. Silinen nesneler ve Silinen bağlantılar "aad.isDeleted" özelliği true olarak bir değer kümesiyle belirtilir; Bu uygulamalar silinmesini daha önce oluşturulan nesneler ve bağlantılar hakkında bilgi edinebilirsiniz emin olmak gereklidir.