Differentiële query | Graph API-concepten
Van toepassing op: Graph API | Azure Active Directory
Dit onderwerp worden beschreven de differentiële query-functie van Azure AD Graph API. Een queryaanvraag differentiële retourneert alle wijzigingen in de opgegeven entiteiten tijdens de periode tussen twee opeenvolgende aanvragen. Bijvoorbeeld, als u een differentiële query aanvragen van een uur na de vorige differentiële queryaanvraag, wordt alleen de wijzigingen die zijn aangebracht tijdens dat uur geretourneerd. Deze functionaliteit is vooral nuttig wanneer synchronisatie directorygegevens van tenant met een toepassing gegevens opslaat.
Als u wilt een differentiële-aanvraag van een tenant directory, moet uw toepassing worden geautoriseerd door de tenant. Zie voor meer informatie toepassingen integreren met Azure Active Directory.
Belangrijk
Wordt aangeraden dat u Microsoft Graph in plaats van Azure AD Graph API voor toegang tot Azure Active Directory-resources. Ontwikkeling van onze producten nu concentreren zich bij Microsoft Graph en geen verdere verbeteringen zijn gepland voor Azure AD Graph API. Er zijn een zeer beperkt aantal scenario's waarvoor Azure AD Graph API nog steeds mogelijk geschikt; Zie voor meer informatie de Microsoft Graph of de Azure AD Graph blogbericht in het Office-ontwikkelaarscentrum.
Differentiële queryaanvragen
Deze sectie beschrijft differentiële queryaanvragen. Alle aanvragen zijn de volgende onderdelen nodig:
Een geldige aanvraag-URL, met inbegrip van het eindpunt van de grafiek voor de tenant en de toepasselijke queryreeksparameters.
Een autorisatie-header, met inbegrip van een geldige toegangstoken dat is uitgegeven door Azure Active Directory. Zie voor meer informatie over verificatie voor Graph API verificatie scenario's voor Azure AD.
De aanvraag-URL differentiële query
Hieronder ziet u de indeling van de URL voor differentiële queryaanvraag; vierkante haken aangeven optionele elementen.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
De URL bestaat uit een hiërarchische segmenten gevolgd door een reeks queryreeksparameters uitgedrukt als sleutel-waardeparen.
URL: De hiërarchische segmenten
| Segment | Description |
|---|---|
| tenantId | De unieke id van de tenant die de query moet worden uitgevoerd tegen. Dit is meestal een van de geverifieerde domeinen (verifiedDomains eigenschap) van de tenant, maar het kan ook de object-ID van de tenant (objectId eigenschap). Niet hoofdlettergevoelig. |
| resourceSet | De specifieke set met deze query moet worden uitgevoerd met tenantbronnen. Hiermee wordt bepaald welke bronnen worden geretourneerd in antwoord op de query. Ondersteunde waarden zijn: 'directoryObjects', 'gebruikers', 'contactpersonen' of 'groepen'. Waarden zijn hoofdlettergevoelig. |
URL: Queryreeksparameters
| Parameter | Description |
|---|---|
| api-versie | Hiermee geeft u de versie van de Graph API op basis waarvan de aanvraag is uitgegeven. Vereist. Vanaf versie 1.5, wordt de waarde uitgedrukt als een numerieke versienummer; bijvoorbeeld, api-versie 1.5 =. Voor eerdere versies van is de waarde een tekenreeks in de notatie jjjj-MM-DD; bijvoorbeeld, api-version = 2013-04-05. (Vervangt het gebruik van x-ms-dirapi-data-contract-version header in de preview-versie van Graph API.) |
| deltaLink | Het token geretourneerd in ofwel de deltaLink eigenschap of de nextLink eigenschap in de laatste reactie. Vereist, maar leeg op de eerste aanvraag. (Vervangt de skipToken querytekenreeksparameter in de preview-versie van Graph API.) |
| $filter | Hiermee wordt aangegeven welke Entiteitstypen moeten worden opgenomen in het antwoord. Optioneel. De ondersteunde entiteittypen zijn: gebruikers, groepen en neem contact op met. Alleen is geldig wanneer & ltresourceSet & gt 'directoryObjects'; anders & ltresourceSet & gt overschrijft het filter. Bijvoorbeeld, als & ltresourceSet & gt is 'gebruikers', en de $filter parameter ook is opgegeven, worden alleen de wijzigingen voor gebruikers ongeacht wat is opgegeven in de filterwaarde geretourneerd. Als & ltresourceSet & gt is 'directoryObjects' en $filter is niet opgegeven, de wijzigingen voor alle ondersteunde Entiteitstypen (gebruikers, groepen en neem contact op met) worden geretourneerd. Geef een type één entiteit, moet u een van de volgende gebruiken:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Vervangt de objectScope querytekenreeksparameter in de preview-versie van Graph API.) Belangrijke vanaf versie 1.5, de Graph API naamruimte is gewijzigd van Microsoft.WindowsAzure.ActiveDirectory in Microsoft.DirectoryServices. Eerdere versies van de Graph API blijven gebruiken van de vorige naamruimte; bijvoorbeeld: $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Hiermee geeft u op welke eigenschappen moeten worden opgenomen in het antwoord. Als * $select ^ niet is opgegeven, alle eigenschappen zijn opgenomen. Eigenschappen kunnen worden opgegeven, volledig gekwalificeerde of niet-gekwalificeerde. Meerdere eigenschappen worden gescheiden door komma's.
|
Opmerking: de sleutel / waarde-paren in de queryreeks zijn hoofdlettergevoelig, maar de volgorde is geen aanzienlijke.
Hier volgt een voorbeeld van de eenvoudigste differentiële query. Dit wordt gebruikt tijdens de eerste synchronisatie.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Hier volgt een voorbeeld van een volgend verzoek.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Reacties op differentiële query 's
Deze sectie beschrijft de inhoud van een differentiële queryantwoord dat wordt geretourneerd wanneer een differentiële queryaanvraag wordt gedaan. De volgende lijst beschrijft de inhoud van een antwoord:
Nul tot 200 DirectoryObject entiteiten, die elk wijzigingen voor een specifieke bevat gebruiker, groep, of Contact object.
Nul tot 3000 DirectoryLinkChange entiteiten, die elk wijzigingen voor een specifieke bevat lid of manager koppeling.
Ofwel een deltaLink of een nextLink eigenschap. In beide gevallen is de waarde een hoofdlettergevoelig, URL-gecodeerde tekenreeks die ingesloten statusinformatie over de set directorywijzigingen die zijn geretourneerd naar de client, met betrekking tot de resterende wijzigingen die zijn opgetreden in de map. Deze tekenreeks (of token) moet worden opgenomen in de deltaLink querytekenreeksparameter in de volgende differentiële queryaanvraag.
Als de deltaLink eigenschap wordt geretourneerd, er zijn geen directorywijzigingen meer dat is gegeven voor de toepassing om te synchroniseren na dit antwoord. De toepassing kan wachten op een vooraf vastgestelde even volgens de eigen vereisten van de volgende differentiële query-aanvraag.
Als de nextLink eigenschap wordt geretourneerd, zijn er wijzigingen in directory resterende voor de toepassing om te synchroniseren na dit antwoord. De toepassing mag de volgende differentiële queryaanvraag bij de vroegste gemak uitgeven.
Antwoorden worden altijd in JSON-indeling geretourneerd.
Overwegingen bij het gebruik van differentiële query
De volgende lijst licht belangrijke aandachtspunten voor toepassingen die gebruikmaken van differentiële query:
Wijzigingen die zijn geretourneerd door differentiële query wordt de status van de directory-objecten weer op het moment van het antwoord. Uw toepassing moet deze wijzigingen niet behandelen als transactielogboeken voor opnieuw afspelen.
Wijzigingen worden weergegeven in de volgorde waarin ze zijn opgetreden. De meest recent gewijzigde objecten weergegeven laatste zelfs als het object is meerdere keren bijgewerkt. De volgorde is ook niet beïnvloed door wanneer de client de wijzigingen ontvangen. Als gevolg hiervan, is het mogelijk om wijzigingen te worden gepresenteerd volgorde ten opzichte van hoe ze in eerste instantie zijn opgetreden in de map.
Uw toepassing moet worden voorbereid voor replays die zich voordoen wanneer dezelfde wijziging wordt weergegeven in de volgende antwoorden. Differentiële query maakt een zo goed mogelijke poging om te beperken replays, zijn ze nog steeds mogelijk.
Uw toepassing moet worden voorbereid voor het afhandelen van een wijziging van de verwijdering van een object niet op de hoogte van is.
Differentiële query kan resulteren in een koppeling naar een bron- of doelentiteit-object dat nog niet is geretourneerd door andere antwoorden.
Zie de extra differentiële query functies sectie hieronder voor meer informatie over het gebruik van de aanvraagheaders voor het beperken van uw query's om prestaties te verbeteren.
Aanvraag en antwoord-voorbeelden
Hier volgt een voorbeeld van een eerste differentiële query-aanvraag:
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
Hier volgt een voorbeeld van een incrementele differentiële queryaanvraag:
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
Opmerking: In zowel deze aanvragen voorbeeld de $filter queryparameter voor demonstratiedoeleinden alleen wordt weergegeven. Omdat het filter alle typen mogelijk doel bevat voor de differentiële query (gebruikers, groepen en neem contact op met) deze kan worden weggelaten en zou de query wijzigingen voor al deze Entiteitstypen standaard retourneren.
Het volgende voorbeeld-antwoord wordt getoond hoe de geretourneerde 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"
}
]
}
Extra differentiële query-functies
Differentiële query's kunnen nu retourneren alleen eigenschappen die worden bijgewerkt en koppelingen – Hierdoor kunnen snellere verwerking en verminderde nettoladingen voor differentiële Query aanroepen. Deze optie is ingeschakeld door de header ocp-aad-dq-include-only-changed-properties als waar, omdat in dit voorbeeld wordt getoond.
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
Bijvoorbeeld als alleen de eigenschap 'weergavenaam' van de gebruiker is gewijzigd. Het geretourneerde object zou zijn vergelijkbaar met het volgende:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
Ondersteuning voor differentiële synchronisatie synchroniseren vanuit 'nu' -een speciale koptekst kan worden opgegeven, vraagt op alleen get een up-to-date deltaToken dit token kan worden gebruikt in de volgende query's, die alleen de wijzigingen van 'nu' wordt geretourneerd. Dit is de aanroep van voorbeeld:
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
Het antwoord bevat de deltaLink, maar hebben niet de gewijzigde objecten, vergelijkbaar met het volgende:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Detecteren van een verwijderd item : het antwoord kan ook worden gebruikt voor het detecteren van een verwijderd item. Verwijderde objecten en Verwijderde koppelingen worden aangeduid met de eigenschap 'aad.isDeleted' met een waarde is ingesteld op waar is; Dit is nodig om ervoor te zorgen dat toepassingen vindt meer informatie over het verwijderen van de eerder gemaakte objecten en koppelingen.