Inkrementelle Änderungen an Nachrichten in einem Ordner abrufen (Vorschau)

Mit der Delta-Abfrage können Sie Ergänzungen, Löschungen oder Aktualisierungen an Nachrichten in einem Ordner anhand einer Serie von Delta-Funktionsaufrufen abfragen. Mit Delta-Daten können Sie einen lokalen Speicher für Nachrichten eines Benutzers pflegen und synchronisieren, ohne dass Sie jedes Mal den gesamten Nachrichtensatz vom Server abrufen müssen.

Die Delta-Abfrage unterstützt die vollständige Synchronisierung, die alle Nachrichten in einem Ordner abruft (z. B. im Posteingang des Benutzers), und die inkrementelle Synchronisierung, die alle Nachrichten abruft, die seit der letzten Synchronisierung in diesem Ordner geändert wurden. In der Regel führen Sie erst eine vollständige Synchronisierung aller Nachrichten in einem Ordner durch und rufen anschließend regelmäßig inkrementelle Änderungen an dem Ordner ab.

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/beta/me/mailFolders/{id}/messages/delta

Eine GET-Anforderung mit der delta-Funktion gibt Folgendes zurück:

  • nextLink (mit einer URL mit einem delta-Funktionsaufruf und einem skipToken) oder
  • deltaLink (mit einer URL mit einem delta-Funktionsaufruf und einem deltaToken).

Diese Token sind Statustoken, die für den Client nicht transparent sind. Um mit einer Änderungsnachverfolgung fortzufahren, kopieren Sie die von der letzten GET-Anforderung zurückgegebene URL einfach und wenden sie auf den nächsten delta-Funktionsaufruf für denselben Ordner an. deltaLink (in einer Antwort zurückgegeben), bedeutet, dass die aktuelle Runde der Änderungsnachverfolgung abgeschlossen ist. Sie können die deltaLink-URL für die nächste Runde speichern und verwenden.

Im Beispiel unten finden Sie Informationen zur Verwendung der nextLink- und deltaLink-URLs.

Verwenden von Abfrageparametern in einer Delta-Abfrage für Nachrichten

  • 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.
  • Die Delta-Abfrage unterstützt $select, $top und $expand für Nachrichten.
  • Es besteht eingeschränkte Unterstützung für $filter und $orderby:
    • Es werden nur die $filter-Ausdrücke $filter=receivedDateTime+ge+{value} oder $filter=receivedDateTime+gt+{value} unterstützt.
    • Es wird nur der $orderby-Ausdruck $orderby=receivedDateTime+desc unterstützt. Wenn Sie keinen $orderby-Ausdruck einschließen, ist die Rückgabereihenfolge nicht gewährleistet.
  • $search wird nicht unterstützt.

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 für die Synchronisierung von Nachrichten in einem Ordner

Das folgende Beispiel zeigt eine Reihe von 3 Anforderungen zum Synchronisieren eines bestimmten Ordners, der 5 Nachrichten enthält:

Sehen Sie sich auch an, was Sie in der nächsten Runde tun werden.

Beispiel für ursprüngliche Anforderung

In diesem Beispiel wird der angegebene Ordner zum ersten Mal synchronisiert, sodass die ursprüngliche Synchronisierungsanforderung kein Statustoken enthält. In dieser Runde werden alle Nachrichten in diesem Ordner zurückgegeben.

Die erste Anforderung gibt Folgendes an:

  • Einen Parameter $select zum Zurückgeben der Eigenschaften Subject und Sender für jede Nachricht in der Antwort.
  • Den optionalen Anforderungsheader, odata.maxpagesize, der gleichzeitig 2 Nachrichten zurückgibt.
GET https://graph.microsoft.com/beta/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$select=Subject,Sender 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 nextLink-URL zeigt an, dass weitere abzurufende Nachrichten in dem Ordner vorhanden sind.

{
    "@odata.context":"https://graph.microsoft.com/beta/$metadata#Collection(message)",
    "@odata.nextLink":"https://graph.microsoft.com/beta/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM",
    "value":[
        {
            "@odata.type":"#microsoft.graph.message",
            "@odata.etag":"W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
            "subject":"Holiday hours update",
            "sender":{
                "emailAddress":{
                    "name":"Dana Swope",
                    "address":"danas@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADNkNAAASq35xAAA="
        },
        {
            "@odata.type":"#microsoft.graph.message",
            "@odata.etag":"W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB/\"",
            "subject":"Holiday promotion sale",
            "sender":{
                "emailAddress":{
                    "name":"Fanny Downs",
                    "address":"fannyd@contoso.onmicrosoft.com"
                }
            },
            "id":"AQMkADNkNAAAVRMKAAAAA=="
        }
    ]
}

Beispiel für zweite Anforderung

Die zweite Anforderung gibt die aus der vorherigen Antwort zurückgegebene nextLink-URL an. Beachten Sie, dass sie nicht denselben Parameter $select wie in der ursprünglichen Anforderung angeben muss, da das skipToken in der nextLink-URL es codiert und einschließt.

GET https://graph.microsoft.com/beta/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 nextLink, was bedeutet, dass weitere abzurufende Nachrichten in dem Ordner vorhanden sind.

{
    "@odata.context":"https://graph.microsoft.com/beta/$metadata#Collection(message)",
    "@odata.nextLink":"https://graph.microsoft.com/beta/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU",
    "value":[
        {
            "@odata.type":"#microsoft.graph.message",
            "@odata.etag":"W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB+\"",
            "subject":"New or modified user account information",
            "sender":{
                "emailAddress":{
                    "name":"Randi Welch",
                    "address":"randiw@contoso.onmicrosoft.com"
                }
            },
            "id":"AQMkADNkNAAAgWJAAAA"
        },
        {
            "@odata.type":"#microsoft.graph.message",
            "@odata.etag":"W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB9\"",
            "subject":"New or modified user account information",
            "sender":{
                "emailAddress":{
                    "name":"Randi Welch",
                    "address":"randiw@contoso.onmicrosoft.com"
                }
            },
            "id":"AQMkADNkNAAAgWHAAAA"
        }
    ]
}

Beispiel für dritte Anforderung

Die dritte Anforderung verwendet weiterhin die neueste aus der letzten Synchronisierungsanforderung zurückgegebene nextLink-URL.

GET https://graph.microsoft.com/beta/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 in dem Ordner verbleibende Nachricht zurück sowie eine deltaLink-URL zurück, was bedeutet, dass die Synchronisierung für diesen Ordner momentan abgeschlossen ist. Speichern und verwenden Sie die deltaLink-URL, um den gleichen Ordner in der nächsten Runde zu synchronisieren.

{
    "@odata.context":"https://graph.microsoft.com/beta/$metadata#Collection(message)",
    "@odata.deltaLink":"https://graph.microsoft.com/beta/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
    "value":[
        {
            "@odata.type":"#microsoft.graph.message",
            "@odata.etag":"W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB8\"",
            "subject":"You've joined the Customer Manager group",
            "sender":{
                "emailAddress":{
                    "name":"Customer Managers team",
                    "address":"customer_managers@contoso.onmicrosoft.com"
                }
            },
            "id":"AQMkADNkNAAAgWFAAAA"
        }
    ]
}

Die nächste Runde

Mit dem 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 (durch Hinzufügung, Löschung oder Aktualisierung). 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/beta/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY HTTP/1.1
Prefer: odata.maxpagesize=2

Siehe auch