Rozdílovou dotazu | Rozhraní Graph API koncepty
Platí pro: Graph API | Azure Active Directory
Toto téma popisuje funkci rozdílové dotazu Azure AD Graph API. Žádost o rozdílové dotaz vrátí všechny změny provedené na zadané entity v době mezi dva po sobě jdoucí požadavky. Například pokud provedete rozdílové dotazu žádosti o jednu hodinu po předchozí požadavek rozdílové dotazu, bude vrácen pouze změny provedené danou dobu. Tato funkce je obzvláště užitečná při ukládání synchronizace dat adresáře klienta s dat aplikace.
Vytvořte žádost na rozdílové dotazu do adresáře klienta, aplikace musí být autorizován klientem. Další informace najdete v tématu integrace aplikací s Azure Active Directory.
Důležité
Důrazně doporučujeme použít Microsoft Graph místo Azure AD Graph API pro přístup k prostředkům Azure Active Directory. Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro Azure AD Graph API. Je velmi omezený počet scénářů, pro které Azure AD Graph API může být vhodné; Další informace najdete v tématu Microsoft Graph nebo Azure AD Graph příspěvku na blogu v Office Dev Center.
Požadavky na rozdílové dotaz
Tato část popisuje požadavky na rozdílové dotaz. Všechny požadavky vyžadují následující součásti:
Platný adrese URL požadavku, včetně grafu koncový bod pro klienta a parametrů řetězce dotazu použít.
Hlavičku autorizace včetně platný přístup tokenem vydaným službou Azure Active Directory. Další informace týkající se ověřování pro rozhraní Graph API najdete v tématu scénáře ověřování pro Azure AD.
Adresa URL požadavku rozdílové dotazu
Následující obrázek znázorňuje formát adresy URL pro rozdílové dotazu požadavek; hranaté závorky [] znamenat volitelné elementy.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
Adresa URL je tvořena hierarchické segmenty, za nímž následuje řadu parametrů řetězce dotazu, vyjádřené jako páry klíč hodnota.
Adres URL: Hierarchická segmenty
| Segment | Popis |
|---|---|
| TenantId | Jedinečný identifikátor klienta, který je třeba spustit dotaz na. To se obvykle označuje ověřených domén (verifiedDomains vlastnost) klienta, ale také může být ID objektu klienta (objectId vlastnost). Není malá a velká písmena. |
| resourceSet | Konkrétní sadu prostředků klienta, které tento dotaz, je třeba spustit na. Určuje, jaké prostředky jsou vráceny v odpovědi na dotaz. Podporovány jsou tyto hodnoty: "directoryObjects", "uživatelé", "kontakty" nebo "skupiny". Hodnoty jsou malá a velká písmena. |
Adresa URL: Parametrů řetězce dotazu
| Parametr | Popis |
|---|---|
| verze-api | Určuje verzi rozhraní Graph API, vůči které se objeví požadavek. Vyžaduje se. Od verze 1.5, hodnota je vyjádřena jako číslo verze číselné; například rozhraní api-version = 1.5. U předchozích verzí hodnota je řetězec ve formátu RRRR-MM-DD; například rozhraní api-version = 2013-04-05. (Nahrazuje použití x-ms-dirapi-data-contract-version záhlaví v verzi preview rozhraní Graph API.) |
| deltaLink | Token vrátil buď deltaLink vlastnost nebo nextLink vlastnost v poslední odpovědi. Vyžaduje, ale bude prázdný na první požadavek. (Nahrazuje skipToken parametr řetězce ve verzi preview rozhraní Graph API dotazu.) |
| $filter | Určuje, jaké typy entit by měl být zahrnuty v odpovědi. Volitelný parametr. Typy podporované entity: uživatelů, skupiny a kontakt. Pouze v případě platný & ltresourceSet & gt je "directoryObjects"; v opačném & ltresourceSet & gt přepsání filtru. Například pokud & ltresourceSet & gt je "uživatelé" a $filter rovněž je zadán parametr, pouze změny pro uživatele, bude vrácen bez ohledu na to, co je zadaný v poli Hodnota filtru. Pokud & ltresourceSet & gt je "directoryObjects" a $filter není zadaný, jsou vráceny změny pro všechny typy podporovaných entit (uživatelů, skupiny a obraťte se na). Zadejte typ jedné entity, použijte jednu z následujících akcí:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Nahrazuje objectScope parametr řetězce ve verzi preview rozhraní Graph API dotazu.) Důležité od verze 1.5, rozhraní Graph API obor názvů se změní z Microsoft.WindowsAzure.ActiveDirectory na Microsoft.DirectoryServices. Dřívějších verzích rozhraní Graph API nadále používat předchozí obor názvů; například $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Určuje vlastnosti, které by měly být zahrnuty v odpovědi. Pokud * $select ^ není zadán, jsou zahrnuty všechny vlastnosti. Vlastnosti mohou být zadané buď plně kvalifikovaný nebo nekvalifikovaným. Více vlastností jsou odděleny čárkami.
|
Poznámka:: rozlišují malá a páry klíč hodnota v řetězci dotazu, ale jejich pořadí není důležité.
Následuje příklad nejjednodušší rozdílové dotazu. To se používá při počáteční synchronizaci.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Následuje příklad následného požadavku.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Odpovědi na dotazy rozdílové
Tato část popisuje obsah rozdílové dotazu odpovědi, která je vrácena, pokud rozdílová dotazu požadavku. Následující seznam popisuje obsah odpovědi:
Nula na 200 DirectoryObject entity, z nichž každý obsahuje změny pro konkrétní uživatele, skupiny, nebo kontaktujte objektu.
Nula na 3000 DirectoryLinkChange entity, z nichž každý obsahuje změny pro konkrétní člen nebo manager odkaz.
Buď deltaLink nebo nextLink vlastnost. V obou případech je jeho hodnota malá a velká písmena, kódovaná adresou URL řetězec, který se vloží informace o sadu změn adresáře, které byl vrácen do klienta, s ohledem na ostatní změny, ke kterým došlo v adresáři stavu. Tento řetězec (nebo token) by měl být součástí deltaLink parametr řetězce v další rozdílové dotazu požadavku dotazu.
Pokud deltaLink je vrácena vlastnost, neexistují žádné další změny adresáře zbývajících pro aplikaci pro synchronizaci po této odpovědi. Aplikace můžete Počkejte chvíli předem určený podle vlastní požadavky na vydání další rozdílové dotazu požadavku.
Pokud nextLink je vrácena vlastnost, jsou změny adresáře zbývající pro aplikaci pro synchronizaci po této odpovědi. Aplikace by měla vydání další rozdílové dotazu požadavku na jeho nejdřívější pohodlí.
Vždy jsou odpovědi vrácené ve formátu JSON.
Informace týkající se použití rozdílové dotazu
V následujícím seznamu jsou uvedeny důležité informace pro aplikace, které používají rozdílové dotazu:
Vrácené dotazem rozdílové změny reprezentovat stav objektů adresáře v době odezvy. Vaše aplikace nesmí tyto změny považovat protokoly transakcí pro opakování.
Změny se v pořadí, ve kterém k nim došlo. Naposledy změněné objekty se zobrazí poslední i v případě, že objekt byl aktualizován vícekrát. Jejich pořadí nemá vliv také při klienta přijetí změn. V důsledku toho je možné pro změny předkládané mimo pořadí, ve srovnání s jak k nim původně došlo v adresáři.
Aplikace musí být připravené opětovná přehrání, ke kterým dochází, když se zobrazí stejné změny v odpovědi na následné. Při rozdílové dotaz provede usilovně ke snížení opětovná přehrání, jsou stále možné.
Aplikace musí být připraveny se zpracovat změnu odstranění pro objekt, který nebyl vědět.
Rozdílovou dotaz může vrátit odkaz na objekt zdroje nebo cíle, které ještě nebyly vráceny pomocí jiné reakce.
Najdete v článku funkce další rozdílové dotazů části níže Další informace o používání hlaviček požadavku omezit své dotazy ke zlepšení výkonu.
Příklady žádosti a odpovědi
Následuje příklad požadavku počáteční rozdílové dotazu:
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
Následuje příklad požadavku přírůstkové rozdílové dotazu:
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
Poznámka:: V obou tyto ukázkové požadavky $filter parametr dotazu se zobrazí pouze pro demonstrační účely. Vzhledem k tomu, že filtr určuje všechny typy možný cíl pro rozdílové dotaz (uživatele, skupiny a obraťte se na), může být vynechán a dotaz by vrátit změny všech těchto typů entit ve výchozím nastavení.
Odpověď na následující příklad ukazuje vrácený JSON:
{
"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"
}
]
}
Funkce další rozdílové dotazů
Rozdílovou dotazy mohou vracet nyní pouze aktualizované vlastnosti a odkazy – to umožňuje rychlejší zpracování a menší datové části pro volání rozdílové dotazu. Tato možnost je povolená nastavením záhlaví ocp-aad-dq-include-only-changed-properties na hodnotu true, jak je znázorněno v tomto příkladu.
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
Například pokud pouze vlastnost "displayName" uživatele byla změněna. Vráceného objektu by měl podobat tomuto:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
Rozdílová synchronizace podpory na synchronizaci z "teď" -lze zadat speciální záhlaví, vyžaduje pouze get aktuální deltaToken, tento token lze použít v následujících dotazech, které vrátí pouze změny provedené z "teď". Tady je příklad volání:
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
Odpověď bude obsahovat deltaLink, ale nebude mít změněné objekty, podobně jako tento:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Zjišťování odstraněné položky – odpovědi lze také použít ke zjištění odstraněné položky. Odstraněné objekty a odstraněných odkazy jsou označeny "aad.isDeleted" vlastnost s hodnotu nastavenou na hodnotu true; To je nezbytné, abyste měli jistotu, že aplikace můžete další informace o odstranění dříve vytvořené objekty a odkazy.