Die abfrage kann derzeit nicht vorgenommen werden.

Weiter zum Hauptinhalt

Dieser Browser wird nicht mehr unterstützt.

Führen Sie ein Upgrade auf Microsoft Edge durch, um die neuesten Features, Sicherheitsupdates und den technischen Support zu nutzen.

Verwenden einer Delta-Abfrage zum Nachverfolgen von Änderungen in Microsoft Graph-Daten

• Artikel
• 07/07/2022
• 9 Minuten Lesedauer

In diesem Artikel

Mit der Delta-Abfrage können Anwendungen neu erstellte, aktualisierte oder gelöschte Entitäten ermitteln, ohne die Zielressource bei jeder Anforderung vollständig lesen zu müssen. Mit der Delta-Abfrage können Microsoft Graph-Anwendungen Änderungen effizient mit einem lokalen Datenspeicher synchronisieren.

Verwenden einer Delta-Abfrage zum Nachverfolgen von Änderungen in einer Ressourcensammlung

Das typische Abrufmuster sieht folgendermaßen aus:

1. Die Anwendung ruft zunächst eine GET-Anforderung mit der Delta-Funktion für die gewünschte Ressource auf.

2. Microsoft Graph sendet dann eine Antwort mit der angeforderten Ressource und einem Statustoken.

   a. Wenn eine @odata.nextLink-URL zurückgegeben wird, müssen eventuell zusätzliche Seiten mit Daten in der Sitzung abgerufen werden. Die Anwendung nimmt weiterhin Anforderungen über die @odata.nextLink-URL vor, um alle Seiten mit Daten abzurufen, bis eine @odata.deltaLink-URL in der Antwort zurückgegeben wird.

   b. Wenn eine @odata.deltaLink-URL zurückgegeben wird, gibt es keine weiteren Daten über den derzeitigen Status der zurückzugebenden Ressource. Für zukünftige Anforderungen verwendet die Anwendung die @odata.deltaLink-URL, um Informationen zu Änderungen an der Ressource zu erhalten.

3. Wenn die Anwendung Informationen zu Änderungen an der Ressource benötigt, nimmt sie eine neue Anforderung mit der in Schritt 2 erhaltenen @odata.deltaLink-URL vor. Diese Anforderung kann umgehend nach Abschluss von Schritt 2 oder bei der Prüfung auf Änderungen durch die Anwendung vorgenommen werden.

4. Microsoft Graph gibt eine Antwort, in der die seit der vorherigen Anforderung an der Ressource vorgenommenen Änderungen beschrieben werden, sowie eine @odata.nextLink-URL oder eine @odata.deltaLink-URL zurück.

Hinweis

Ressourcen, die in Azure Active Directory gespeichert sind (z. B. Benutzer und Gruppen), unterstützen „Synchronisation ab sofort“-Szenarien. Deshalb können Sie die Schritte 1 und 2 überspringen (wenn Sie nicht den vollständigen Status der Ressource abrufen möchten) und stattdessen den neuesten @odata.deltaLink abrufen. Fügen Sie $deltaToken=latest an die delta-Funktion an; die Antwort enthält dann ein @odata.deltaLink und keine Ressourcendaten. Ressourcen in Microsoft OneDrive und Microsoft Office SharePoint Online unterstützen diese Funktion ebenfalls. Bei Ressourcen in Microsoft OneDrive und Microsoft Office SharePoint Online fügen Sie stattdessen token=latest an.

Hinweis

Auf die Delta-Abfragefunktion wird im Allgemeinen durch Anhängen /delta an den Ressourcennamen verwiesen. Allerdings ist /delta eine Verknüpfung für den vollqualifizierten Namen /microsoft.graph.delta, der in Anforderungen angezeigt wird, die von Microsoft Graph-SDKs generiert werden.

Hinweis

Die anfängliche Anforderung an die Delta-Abfragefunktion (no $deltaToken oder $skipToken) gibt die Ressourcen zurück, die derzeit in der Sammlung vorhanden sind. Ressourcen, die vor der anfänglichen Delta-Abfrage erstellt und gelöscht wurden, werden nicht zurückgegeben. Updates, die vor der anfänglichen Anforderung vorgenommen wurden, werden in der Ressource zusammengefasst, die als neuester Status zurückgegeben wird.

