directoryObject: delta
Wichtig
Die APIs unter der /beta
Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.
Namespace: microsoft.graph
Rufen Sie neu erstellte, aktualisierte oder gelöschte Verzeichnisobjekte ab, ohne die gesamte directoryObject-Auflistung vollständig zu lesen. Weitere Informationen zur Delta-Funktion finden Sie unter Verwenden von Deltaabfragen zum Nachverfolgen von Änderungen in Microsoft Graph-Daten .
Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.
Globaler Dienst | US Government L4 | US Government L5 (DOD) | China, betrieben von 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Berechtigungen
In der folgenden Tabelle sind die Berechtigungen mit den geringsten Berechtigungen aufgeführt, die für jeden Ressourcentyp erforderlich sind, wenn diese API aufgerufen wird. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie unter Berechtigungen.
Unterstützte Ressource | Delegiert (Geschäfts-, Schul- oder Unikonto) | App | Delegiert (persönliches Microsoft-Konto) |
---|---|---|---|
application | Application.Read.All | Application.Read.All | Nicht unterstützt |
administrativeUnit | AdministrativeUnit.Read.All | AdministrativeUnit.Read.All | Nicht unterstützt |
device | Device.Read.All | Device.Read.All | Nicht unterstützt |
directoryRole | RoleManagement.Read.Directory | RoleManagement.Read.Directory | Nicht unterstützt |
group | Group.Read.All | Group.Read.All | Nicht unterstützt |
orgContact | OrgContact.Read.All | OrgContact.Read.All | Nicht unterstützt |
servicePrincipal | Application.Read.All | Application.Read.All | Nicht unterstützt |
user | User.Read.All | User.Read.All | Nicht unterstützt |
HTTP-Anforderung
Nachverfolgen von Änderungen für eine Auflistung eines Verzeichnisobjekttyps.
GET /directoryObjects/delta?$filter=isof('microsoft.graph.application')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.administrativeUnit')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.device')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.directoryRole')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.group')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.orgContact')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.servicePrincipal')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.user')
Nachverfolgen von Änderungen für ein Verzeichnisobjekt.
GET /directoryObjects/delta?$filter=id eq '{id}'
OData-Abfrageparameter
Diese Methode unterstützt optionale OData-Abfrageparameter, um die Antwort anzupassen.
- Sie können wie bei jeder GET-Anforderung den Abfrageparameter
$select
verwenden, um zwecks Leistungsoptimierung nur die benötigten Eigenschaften anzugeben. Die Eigenschaft id wird immer zurückgegeben. - Beim Filtern mehrerer Objekte, z. B. ,
/directoryObjects/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'
gilt ein Grenzwert von 50 Filterausdrücken. - Sie können die
$filter
Syntaxen kombinieren. Beispiel:$filter=isof('{resource type}') or id eq '{id}'
. Dadurch wird eine Schnittmenge von -Objekten bereitgestellt, die durch den Abgleich{resource type}
und den Ressourcentyp von{id}
angegeben werden.
Anforderungsheader
Name | Beschreibung |
---|---|
Authorization | Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung. |
Content-Type | application/json |
Prefer | return=minimal Wenn Sie für diese Kopfzeile eine Aufforderung festlegen, die ein @odata.deltaLink verwendet, würden nur die Objekteigenschaften zurückgegeben werden, die seit der letzten Runde geändert wurden. Optional. |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwort
Bei erfolgreicher Ausführung gibt die Methode den Antwortcode und das directoryObject-Auflistungsobjekt im Antworttext zurück200 OK
. Die Antwort enthält auch ein Zustandstoken, das entweder eine @odata.nextLink
URL oder eine @odata.deltaLink
URL ist.
Wenn eine
@odata.nextLink
-URL zurückgegeben wird:- Dies deutet darauf hin, dass in der Sitzung weitere Seiten mit Daten abgerufen werden sollen. Die Anwendung stellt weiterhin Anforderungen mithilfe der
@odata.nextLink
URL, bis eine@odata.deltaLink
URL in der Antwort enthalten ist. - Die Antwort enthält die gleiche Gruppe von Eigenschaften, wie in der ersten Anforderung einer Delta-Abfrage. Dadurch können Sie den vollständigen aktuellen Status der Objekte beim Initiieren des Delta-Zyklus erfassen.
- Dies deutet darauf hin, dass in der Sitzung weitere Seiten mit Daten abgerufen werden sollen. Die Anwendung stellt weiterhin Anforderungen mithilfe der
Wenn eine
@odata.deltaLink
-URL zurückgegeben wird:- Dies deutet darauf hin, dass keine Weiteren Daten zum vorhandenen Zustand der Ressource vorhanden sind, die zurückgegeben werden soll. Speichern Sie und verwenden Sie die
@odata.deltaLink
-URL, um Informationen über die Änderungen an der Ressource in der nächsten Runde zu erhalten. - Sie können die
Prefer:return=minimal
-Kopfzeile so festlegen, dass in der Antwort nur die Eigenschaften Werte enthalten sind, die seit dem Zeitpunkt geändert wurden, an dem die@odata.deltaLink
erstellt wurde.
- Dies deutet darauf hin, dass keine Weiteren Daten zum vorhandenen Zustand der Ressource vorhanden sind, die zurückgegeben werden soll. Speichern Sie und verwenden Sie die
Standard: Es werden dieselben Eigenschaften zurückgegeben wie die der ursprünglichen Delta-Anfrage
Standardmäßig geben Abfragen, die @odata.deltaLink
oder @odata.nextLink
verwenden, dieselben Eigenschaften zurück, wie sie in der ersten Delta-Abfrage ausgewählt wurden. Diese geschieht wie folgt:
- Wenn die Eigenschaft geändert wurde, ist der neue Wert in der Antwort enthalten. Dies schließt Eigenschaften ein, die auf einen Null-Wert festgelegt werden.
- Wenn sich die Eigenschaft nicht geändert hat, wird der alte Wert in die Antwort aufgenommen.
- Wenn eine Eigenschaft zuvor nie festgelegt wurde, ist sie überhaupt nicht in der Antwort enthalten.
Hinweis: Durch das Betrachten der Antwort kann nicht festgestellt werden, ob sich eine Eigenschaft ändert oder nicht. Außerdem sind die Deltaantworten in der Regel groß, da sie alle Eigenschaftswerte enthalten (siehe Beispiel 3).
Alternative: nur die geänderten Eigenschaften zurückgeben
Das Hinzufügen eines optionalen Anfrage-Headers – prefer:return=minimal
– führt zu folgendem Verhalten:
- Wenn die Eigenschaft geändert wurde, ist der neue Wert in der Antwort enthalten. Dies schließt Eigenschaften ein, die auf einen Null-Wert festgelegt werden.
- Wenn die Eigenschaft nicht geändert wurde, ist die Eigenschaft überhaupt nicht in der Antwort enthalten. (Anders als beim Standardverhalten).
Hinweis: Die Kopfzeile kann zu jedem Zeitpunkt im Delta-Zyklus zu einer
@odata.deltaLink
-Abfrage hinzugefügt werden. Die Kopfzeile wirkt sich nur auf die Gruppe von Eigenschaften, die in der Antwort enthalten sind, aus und beeinflusst nicht, wie die Delta-Abfrage ausgeführt wird. Siehe Beispiel 4.
Beispiele
Beispiel 1: Abrufen von Änderungen für eine Sammlung von Benutzern und Gruppen
Anforderung
Das folgende Beispiel zeigt eine Anforderung, die den $filter=isof('{resource type}')
Parameter für Benutzer und Gruppen verwendet. Da kein $select
Parameter vorhanden ist, wird ein Standardsatz von Eigenschaften nachverfolgt und zurückgegeben.
GET https://graph.microsoft.com/beta/directoryObjects/delta?filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')
Antwort
Hier sehen Sie ein Beispiel für die Antwort bei Verwendung von @odata.deltaLink
, die aus der Abfrageinitialisierung mit $filter=isof('{resource type}')
abgerufen wird. Beachten Sie das Vorhandensein der members@delta-Eigenschaft , die die IDs von Memberobjekten in der Gruppe enthält.
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects","@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
"value":[
{
"@odata.type": "#microsoft.graph.user",
"businessPhones": [
"+1 425 555 0109"
],
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@contoso.com",
"mobilePhone": "+1 425 555 0109",
"officeLocation": "18/2111",
"preferredLanguage": "en-US",
"surname": "Vance",
"userPrincipalName": "AdeleV@contoso.com",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
},
{
"@odata.type": "#microsoft.graph.group",
"createdDateTime":"2021-03-12T10:36:14Z",
"description":"This is the default group for everyone in the network",
"displayName":"All Company",
"groupTypes": [
"Unified"
],
"mail": "allcompany@contoso.com",
"id": "72052a9a-c466-4995-8210-95a1c1221995",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "693acd06-2877-4339-8ade-b704261fe7a0"
},
{
"@odata.type": "#microsoft.graph.user",
"id": "49320844-be99-4164-8167-87ff5d047ace"
}
]
}
]
}
Beispiel 2: Abrufen einer Auflistung von Änderungen für ein Verzeichnisobjekt
Anforderung
Das folgende Beispiel zeigt die Anforderung mit dem $filter=id eq '{id}'
-Parameter. Da kein $select
Parameter vorhanden ist, wird ein Standardsatz von Eigenschaften nachverfolgt und zurückgegeben.
GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=id eq '87d349ed-44d7-43e1-9a83-5f2406dee5bd'
Antwort
Hier sehen Sie ein Beispiel für die Antwort bei Verwendung von @odata.deltaLink
, die aus der Abfrageinitialisierung mit $filter=id eq '{id}'
abgerufen wird.
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
"@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"@odata.type": "#microsoft.graph.group",
"createdDateTime":"2021-03-12T10:36:14Z",
"description":"This is the default group for everyone in the network",
"displayName":"All Company",
"groupTypes": [
"Unified"
],
"mail": "allcompany@contoso.com",
"id": "72052a9a-c466-4995-8210-95a1c1221995",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "693acd06-2877-4339-8ade-b704261fe7a0"
},
{
"@odata.type": "#microsoft.graph.user",
"id": "49320844-be99-4164-8167-87ff5d047ace"
}
]
}
]
}
Beispiel 3: Abrufen von Änderungen an bestimmten Eigenschaften für eine Sammlung von Benutzern und Gruppen
Anforderung
Das folgende Beispiel zeigt die anfängliche Anforderung, die jeweils eine Eigenschaft eines Benutzers und einer Gruppe für die Änderungsnachverfolgung mit standardem Antwortverhalten auswählt:
GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')&$select=microsoft.graph.user/surname,microsoft.graph.group/displayName
Antwort
Hier sehen Sie ein Beispiel für die Antwort, wenn sie aus @odata.deltaLink
der Abfrageinitialisierung abgerufen wird. Beide Eigenschaften sind in der Antwort enthalten, und es ist nicht bekannt, welche sich seit dem Abrufen von @odata.deltaLink
geändert haben.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
"@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"@odata.type": "#microsoft.graph.user",
"surname": "Vance",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
},
{
"@odata.type": "#microsoft.graph.group",
"displayName":"All Company",
"id": "72052a9a-c466-4995-8210-95a1c1221995",
}
]
}
Beispiel 4: Abrufen bestimmter Eigenschaften nur, wenn sie für eine Sammlung von Benutzern und Gruppen geändert wurden
Anforderung
Das folgende Beispiel zeigt die anfängliche Anforderung, die jeweils eine Eigenschaft eines Benutzers und einer Gruppe für die Änderungsnachverfolgung mit einem alternativen minimalen Antwortverhalten auswählt:
GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')&$select=microsoft.graph.user/surname,microsoft.graph.group/displayName
Prefer: return=minimal
Antwort
Hier sehen Sie ein Beispiel für die Antwort, wenn sie aus @odata.deltaLink
der Abfrageinitialisierung abgerufen wird. Die microsoft.graph.user/surname
-Eigenschaft ist nicht enthalten, was bedeutet, dass sie sich seit der letzten Deltaabfrage nicht geändert hat. microsoft.graph.group/displayName
Ist eingeschlossen, was bedeutet, dass sich ihr Wert geändert hat.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
"@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"@odata.type": "#microsoft.graph.group",
"displayName":"Everyone",
"id": "72052a9a-c466-4995-8210-95a1c1221995",
}
]
}
Verwandte Inhalte
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für