group: delta
Namespace: microsoft.graph
Rufen Sie neu erstellte, aktualisierte oder gelöschte Gruppen ab, einschließlich Änderungen an der Gruppenmitgliedschaft, ohne die gesamte Gruppensammlung vollständig lesen zu müssen. Weitere Informationen finden Sie unter Verwenden von Deltaabfragen zum Nachverfolgen von Änderungen in Microsoft Graph-Daten .
Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.
Weltweiter Service | US Government L4 | US Government L5 (DOD) | China, betrieben von 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Berechtigungen
Wählen Sie die Berechtigung oder Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.
Berechtigungstyp | Berechtigungen mit den geringsten Berechtigungen | Berechtigungen mit höheren Berechtigungen |
---|---|---|
Delegiert (Geschäfts-, Schul- oder Unikonto) | GroupMember.Read.All | Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, Group.ReadWrite.All |
Delegiert (persönliches Microsoft-Konto) | Nicht unterstützt | Nicht unterstützt |
Anwendung | GroupMember.Read.All | Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, Group.ReadWrite.All |
HTTP-Anforderung
Um mit der Nachverfolgung von Änderungen zu beginnen, stellen Sie eine Anforderung und fügen die Delta-Funktion in die Groups-Ressource ein.
GET /groups/delta
Abfrageparameter
Das Nachverfolgen von Änderungen in Gruppen verursacht eine Runde von einem oder mehreren Deltafunktionsaufrufen. Wenn Sie Abfrageparameter (außer $deltatoken
und $skiptoken
) verwenden, müssen Sie sie in der ursprünglichen Delta-Anforderung angeben. Microsoft Graph codiert automatisch alle angegebenen Parameter in den Tokenteil der in der Antwort enthaltenen @odata.nextLink
- oder @odata.deltaLink
-URL.
Sie müssen alle gewünschten Abfrageparameter nur einmal im Vorfeld angeben.
In nachfolgenden Anforderungen können Sie die @odata.nextLink
- oder @odata.deltaLink
-URL aus der vorherigen Antwort kopieren und anwenden, da diese URL bereits die codierten gewünschten Parameter enthält.
Abfrageparameter | Typ | Beschreibung |
---|---|---|
$deltatoken | string | Ein Zustandstoken, das in der @odata.deltaLink URL des vorherigen Delta-Funktionsaufrufs für dieselbe Gruppensammlung zurückgegeben wird und den Abschluss dieser Runde der Änderungsnachverfolgung angibt. Speichern Sie die gesamte @odata.deltaLink -URL einschließlich dieses Tokens, und wenden Sie sie in der ersten Anforderung der nächsten Änderungsnachverfolgungsrunde für diese Sammlung an. |
$skiptoken | string | Ein Statustoken, das in der @odata.nextLink -URL des vorhergehenden delta-Funktionsaufrufs zurückgegeben wird und anzeigt, dass in derselben Gruppensammlung weitere Änderungen zum Nachverfolgen vorliegen. |
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. - Sie können verwenden
$select=members
, um Mitgliedschaftsänderungen abzurufen. Sie können auch andere Änderungen wie Besitz und mehr nachverfolgen, indem Sie eine beliebige Gruppenbeziehung vom Typ directoryObject-Sammlung auswählen. - Es gibt eingeschränkte Unterstützung für
$filter
:- Der einzige unterstützte
$filter
-Ausdruck dient zum Nachverfolgen von Änderungen an einem bestimmten Objekt:$filter=id+eq+{value}
. Sie können mehrere Objekte filtern. Beispiel:https://graph.microsoft.com/v1.0/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'
. Es gilt ein Grenzwert von 50 gefilterten Objekten.
- Der einzige unterstützte
Anforderungsheader
Name | Beschreibung |
---|---|
Authorization | Bearer {token}. Erforderlich. Erfahren Sie mehr über 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
Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK
und das group-Sammlungsobjekt im Antworttext zurückgegeben. 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 nimmt weiterhin Anforderungen über die
@odata.nextLink
-URL vor, bis eine@odata.deltaLink
-URL in der Antwort zurückgegeben wird. - 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 nimmt weiterhin Anforderungen über die
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 , wie im zweiten Beispiel unten gezeigt.
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 das nachfolgende dritte Beispiel.
Beispiel
Anforderung 1
Das folgende Beispiel zeigt eine Anfrage. Da kein $select
Parameter vorhanden ist, wird ein Standardsatz von Eigenschaften nachverfolgt und zurückgegeben.
GET https://graph.microsoft.com/v1.0/groups/delta
Antwort 1
Hier sehen Sie ein Beispiel für die Antwort, wenn sie aus @odata.deltaLink
der Abfrageinitialisierung abgerufen wird.
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
Beachten Sie das Vorhandensein der members@delta-Eigenschaft , die die IDs von Memberobjekten in der Gruppe enthält.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups","@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
"value":[
{
"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",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "693acd06-2877-4339-8ade-b704261fe7a0"
},
{
"@odata.type": "#microsoft.graph.user",
"id": "49320844-be99-4164-8167-87ff5d047ace"
}
]
}
]
}
Anforderung 2
Das nächste Beispiel zeigt die anfängliche Anforderung, die drei Eigenschaften für die Änderungsnachverfolgung mit standardem Antwortverhalten auswählt:
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,mailNickname
Antwort 2
Hier sehen Sie ein Beispiel für die Antwort, wenn sie aus @odata.deltaLink
der Abfrageinitialisierung abgerufen wird. Alle drei 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/v1.0/$metadata#groups",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"displayName": "All Company",
"description": null,
"mailNickname": "allcompany@contoso.com"
}
]
}
Anforderung 3
Das nächste Beispiel zeigt die anfängliche Anforderung, die drei Eigenschaften für die Änderungsnachverfolgung mit einem alternativen minimalen Antwortverhalten auswählt:
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,mailNickname
Prefer: return=minimal
Antwort 3
Hier sehen Sie ein Beispiel für die Antwort, wenn sie aus @odata.deltaLink
der Abfrageinitialisierung abgerufen wird. Die mailNickname
-Eigenschaft ist nicht enthalten, was bedeutet, dass sie sich seit der letzten Deltaabfrage displayName
nicht geändert hat und description
enthalten ist, was bedeutet, dass sich ihre Werte geändert haben.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
"@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"displayName": "Everyone",
"description": null
}
]
}