Statustoken

Eine GET-Antwort einer Delta-Abfrage umfasst immer eine URL, die in einem @odata.nextLink- oder @odata.deltaLink-Antwortheader angegeben ist. Die @odata.nextLink-URL umfasst ein $skipToken, und eine @odata.deltaLink-URL umfasst ein $deltaToken.

Diese Token sind für den Client nicht transparent. Nachfolgend finden Sie alles, was Sie darüber wissen müssen:

• Jedes Token gibt den Status an und ist eine Momentaufnahme der Ressource in dieser Runde der Änderungsnachverfolgung.

• Die Statustoken codieren und umfassen auch andere Abfrageparameter (z. B. $select), die in der anfänglichen Delta-Abfrageanforderung angegeben sind. Es ist daher nicht erforderlich, diese in nachfolgenden Delta-Abfrageanforderungen zu wiederholen.

• Beim Ausführen von Delta-Abfragen können Sie die @odata.nextLink- oder @odata.deltaLink-URL kopieren und auf den nächsten delta-Funktionsaufruf anwenden, ohne den Inhalt der URL, einschließlich ihres Statustoken, zu überprüfen.

Optionale Abfrageparameter

Wenn ein Client einen Abfrageparameter verwendet, muss dieser in der ursprünglichen Anforderung angegeben sein. Microsoft Graph codiert automatisch den angegebenen Parameter in den in der Antwort enthaltenen @odata.nextLink oder @odata.deltaLink. Die aufrufende Anwendung muss die Abfrageparameter nur einmal im Vorfeld angeben. Microsoft Graph fügt die angegebenen Parameter automatisch für alle nachfolgenden Anforderungen hinzu.

Beachten Sie die allgemein eingeschränkte Unterstützung für die folgenden optionalen Abfrageparameter:

• $orderby

  Gehen Sie nicht von einer bestimmten Sequenz der von einer Delta-Abfrage zurückgegebenen Antworten aus. Gehen Sie davon aus, dass das gleiche Element an einer beliebigen Stelle in der Sequenz @odata.nextLink angezeigt werden kann, und berücksichtigen Sie dies in Ihrer Zusammenführungslogik.

• $top

  Die Anzahl der Objekte auf jeder Seite kann je nach Ressourcentyp und Art der Änderungen an der Ressource variieren.

Für die Ressource message schauen Sie sich die Einzelheiten zur Unterstützung von Abfrageparametern in einer Delta-Abfrage an.

Für die Ressourcen user und group gibt es Einschränkungen im Hinblick auf die Verwendung einiger Abfrageparameter:

• $expand wird nicht unterstützt.

• $top wird nicht unterstützt.

• $orderby wird nicht unterstützt.

• Wenn ein $select-Abfrageparameter verwendet wird, bedeutet dies, dass der Client nur Änderungen an den Eigenschaften oder Beziehungen nachverfolgen möchte, die in der $select-Anweisung angegeben sind. Wenn eine Änderung an einer nicht ausgewählten Eigenschaft vorgenommen wird, wird die Ressource, für die diese Eigenschaft geändert wurde, nach einer nachfolgenden Anforderung nicht in der Delta-Antwort angezeigt.

• $select unterstützt außerdem Nagivationseigenschaften für Vorgesetzte und Mitglieder für Benutzer bzw. Gruppen. Wenn Sie diese Eigenschaften auswählen, können Sie Änderungen an Manager- und Gruppenmitgliedschaften des Benutzers nachverfolgen.

• Sie können mithilfe von Bereichsfiltern Änderungen an einem oder mehreren bestimmten Benutzern bzw. einer oder mehreren bestimmten Gruppen nach Objekt-ID nachverfolgen. Die folgende Anforderung gibt beispielsweise Änderungen für die Gruppen zurück, die mit den im Abfragefilter angegebenen IDs übereinstimmen.

https://graph.microsoft.com/beta/groups/delta/?$filter=id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'

Ressourcendarstellung in der Delta-Abfrageantwort

• Neu erstellte Instanzen einer unterstützten Ressourcen werden in der Delta-Abfrageantwort mithilfe ihrer standardmäßigen Darstellung dargestellt.

• Aktualisierte Instanzen werden anhand ihrer ID mit mindestens den Eigenschaften dargestellt, die aktualisiert wurden. Es können aber auch weitere Eigenschaften eingeschlossen werden.

