Differenzielle Abfragen | Graph-API-Konzepte
Gilt für: Graph-API | Azure Active Directory
In diesem Artikel wird das Feature für differenzielle Abfragen mit der Azure AD Graph-API besprochen. Eine differenzielle Abfrage gibt alle Änderungen zurück, die an angegebenen Entitäten im Zeitraum zwischen zwei aufeinanderfolgenden Anforderungen vorgenommen wurden. Wenn Sie z. B. eine differenzielle Abfrageanforderung eine Stunde nach der vorherigen Abfrageanforderung ausgeben, werden nur die während dieser Stunde vorgenommenen Änderungen zurückgegeben. Diese Funktion ist insbesondere dann sinnvoll, wenn Verzeichnisdaten des Mandanten mit dem Datenspeicher einer Anwendung synchronisiert werden.
Damit eine differenzielle Abfrageanforderung für das Verzeichnis eines Mandanten erfolgen kann, muss Ihre Anwendung durch den Mandanten autorisiert sein. Weitere Informationen finden Sie unter Integrieren von Anwendungen in Azure Active Directory.
Wichtig
Es wird dringend empfohlen, für den Zugriff auf Azure Active Directory-Ressourcen Microsoft Graph zu verwenden, nicht die Azure AD Graph-API. Wir konzentrieren unsere Entwicklungsarbeit auf Microsoft Graph, weitere Verbesserungen für die Azure AD Graph-API sind nicht geplant. Es gibt einige wenige Szenarien, in denen die Azure AD Graph-API möglicherweise noch geeignet ist. Weitere Informationen finden Sie im Office Dev Center im Blogbeitrag Microsoft Graph or the Azure AD Graph.
Differenzielle Abfrageanforderungen
In diesem Abschnitt werden differenzielle Abfrageanforderungen beschrieben. Alle Anforderungen benötigen die folgenden Komponenten:
Eine gültige Anforderungs-URL einschließlich Graph-Endpunkt für den Mandanten und ggf. anwendbare Abfragezeichenfolgenparameter.
Einen Autorisierungsheader, der ein gültiges Zugiffsstoken enthält, das von Azure Active Directory ausgestellt wurde. Weitere Informationen zur Authentifizierung bei der Graph-API finden Sie unter Authentifizierungsszenarien für Azure AD.
URL für differenzielle Abfrageanforderungen
Das folgende Beispiel zeigt das Format der URL für differenzielle Abfrageanforderungen. Eckige Klammern ([]) zeigen optionale Elemente an.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
Die URL besteht aus hierarchischen Segmenten, gefolgt von einer Reihe von Abfragezeichenfolgenparametern, die als Schlüssel-Wert-Paare ausgedrückt werden.
URL: Hierarchische Segmente
| Segment | Beschreibung |
|---|---|
| tenantId | Der eindeutige Bezeichner des Mandanten, für den die Abfrage ausgeführt werden soll. Dies ist normalerweise eine der überprüften Domänen (verifiedDomains-Eigenschaft) des Mandanten, es kann sich jedoch auch um die Objekt-ID (objectId-Eigenschaft) des Mandanten handeln. Keine Unterscheidung zwischen Groß-/Kleinschreibung. |
| resourceSet | Die jeweilige Sammlung von Mandantenressourcen, für die die Abfrage ausgeführt werden soll. Bestimmt, welche Ressourcen in der Abfrageantwort zurückgegeben werden. Die folgenden Werte werden unterstützt: „directoryObjects“, „users“, „contacts“ und „groups“. Bei den Werten wird die Groß-/Kleinschreibung berücksichtigt. |
URL: Abfragezeichenfolgenparameter
| Parameter | Beschreibung |
|---|---|
| api-version | Gibt die Version der Graph-API an, für die die Anforderung ausgegeben wird. Erforderlich. Ab Version 1.5 wird der Wert als numerische Versionsnummer angegeben, z. B. „api-version=1.5“. Für frühere Versionen ist der Wert eine Zeichenfolge im Format JJJJ-MM-TT, z. B. „api-Version=2013-04-05“. (Ersetzt die Verwendung des x-ms-dirapi-data-contract-version-Headers in der Vorschauversion der Graph-API.) |
| deltaLink | Das Token, das in der Eigenschaft deltaLink oder nextLink in der letzten Antwort zurückgegeben wird. Erforderlich, jedoch bei der ersten Anforderung leer. (Ersetzt den skipToken-Abfragezeichenfolgenparameter in der Vorschauversion der Graph-API.) |
| $filter | Gibt an, welche Entitätstypen in der Antwort enthalten sein sollen. (Optional) Die folgenden Entitätstypen werden unterstützt: „User“, „Group“ und „Contact“. Nur gültig, wenn <resourceSet> den Wert „directoryObjects“ besitzt, andernfalls setzt <resourceSet> den Filter außer Kraft. Wenn <resourceSet> z. B. den Wert „users“ aufweist und der Parameter $filter ebenfalls angegeben wird, werden unabhängig davon, was im Filterwert angegeben wurde, nur Änderungen für Benutzer zurückgegeben. Wenn <resourceSet> den Wert „directoryObjects“ besitzt und $filter nicht angegeben wird, werden Änderungen für alle unterstützten Entitätstypen („User“, „Group“ und „Contact“) zurückgegeben. Verwenden Sie eine der folgenden Möglichkeiten, um einen einzelnen Entitätstyp anzugeben:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Ersetzt den objectScope-Abfragezeichenfolgenparameter in der Vorschauversion der Graph-API.) Wichtig Der Graph-API-Namespace Microsoft.WindowsAzure.ActiveDirectory lautet ab Version 1.5 Microsoft.DirectoryServices. In früheren Versionen der Graph-API wird weiterhin der vorherige Namespace verwendet. Beispiel: $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Gibt an, welche Eigenschaften in die Antwort eingeschlossen werden sollen. Wenn *$select^ nicht angegeben ist, werden alle Eigenschaften eingeschlossen. Eigenschaften können vollqualifiziert oder unqualifiziert angegeben werden. Mehrere Eigenschaften werden durch Kommas voneinander getrennt.
|
Hinweis: Für die Schlüssel-Wert-Paare in der Abfragezeichenfolge wird zwischen Groß-Kleinschreibung unterschieden. Ihre Reihenfolge ist jedoch unwesentlich.
Das folgende Beispiel zeigt die einfachste differenzielle Abfrage: Diese wird während der anfänglichen Synchronisierung verwendet.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Das folgende Beispiel zeigt eine nachfolgende Anforderung.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Antworten auf differenzielle Abfragen
In diesem Abschnitt werden die Inhalte der Antwort auf eine differenzielle eine Abfrage beschrieben, die zurückgegeben wird, wenn eine differenzielle Abfrageanforderung ausgeführt wird. In der folgenden Liste werden die Inhalte einer Antwort beschrieben:
Null bis 200 DirectoryObject-Entitäten, von denen jede Änderungen für ein bestimmtes User, Group oder ContactObjekt enthält.
Null bis 3000 DirectoryLinkChange-Entitäten, von denen jede Änderungen für einen bestimmten member- oder manager-Link enthält.
Die deltaLink-Eigenschaft oder die nextLink-Eigenschaft. In beiden Fällen ist der Wert eine URL-codierte Zeichenfolge, für die zwischen Groß- und Kleinschreibung unterschieden wird, die Statusinformationen zu den Verzeichnisänderungen einbettet, die in Bezug auf die verbleibenden Änderungen, die im Verzeichnis aufgetreten sind, an den Client zurückgegeben wurden. Diese Zeichenfolge (oder dieses Token) sollte im deltaLink-Abfragezeichenfolgenparameter der nächsten differenziellen Abfrageanforderung enthalten sein.
Wenn die deltaLink-Eigenschaft zurückgegeben wird, sind nach dieser Antwort keine weiteren Verzeichnisänderungen vorhanden, die die Anwendung synchronisieren muss. Die Anwendung kann nun für ein vorab gemäß ihren Anforderungen definiertes Zeitintervall warten, bis die nächste differenzielle Abfrageanforderung ausgegeben wird.
Wenn die nextLink-Eigenschaft zurückgegeben wird, sind nach dieser Antwort noch Verzeichnisänderungen vorhanden, die die Anwendung synchronisieren muss. Die Anwendung sollte die nächste differenzielle Abfrageanforderung so bald wie möglich ausgeben.
Antworten werden immer im JSON-Format zurückgegeben.
Überlegungen für die Verwendung differenzieller Abfragen
Die folgende Liste nennt wichtige Überlegungen für Anwendungen, die differenzielle Abfragen verwenden:
Änderungen, die von einer differenziellen Abfrage zurückgegeben werden, stellen den Status der Verzeichnisobjekte zum Zeitpunkt der Antwort dar. Ihre Anwendung darf diese Änderungen nicht als Transaktionsprotokolle für Replay verwenden.
Änderungen werden in der Reihenfolge angezeigt, in der sie aufgetreten sind. Die Objekte, die zuletzt geändert wurden, werden selbst dann an letzter Stelle angezeigt, wenn das Objekt mehrmals aktualisiert wurde. Ihre Reihenfolge wird auch nicht durch den Zeitpunkt beeinflusst, an dem der Client die Änderungen empfangen hat. Daher ist es möglich, dass Änderungen in einer anderen Reihenfolge als der Reihenfolge angezeigt werden, in der sie ursprünglich im Verzeichnis aufgetreten sind.
Ihre Anwendung muss auf Replays vorbereitet sein, die auftreten, wenn die gleiche Änderung in nachfolgenden Antworten enthalten ist. Trotz aller Bemühungen differenzieller Abfragen, Replays zu verringern, sind diese dennoch möglich.
Ihre Anwendung muss darauf vorbereitet sein, eine Löschänderung für ein Objekt zu verarbeiten, die ihr unbekannt war.
Differenzielle Abfragen können einen Link zu einem Quell- oder Zielobjekt zurückgeben, das von anderen Antworten noch nicht zurückgegeben wurde.
Im Abschnitt Zusätzliche Funktionen für differenzielle Abfragen weiter unten finden Sie weitere Informationen zur Verwendung der Anforderungsheader, um Abfragen zur Verbesserung der Leistung zu beschränken.
Beispiele für Anforderung und Antwort
Das folgende Beispiel zeigt eine anfängliche differenzielle Abfrage:
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
Das folgende Beispiel zeigt eine inkrementelle differenzielle Abfrageanforderung:
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
Hinweis: In beiden Beispielanforderungen wird der $filter-Abfrageparameter nur für Demonstrationszwecke gezeigt. Da der Filter alle möglichen Zieltypen für die differenzielle Abfrage zeigt (User, Group und Contact), kann er ausgelassen werden, und die Abfrage würde standardmäßig Änderungen für alle diese Entitätstypen zurückgeben.
Die folgende Beispielantwort zeigt den zurückgegebenen JSON-Code:
{
"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"
}
]
}
Zusätzliche Features für differenzielle Abfragen
Differenzielle Abfragen können jetzt nur aktualisierte Eigenschaften und Links zurückgeben – dies ermöglicht eine schnellere Verarbeitung und geringere Nutzlasten für Aufrufe differenzieller Abfragen. Diese Option wird aktiviert, indem Sie den Header ocp-aad-dq-include-only-changed-properties auf „true“ festlegen, wie im folgenden Beispiel gezeigt.
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
Angenommen, nur die displayName-Eigenschaft von „user“ wurde geändert. Das zurückgegebene Objekt lautet dann in etwa wie folgt:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
Unterstützung der differenziellen Synchronisierung für die Synchronisierung ab „jetzt“: Ein spezieller Header kann angegeben werden, um nur ein aktuelles deltaToken abzurufen. Dieses Token kann in nachfolgenden Abfragen verwendet werden, mit denen Änderungen ab „jetzt“ zurückgegeben werden. Beispielaufruf:
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
Die Antwort enthält den deltaLink, jedoch keine geänderten Objekte, ähnlich wie dieses Beispiel:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Erkennen eines gelöschten Elements – die Antwort kann auch verwendet werden, um ein gelöschtes Element zu erkennen. Gelöschte Objekte und gelöschte Links werden durch die Eigenschaft „aad.isDeleted“ mit einem auf „true“ festgelegten Wert gekennzeichnet. Dies ist erforderlich, um sicherzustellen, dass Anwendungen vom Löschen der zuvor erstellten Objekte und Links erfahren.