Inkrementelle Änderungen an Nachrichten in einem Ordner abrufen
Mit der Deltaabfrage können Sie Ergänzungen, Löschungen oder Aktualisierungen an Nachrichten in einem Ordner anhand einer Serie von Aufrufen der Funktion delta abfragen. Mit Deltadaten können Sie einen lokalen Speicher für Nachrichten eines Benutzers pflegen und synchronisieren, ohne dass Sie jedes Mal den gesamten Nachrichtensatz des Benutzers vom Server abrufen müssen.
Beim Synchronisieren von Nachrichtenelementen in einem lokalen Speicher kann die Deltaabfrage für die erste vollständige Synchronisierung und nachfolgende inkrementelle Synchronisierungen verwendet werden. In der Regel führen Sie eine anfängliche vollständige Synchronisierung aller Nachrichten in einem Ordner (z. B. im Posteingang des Benutzers) durch und rufen dann in regelmäßigen Abständen inkrementelle Änderungen an diesem Ordner ab.
Um inkrementelle Änderungen nur eines bestimmten Typs ( Nachrichten, die seit der ersten Synchronisierung erstellt, aktualisiert oder gelöscht wurden) abzurufen, führen Sie eine erste Synchronisierung aller Nachrichten im Ordner durch und rufen dann inkrementelle Änderungen eines bestimmten gewünschten Typs in nachfolgenden Runden ab. Geben Sie den gewünschten Änderungstyp als Abfrageoption in der anfänglichen Deltaanforderung an. Microsoft Graph codiert automatisch alle OData- und benutzerdefinierten Abfrageoptionen in oder in @odata.nextLink@odata.deltaLink der Antwort angegeben.
Nachverfolgen von Nachrichtenänderungen in einem Ordner
Die Delta-Abfrage wird jeweils für einen Ordner durchgeführt. Um die Änderungen der Nachrichten in einer Ordnerhierarchie nachzuverfolgen, müssen Sie jeden Ordner einzeln nachverfolgen.
Das Nachverfolgen von Nachrichtenänderungen in einem Ordner ist in der Regel eine Runde aus einer oder mehreren GET-Anforderungen mit der Delta-Funktion. Die ursprüngliche GET-Anforderung wird ähnlich wie das Abrufen von Nachrichten durchgeführt, außer dass die folgende delta-Funktion eingeschlossen wird:
GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta
Eine GET-Anforderung mit der delta-Funktion gibt Folgendes zurück:
@odata.nextLink(mit einer URL mit einem delta-Funktionsaufruf und einem skipToken) oder@odata.deltaLink(mit einer URL mit einem delta-Funktionsaufruf und einem deltaToken).
Diese Token sind Zustandstoken , die für den Client nicht transparent sind.
Um mit einer Runde der Änderungsnachverfolgung fortzufahren, kopieren Sie die url, die von der letzten GET-Anforderung zurückgegeben wurde, und wenden Sie sie auf den nächsten Delta-Funktionsaufruf für denselben Ordner an. @odata.deltaLink (in einer Antwort zurückgegeben), bedeutet, dass die aktuelle Runde der Änderungsnachverfolgung abgeschlossen ist. Sie können die @odata.deltaLink-URL für die nächste Runde speichern und verwenden.
Der Rest dieses Artikels enthält 2 Beispiele:
- In Beispiel 1 erfahren Sie, wie Sie die
@odata.nextLinkURLs und@odata.deltaLinkverwenden. - In Beispiel 2 erfahren Sie, wie Sie inkrementell nur Nachrichten abrufen, die seit der ersten Runde erstellt wurden.
Verwenden von Abfrageparametern in einer Delta-Abfrage für Nachrichten
- Sie können wie bei jeder GET-Anforderung den Abfrageparameter
$selectverwenden, um zwecks Leistungsoptimierung nur die benötigten Eigenschaften anzugeben. Dieid-Eigenschaft wird immer zurückgegeben. - Die Delta-Abfrage unterstützt
$select,$topund$expandfür Nachrichten. - Es besteht eingeschränkte Unterstützung für
$filterund$orderby:- Es werden nur die
$filter-Ausdrücke$filter=receivedDateTime+ge+{value}oder$filter=receivedDateTime+gt+{value}unterstützt. - Wenn Sie
$filterin einer Delta-Abfrage anwenden, werden nur bis zu 5.000 Nachrichten zurückgegeben. - Es wird nur der
$orderby-Ausdruck$orderby=receivedDateTime+descunterstützt. Wenn Sie keinen Ausdruck einschließen$orderby, ist die Rückgabereihenfolge nicht garantiert.
- Es werden nur die
$searchwird nicht unterstützt.
Um in der Antwort der Deltaabfrage nur bestimmte Änderungen (erstellt, aktualisiert oder gelöscht) zurückzugeben, können Sie optional den gewünschten Änderungstyp mithilfe einer benutzerdefinierten Abfrageoption changeTypefiltern. Mögliche Werte sind created, updated oder deleted.
GET /me/mailfolders/{id}/messages/delta?changeType=created
GET /me/mailfolders/{id}/messages/delta?changeType=updated
GET /me/mailfolders/{id}/messages/delta?changeType=deleted
Optionaler Anforderungsheader
Jede GET-Anforderung der Delta-Abfrage gibt eine Sammlung aus einer oder mehreren Nachrichten in der Antwort zurück. Sie können optional den Anforderungsheader, Prefer: odata.maxpagesize={x}, angeben, um die maximale Anzahl an Nachrichten in einer Antwort festzulegen.
Beispiel 1: Synchronisieren von Nachrichten in einem Ordner
Das folgende Beispiel zeigt zwei Synchronisierungsvorgänge für einen bestimmten Ordner, der anfänglich fünf Nachrichten enthält.
Der erste Vorgang umfasst eine Reihe von drei Anforderungen zur Synchronisierung aller fünf Nachrichten im Ordner:
- Beispiel für ursprüngliche Anforderung und Antwort
- Beispiel für zweite Anforderung und Antwort
- Beispiel für dritte Anforderung und letzte Antwort
Nach dem ersten Vorgang wird eine der Nachrichten gelöscht und eine andere als gelesen markiert. Beim zweiten Synchronisierungsvorgang wird nur das Delta (die Löschung und Aktualisierung) zurückgegeben. Die anderen Nachrichten, die sich nicht geändert haben, werden nicht zurückgegeben.
Beispiel für ursprüngliche Anforderung
In diesem Beispiel wird der angegebene Ordner zum ersten Mal synchronisiert, sodass die anfängliche Synchronisierungsanforderung kein Zustandstoken enthält. Diese Runde gibt alle Nachrichten in diesem Ordner zurück.
Die erste Anforderung gibt Folgendes an:
- einen
$select-Parameter zum Zurückgeben der Eigenschaftensubject,senderundisReadfür jede Nachricht in der Antwort. - Den optionalen Anforderungsheader, odata.maxpagesize, der gleichzeitig 2 Nachrichten zurückgibt.
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2
Beispiel für ursprüngliche Antwort
Die Antwort enthält zwei Nachrichten und einen @odata.nextLink-Antwortheader.
Die @odata.nextLink-URL zeigt an, dass weitere abzurufende Nachrichten in dem Ordner vorhanden sind.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
"subject": "Holiday hours update",
"isRead": false,
"sender": {
"emailAddress": {
"name": "Dana Swope",
"address": "danas@contoso.com"
}
},
"id": "AAMkADNkNAAASq35xAAA="
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB/\"",
"subject": "Holiday promotion sale",
"isRead": true,
"sender": {
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
},
"id": "AQMkADNkNAAAVRMKAAAAA=="
}
]
}
Beispiel für zweite Anforderung
Die zweite Anforderung gibt die aus der vorherigen Antwort zurückgegebene @odata.nextLink-URL an. Beachten Sie, dass sie nicht denselben Parameter $select wie in der ursprünglichen Anforderung angeben muss, da das skipToken in der @odata.nextLink-URL es codiert und einschließt.
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM HTTP/1.1
Prefer: odata.maxpagesize=2
Beispiel für zweite Antwort
Die zweite Antwort gibt die nächsten 2 Nachrichten in dem Ordner zurück und ein weiteres @odata.nextLink, was bedeutet, dass weitere abzurufende Nachrichten in dem Ordner vorhanden sind.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlqfdAAAEfYB+\"",
"subject": "Microsoft Virtual Academy at Contoso",
"isRead": true,
"sender": {
"emailAddress": {
"name": "Elliot Hyde",
"address": "elliot-hyde@tailspintoys.com"
}
},
"id": "AQMkADNkNAAAgWkAAAA"
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB+\"",
"subject": "New or modified user account information",
"isRead": true,
"sender": {
"emailAddress": {
"name": "Randi Welch",
"address": "randiw@contoso.com"
}
},
"id": "AQMkADNkNAAAgWJAAAA"
}
]
}
Beispiel für dritte Anforderung
Die dritte Anforderung verwendet weiterhin die neueste aus der letzten Synchronisierungsanforderung zurückgegebene @odata.nextLink-URL.
GET https://graph.microsoft.com/v1.0/me/mailFolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU HTTP/1.1
Prefer: odata.maxpagesize=2
Beispiel für dritte und letzte Antwort
Die dritte Antwort gibt die einzige verbleibende Nachricht im Ordner und eine @odata.deltaLink URL zurück, die angibt, dass die Synchronisierung für diesen Ordner vorerst abgeschlossen ist. Speichern und verwenden Sie die @odata.deltaLink-URL, um den gleichen Ordner in der nächsten Runde zu synchronisieren.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzFPjSbaPPxzjlzOTAAAEfYB+\"",
"subject": "Fabric CDN now available",
"isRead": true,
"sender": {
"emailAddress": {
"name": "Jodie Sharp",
"address": "Jodie.Sharp@contoso.com"
}
},
"id": "AAMkADk0MGFkODE3LWEAAA="
}
]
}
Synchronisieren der Nachrichten in demselben Ordner im nächsten Vorgang
Mit dem @odata.deltaLink aus der letzten Anforderung in der letzten Runde können Sie nur die Nachrichten abrufen, die sich seitdem in diesem Ordner geändert haben (indem sie hinzugefügt, gelöscht oder aktualisiert wurden).
Ihre erste Anforderung in der nächsten Runde sieht folgendermaßen aus, sofern Sie die gleiche maximale Seitengröße in der Antwort beibehalten möchten:
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY HTTP/1.1
Prefer: odata.maxpagesize=2
Die Antwort enthält ein @odata.deltaLink. Dies weist darauf hin, dass alle Änderungen im entfernten Nachrichtenordner jetzt synchronisiert sind. Eine Nachricht wurde gelöscht und die andere Nachricht wurde geändert.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS0Dh_6qB-pB2Sa2pUum19a6YAAKnLuxoAAA=",
"@removed": {
"reason": "deleted"
}
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
"subject": "Holiday hours update",
"isRead": "true",
"sender": {
"emailAddress": {
"name": "Dana Swope",
"address": "danas@contoso.com"
}
},
"id": "AAMkADNkNAAASq35xAAA="
}
]
}
Beispiel 2: Synchronisieren von Nachrichten in einem Ordner basierend auf dem Änderungstyp
Das folgende Beispiel zeigt das Abrufen von Nachrichten, die seit der ersten Synchronisierung in einem bestimmten Ordner erstellt wurden. Das Beispiel umfasst zwei Synchronisierungsrunden dieses Ordners, der anfänglich 4 Nachrichten enthält.
Die erste Runde umfasst eine Reihe von zwei Anforderungen, um alle vier Nachrichten im Ordner zu synchronisieren:
- Beispiel für eine anfängliche Anforderung mit angegebenem Änderungstyp und -antwort
- Beispiel für eine zweite Anforderung mit angegebenem Änderungstyp und -antwort
Nach der ersten Runde werden zwei weitere Nachrichten erstellt, eine Nachricht wird gelöscht und eine andere als gelesen markiert.
Die zweite Synchronisierungsrunde gibt nur die Änderungen im Ordner des created Änderungstyps (die beiden neu erstellten Nachrichten) zurück, ohne die anderen Nachrichten zurückzugeben, die seit der letzten Synchronisierung gleich geblieben, gelöscht oder aktualisiert wurden.
Beispiel für eine anfängliche Anforderung mit angegebenem Änderungstyp
In diesem Beispiel wird der angegebene Ordner zum ersten Mal synchronisiert, sodass die anfängliche Synchronisierungsanforderung kein Zustandstoken enthält. Diese Runde gibt alle Nachrichten in diesem Ordner zurück.
Die erste Anforderung gibt Folgendes an:
- Ein
changeTypeParameter, der nur die erstellten Nachrichten in der nachfolgenden Deltaantwort zurückgibt. - einen
$select-Parameter zum Zurückgeben der Eigenschaftensubject,senderundisReadfür jede Nachricht in der Antwort. - Den optionalen Anforderungsheader, odata.maxpagesize, der gleichzeitig 2 Nachrichten zurückgibt.
GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?changeType=created&$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2
Beispiel für die erste Antwort mit dem angegebenen Änderungstyp
Die Antwort enthält zwei Nachrichten und einen @odata.nextLink-Antwortheader.
Die @odata.nextLink-URL zeigt an, dass weitere abzurufende Nachrichten in dem Ordner vorhanden sind.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBP\"",
"subject": "Inline Attachments Again",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LT2fKdhq8oSKEDSVrdi3lRAAIei5gdAAA=",
"sender": {
"emailAddress": {
"name": "Megan Brown",
"address": "Megan.Brown@contoso.com"
}
}
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBR\"",
"subject": "RE: Test Outlook TimeZone",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMKdhq8oSKEDSVrdi3lRAAIei5geAAA=",
"sender": {
"emailAddress": {
"name": "Megan Brown",
"address": "Megan.Brown@contoso.com"
}
}
}
]
}
Beispiel für eine zweite Anforderung mit angegebenem Änderungstyp
Die zweite Anforderung gibt die aus der vorherigen Antwort zurückgegebene @odata.nextLink-URL an. Beachten Sie, dass nicht mehr derselbe $select Parameter oder der changeType Parameter wie in der ursprünglichen Anforderung angegeben werden muss, da der skipToken in der @odata.nextLink URL codiert und enthält.
GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs HTTP/1.1
Prefer: odata.maxpagesize=2
Beispiel für eine zweite Antwort mit angegebenem Änderungstyp
Die zweite Antwort gibt die nächsten 2 Nachrichten im Ordner und @odata.deltaLink die URL zurück, die angibt, dass die Synchronisierung für diesen Ordner vorerst abgeschlossen ist. Speichern und verwenden Sie die @odata.deltaLink-URL, um den gleichen Ordner in der nächsten Runde zu synchronisieren.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBu\"",
"subject": "Your preview of the new Briefing email",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBIJ",
"sender": {
"emailAddress": {
"name": "Cortana",
"address": "cortana@contoso.com"
}
}
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBw\"",
"subject": "Char Coding HTML",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBA=",
"sender": {
"emailAddress": {
"name": "John Doe",
"address": "John.Doe@contoso.com"
}
}
}
]
}
Synchronisieren von Nachrichten im selben Ordner in der nächsten Runde basierend auf dem angegebenen Änderungstyp
Mit der @odata.deltaLink aus der letzten Antwort in der letzten Runde können Sie nur die Nachrichten abrufen, die seitdem in diesem Ordner hinzugefügt wurden.
Ihre erste Anforderung in der nächsten Runde sieht folgendermaßen aus, sofern Sie die gleiche maximale Seitengröße in der Antwort beibehalten möchten:
GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8 HTTP/1.1
Prefer: odata.maxpagesize=2
Die Antwort enthält ein @odata.deltaLink. Dies weist darauf hin, dass alle Änderungen im entfernten Nachrichtenordner jetzt synchronisiert sind. Seit der letzten Synchronisierung wurden zwei Nachrichten hinzugefügt. Die Nachrichten, die seit der letzten Synchronisierung aktualisiert & gelöscht wurden, werden in dieser Deltaantwort nicht zurückgegeben.
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=EPuhZPRDHo-r3EBfscYE444fuGSBRV1eXex3JZkLzT9fRM",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MCP\"",
"subject": "Nested Attachment",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBIJ",
"sender": {
"emailAddress": {
"name": "Patti Fernandez",
"address": "PattiF@contoso.com"
}
}
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MCN\"",
"subject": "Attachment Testing",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwZA=",
"sender": {
"emailAddress": {
"name": "Patti Fernandez",
"address": "PattiF@contoso.com"
}
}
}
]
}
Verwandte Inhalte
Feedback
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 unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für