• Beziehungen für Benutzer und Gruppen werden als Anmerkungen in der standardmäßigen Ressourcendarstellung dargestellt. Diese Anmerkungen haben das Format propertyName@delta. Die Anmerkungen sind in der Antwort auf die erste Delta-Abfrageanforderung enthalten.

Entfernte Instanzen werden durch ihre id und ein @removed-Objekt dargestellt. Das @removed-Objekt kann zusätzliche Informationen zum Grund der Entfernung der Instanz enthalten. Beispiel: "@removed": {"reason": "changed"}.

Mögliche @removed-Gründe sind changed oder deleted.

• changed gibt an, dass das Element gelöscht wurde und aus deletedItems wiederhergestellt werden kann.

• deleted gibt an, dass das Element gelöscht wurde und nicht wiederhergestellt werden kann.

Das @removed-Objekt kann in der Antwort auf die erste Delta-Abfrage und in nachverfolgten (deltaLink-)Antworten zurückgegeben werden. Clients, die Delta-Abfrageanforderungen verwenden, sollten so konzipiert sein, dass sie diese Objekte in den Antworten behandeln.

Hinweis

Es ist möglich, dass eine einzelne Entität mehrmals in der Antwort enthalten ist, wenn diese Entität mehrmals und unter bestimmten Bedingungen geändert wurde. Mit Hilfe von Delta-Abfragen kann Ihre Anwendung alle Änderungen auflisten, aber sie kann nicht sicherstellen, dass die Entitäten in einer einzigen Antwort vereinheitlicht werden.

Unterstützte Ressourcen

Delta-Abfragen werden derzeit für die folgenden Ressourcen unterstützt. Beachten Sie, dass einige Ressourcen, die in v1.0 verfügbar sind, ihre entsprechenden Delta-Funktionen noch im Vorschaustatus haben, wie angegeben.

* Das Verwendungsmuster für OneDrive- und SharePoint-Ressourcen ähnelt dem der anderen unterstützten Ressourcen, mit geringen Unterschieden in der Syntax. Die Delta-Abfrage für Laufwerke wird zwecks Konsistenz mit anderen Ressourcentypen demnächst aktualisiert. Weitere Informationen zur aktuellen Syntax finden Sie unter driveItem: delta und listItem: delta.

** Das Nutzungsmuster für Planner-Ressourcen ist ähnlich wie bei anderen unterstützten Ressourcen mit einigen Unterschieden. Einzelheiten finden Sie unter planner: delta.

Einschränkungen

Außerhalb des primären Datenspeichers gespeicherte Eigenschaften

Einige Ressourcen enthalten Eigenschaften, die außerhalb des primären Datenspeichers für die Ressource gespeichert sind (die Benutzerressource wird beispielsweise meist im Azure Ad-System gespeichert, während einige Eigenschaften wie skills in SharePoint Online gespeichert werden). Derzeit werden diese Eigenschaften im Rahmen der Änderungsnachverfolgung nicht unterstützt. Änderungen an einer dieser Eigenschaften führen nicht dazu, dass ein Objekt in der Delta-Abfrageantwort angezeigt wird. Aktuell lösen nur die im Hauptdatenspeicher gespeicherten Eigenschaften Änderungen in der Delta-Abfrage aus.

Um zu überprüfen, ob eine Eigenschaft in einer Delta-Abfrage verwendet werden kann, versuchen Sie, einen regulären GET-Vorgang für die Ressourcensammlung auszuführen, und wählen Sie die Eigenschaft aus, an der Sie interessiert sind. Sie können beispielsweise die Eigenschaft skills in der Benutzersammlung ausprobieren.

GET https://graph.microsoft.com/v1.0/users/?$select=skills

Da die Eigenschaft skills außerhalb von Azure AD gespeichert ist, sieht die Antwort wie folgt aus.

HTTP/1.1 501 Not Implemented
Content-type: application/json

{
    "error": {
        "code": "NotImplemented",
        "message": "This operation target is not yet supported.",
        "innerError": {
            "request-id": "...",
            "date": "2019-09-20T21:47:50"
        }
    }
}

Dies weist darauf hin, dass die Eigenschaft skills für die Delta-Abfrage der Ressource user nicht unterstützt wird.

