Differentiella fråga | Graph API-begrepp
Gäller för: Graph API | Azure Active Directory
Det här avsnittet beskriver funktionen differentiell frågan i Azure AD Graph API. En differentiell fråga returnerar alla ändringar i angivna enheter under tiden mellan två på varandra följande begäranden. Till exempel om du gör en differentiell fråga som begär en timme efter föregående differentiell fråga kan kommer endast de ändringar som gjorts under den timmen att returneras. Den här funktionen är särskilt användbart när du synkroniserar klient med programdata katalogdatabas.
Om du vill göra en differentiell fråga till en klient directory måste ditt program verifieras av klienten. Mer information finns i integrera program med Azure Active Directory.
Viktigt
Vi rekommenderar starkt att du använder Microsoft Graph i stället för Azure AD Graph API för att komma åt resurser i Azure Active Directory. Vårt utvecklingsarbete är nu samlade på Microsoft Graph och inga fler förbättringar som planeras att Azure AD Graph API. Det finns ett begränsat antal scenarier som Azure AD Graph API kan fortfarande vara lämplig. Mer information finns i Microsoft Graph eller Azure AD Graph blogginlägget i Office Dev Center.
Differentiella frågebegäranden
Det här avsnittet beskrivs differentiell frågebegäranden. Alla förfrågningar kräver följande komponenter:
En giltig URL-begäran, inklusive diagram slutpunkten för klient och gäller sträng Frågeparametrar.
Ett authorization-huvud, inklusive en åtkomst-token som utfärdats av Azure Active Directory. Mer information om autentisering för Graph API finns Autentiseringsscenarier för Azure AD.
Differentiella fråge-URL för begäran
Nedan visas ett format för URL: en för differentiell fråga; hakparentes [] Anger valfria element.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
Webbadressen består av en hierarkisk segment följt av en serie sträng frågeparametrar uttryckt i nyckel-värdepar.
URL: Hierarkisk segment
| Segment | Description |
|---|---|
| tenantId | Den unika identifieraren för innehavaren som frågan ska köras mot. Detta är vanligtvis en av de verifierade domänerna (verifiedDomains egenskapen) för klienten, men det kan också vara klientens objekt-ID (objectId egenskap). Inte skiftlägeskänsliga. |
| resourceSet | Uppsättningen klientresurser som den här frågan ska köras mot. Anger vilka resurser returneras i svaret på frågan. Värden som stöds är: ”directoryObjects”, ”användare”, ”kontakter” eller ”grupper”. Värden är skiftlägeskänsliga. |
URL: Frågan string-parametrar
| Parameter | Description |
|---|---|
| api-version | Anger versionen av Graph-API som begäran har utfärdats. Krävs. Från och med version 1.5, uttrycks värdet som ett numeriskt versionsnummer; till exempel api-version = 1.5. Värdet är för tidigare versioner av en sträng med formatet ÅÅÅÅ-MM-DD; till exempel api-version = 2013-04-05. (Ersätter användning av x-ms-dirapi-data-contract-version huvudet i av förhandsversionen av Graph API.) |
| deltaLink | Token som returneras i antingen den deltaLink egenskapen eller nextLink egenskap i det senaste svaret. Krävs men är tomma på den första begäranden. (Ersätter den skipToken frågesträngparametern i av förhandsversionen av Graph API.) |
| $filter | Anger vilka typer av enheter som ska inkluderas i svaret. Valfritt. Typerna av enheter som stöds är: användare, grupp och kontakta. Endast är giltigt när & ltresourceSet & gt ”directoryObjects”; Annars & ltresourceSet & gt åsidosätter filtret. Till exempel om & ltresourceSet & gt är ”användare”, och $filter parametern också anges endast ändringar för användare returneras oavsett vad som anges i filtervärdet. Om & ltresourceSet & gt är ”directoryObjects” och $filter har inte angetts ändringar för alla stöds entitetstyper (användare, grupp och kontakt) returneras. Använd något av följande om du vill ange en enda entitet av typen:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Ersätter den objectScope frågesträngparametern i av förhandsversionen av Graph API.) Viktiga från och med version 1.5, Graph API namnområdet har ändrats från Microsoft.WindowsAzure.ActiveDirectory till Microsoft.DirectoryServices. Tidigare versioner av Graph API fortsätta att använda föregående namnområdet; till exempel $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Anger vilka egenskaper som ska inkluderas i svaret. Om * $select ^ anges alla egenskaper ingår. Egenskaper kan anges antingen fullständigt kvalificerade eller icke-kvalificerade. Flera egenskaper är avgränsade med kommatecken.
|
Obs: nyckel / värde-par i frågesträngen är skiftlägeskänsliga, men inte ordningsföljden är viktig.
Följande är ett exempel på den enklaste differentiella frågan. Det här används under den inledande synkroniseringen.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Följande är ett exempel på efterföljande begäran.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Differentiella frågesvar
Det här avsnittet beskrivs innehållet i en differentiell frågesvar som returneras när en differentiell fråga görs. I följande lista beskrivs innehållet i ett svar:
Noll till 200 DirectoryObject entiteter, som innehåller ändringar för ett visst användare, grupp, eller Kontakta objekt.
Noll till 3000 DirectoryLinkChange entiteter, som innehåller ändringar för ett visst medlem eller manager länk.
Antingen en deltaLink eller en nextLink egenskapen. I båda fallen kan är dess värde en skiftlägeskänslig, URL-kodade sträng som bäddar in statusinformation om uppsättning katalogändringar som har returnerats till klienten med avseende på återstående ändringar som har inträffat i katalogen. Den här strängen (eller token) ska tas med i den deltaLink frågesträngparametern i nästa differentiell fråga.
Om den deltaLink egenskapen returneras inga ändringar har gjorts flera directory kvar för programmet som ska synkroniseras efter det här svaret. Programmet kan vänta lite förutbestämd tid enligt sina egna krav att utfärda nästa differentiell fråga.
Om den nextLink egenskapen returneras finns det katalogändringar återstående för programmet som ska synkroniseras efter det här svaret. Programmet ska utfärda nästa differentiell fråga när den tidigaste dig.
Svar returneras alltid i JSON-format.
Överväganden när du använder differentiella fråga
I följande lista visar viktiga överväganden för program som använder differentiella fråga:
Ändringar som returneras av differentiell fråga representerar tillståndet för directory-objekt vid tidpunkten för svaret. Programmet måste inte behandla ändringarna som transaktionsloggar för att svarsidentifiering.
Ändringar visas i den ordning som de inträffade. Senast ändrade objekt visas senast även om objektet har uppdaterats flera gånger. Ordningsföljden är också inte påverkas av när klienten emot ändringarna. Därför är det möjligt för att ändringarna ska visas i oordning jämfört med hur de ursprungligen uppstod i katalogen.
Programmet måste förberedas för repetitioner som inträffar när samma ändringar visas i efterföljande svar. Medan differentiell fråga gör en bästa för att minska repetitioner, är de fortfarande möjligt.
Programmet måste förberedas för att hantera en borttagning ändring för ett objekt som det inte var medveten om.
Differentiella frågan kan returnera en länk till ett käll- eller objekt som inte ännu har returnerats av andra svar.
Finns det ytterligare differentiell frågefunktioner avsnittet nedan för mer information om hur du använder huvuden för begäran om du vill begränsa dina frågor att förbättra prestanda.
Exempel för förfrågan och svar
Följande är ett exempel på en inledande differentiell fråga:
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
Följande är ett exempel på en inkrementell differentiell fråga:
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
Obs: I båda dessa exempel begäranden i $filter frågeparameter visas endast i demonstrationssyfte. Eftersom filtret anger de olika möjligt mål för den differentiella frågan (användare, grupp och kontakt) kan anges och returnerar frågan ändringar för alla dessa entitetstyper som standard.
Följande exempelsvar visar returnerade 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"
}
]
}
Ytterligare differentiell frågefunktioner
Differentiella frågor kan nu bara returnera uppdaterade egenskaper och länkar – detta innebär snabbare bearbetning och minskade nyttolaster för differentiell fråga-anrop. Det här alternativet aktiveras genom att ange rubriken ocp-aad-dq-include-only-changed-properties till true som visas i det här exemplet.
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
Till exempel om endast egenskapen ”visningsnamn” för användare som har ändrats. Det returnerade objektet är ungefär så här:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
Differentiell synkronisering supporten om du vill synkronisera från ”nu” -särskilda rubrik kan anges begär att endast få uppdaterade deltaToken detta token kan användas i efterföljande frågor, vilket returnerar endast ändringar från ”nu”. Här är exempel anropet:
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
Svaret innehåller den deltaLink, men har inte de ändrade objekten ut ungefär så här:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Identifiera ett borttaget objekt – svaret kan också användas för att identifiera ett borttaget objekt. Borttagna objekt och borttagna länkar anges av egenskapen ”aad.isDeleted” med ett värde på värdet true; Detta är nödvändigt att se till att program kan läsa mer om borttagning av tidigare skapade objekt och länkar.