Navigationseigenschaften

Navigationseigenschaften werden nicht unterstützt. Beispielsweise können Sie keine Änderungen an der Benutzersammlung nachverfolgen, die Änderungen an ihrer Foto-Eigenschaft beinhalten würden; photo ist eine Navigationseigenschaft, die außerhalb der Benutzerentität gespeichert wird, und Änderungen daran führen nicht dazu, dass das Benutzerobjekt in die Delta-Antwort aufgenommen wird.

Verarbeitungsverzögerungen

Erwarten Sie unterschiedliche Verzögerungen zwischen dem Zeitpunkt, zu dem eine Änderung an einer Ressourceninstanz vorgenommen wird, die über eine Anwendungsschnittstelle oder API erfolgen kann, und dem Zeitpunkt, zu dem die nachverfolgte Änderung in einer Delta-Abfrageantwort reflektiert wird.

Manchmal werden die Änderungen, die am Objekt vorgenommen wurden, möglicherweise nicht angezeigt, wenn Sie die @odata.nextLink oder die @odata.deltaLink auswählen. Dies liegt daran, dass bei einigen Anforderungen Replikationsverzögerungen für Objekte auftreten können, die kürzlich erstellt, aktualisiert oder gelöscht wurden. Wiederholen Sie die @odata.nextLink oder @odata.deltaLink nach einiger Zeit, um die neuesten Änderungen abzurufen.

Nationale Clouds

Delta-Abfragen sind nur für Kunden verfügbar, die in der öffentlichen Cloud gehostet werden, sowie für Kunden von Microsoft Graph China, die von 21Vianet betrieben werden.

Wiederholungen

Ihre Anwendung muss für Wiederholungen vorbereitet werden, die auftreten, wenn die gleiche Änderung in nachfolgenden Antworten erscheint. Obwohl die Deltaabfrage nach besten Kräften versucht, Wiederholungen zu reduzieren, sind sie dennoch möglich.

Synchronisierungszurücksetzung

Die Deltaabfrage kann den Antwortcode 410 (gone) und einen Location-Header zurückgeben, der eine Anforderungs-URL mit einem leeren $deltaToken enthält (identisch mit der ursprünglichen Abfrage). Dies ist ein Hinweis darauf, dass die Anwendung mit einer vollständigen Synchronisierung des Zielmandanten neu gestartet werden muss. Dies geschieht in der Regel, um Dateninkonsistenzen aufgrund interner Wartung oder Migration des Zielmandanten zu vermeiden.

Tokendauer

Delta-Tokens sind nur für eine bestimmte Dauer gültig, bevor die Client-Anwendung erneut eine vollständige Synchronisierung ausführen muss.

• Für Verzeichnisobjekte beträgt der Grenzwert sieben Tage.
• Bei Objekten für Schulung und Weiterbildung (educationSchool, educationUser und educationClass) beträgt das Limit ebenfalls sieben Tage.
• Bei Outlook-Entitäten (message, mailFolder, event, contact, contactFolder, todoTask und todoTaskList ) wird das obere Limit nicht festgelegt; es ist abhängig von der Größe des internen Delta-Token-Caches. Während neue Delta-Token im Cache kontinuierlich hinzugefügt werden, werden nach Überschreitung der Cachekapazität die älteren Delta-Token gelöscht.

Im Falle eines abgelaufenen Tokens sollte der Dienst mit einem Fehler der 40X-Serie mit Fehlercodes wie syncStateNotFound. Weitere Informationen finden Sie unter Fehlercodes in Microsoft Graph.

Voraussetzungen

Dieselben Berechtigungen, die zum Lesen einer bestimmten Ressource erforderlich sind, werden auch zur Durchführung der Delta-Abfrage für diese Ressource benötigt.

Beispiele für die Delta-Abfrageanforderung

• Inkrementelle Änderungen an Ereignissen in einer Kalenderansicht abrufen
• Inkrementelle Änderungen an Nachrichten in einem Ordner abrufen
• Inkrementelle Änderungen an Gruppen abrufen
• Inkrementelle Änderungen an Benutzern abrufen

Wann ist ein Einschreiben zugestellt?

Wie bekomme ich raus von wem ein Einschreiben ist?

Wann wurde mein Brief zugestellt?

Wie kann man die Post verfolgen?