Inkrementelle Änderungen an Nachrichten in einem Ordner abrufenGet incremental changes to messages in a folder

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.Delta query lets you query for additions, deletions, or updates to messages in a folder, by way of a series of delta function calls. Delta data enables you to maintain and synchronize a local store of a user's messages, without having to fetch the entire set of the user's messages from the server every time.

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.Delta query supports both full synchronization that retrieves all of the messages in a folder (for example, the user's Inbox), and incremental synchronization that retrieves all of the messages that have changed in that folder since the last synchronization. Typically, you would do an initial full synchronization of all the messages in a folder, and subsequently, get incremental changes to that folder periodically.

Nachverfolgen von Nachrichtenänderungen in einem OrdnerTrack message changes in a folder

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.Delta query is a per-folder operation. To track the changes of the messages in a folder hierarchy, you need to track each folder individually.

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:Tracking message changes in a mail folder typically is a round of one or more GET requests with the delta function. The initial GET request is very much like the way you get messages, except that you include the delta function:

GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta

Eine GET-Anforderung mit der delta-Funktion gibt Folgendes zurück:A GET request with the delta function returns either:

  • nextLink (mit einer URL mit einem delta-Funktionsaufruf und einem skipToken) oderA nextLink (that contains a URL with a delta function call and a skipToken), or
  • deltaLink (mit einer URL mit einem delta-Funktionsaufruf und einem deltaToken).A deltaLink (that contains a URL with a delta function call and 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.These tokens are state tokens that are completely opaque to the client. To proceed with a round of change tracking, simply copy and apply the URL returned from the last GET request to the next delta function call for the same folder. A deltaLink returned in a response signifies that the current round of change tracking is complete. You can save and use the deltaLink URL when you begin the next round.

Im Beispiel unten finden Sie Informationen zur Verwendung der nextLink- und deltaLink-URLs.See the example below to learn how to use the nextLink and deltaLink URLs.

Verwenden von Abfrageparametern in einer Delta-Abfrage für NachrichtenUse query parameters in a delta query for messages

  • 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.You can use a $select query parameter as in any GET request to specify only the properties your need for best performance. The id property is always returned.
  • Die Delta-Abfrage unterstützt $select, $top und $expand für Nachrichten.Delta query support $select, $top, and $expand for messages.
  • Es besteht eingeschränkte Unterstützung für $filter und $orderby:There is limited support for $filter and $orderby:
    • Es werden nur die $filter-Ausdrücke $filter=receivedDateTime+ge+{value} oder $filter=receivedDateTime+gt+{value} unterstützt.The only supported $filter expressions are $filter=receivedDateTime+ge+{value} or $filter=receivedDateTime+gt+{value}.
    • 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.The only supported $orderby expression is $orderby=receivedDateTime+desc. If you do not include an $orderby expression, the return order is not guaranteed.
  • $search wird nicht unterstützt.There is no support for $search.

Optionaler AnforderungsheaderOptional request header

Jede GET-Anforderung der Delta-Abfrage gibt eine Sammlung aus einer oder mehreren Nachrichten in der Antwort zurück.Each delta query GET request returns a collection of one or more messages in the response. Sie können optional den Anforderungsheader, Prefer: odata.maxpagesize={x}, angeben, um die maximale Anzahl an Nachrichten in einer Antwort festzulegen.You can optionally specify the request header, Prefer: odata.maxpagesize={x}, to set the maximum number of messages in a response.

Beispiel für die Synchronisierung von Nachrichten in einem OrdnerExample to synchronize messages in a folder

Das folgende Beispiel zeigt zwei Synchronisierungsvorgänge für einen bestimmten Ordner, der anfänglich fünf Nachrichten enthält.The following example shows 2 rounds of synchronization of a specific folder which initially contains 5 messages.

Der erste Vorgang umfasst eine Reihe von drei Anforderungen zur Synchronisierung aller fünf Nachrichten im Ordner:The first round involves a series of 3 requests to synchronize all 5 messages in the folder:

Nach dem ersten Vorgang wird eine der Nachrichten gelöscht und eine andere als gelesen markiert.After the first round, one of the messages is deleted, and another is marked as read. 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.The second round of synchronization returns only the delta (the deletion and update), without returning the other messages that have remained the same.

Beispiel für ursprüngliche AnforderungSample initial request

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.In this example, the specified folder is being synchronized for the first time, so the initial sync request does not include any state token. This round will return all the messages in that folder.

Die erste Anforderung gibt Folgendes an:The first request specifies the following:

  • einen $select-Parameter zum Zurückgeben der Eigenschaften subject, sender und isRead für jede Nachricht in der Antwort.A $select parameter to return the subject, sender, and isRead properties for each message in the response.
  • Den optionalen Anforderungsheader, odata.maxpagesize, der gleichzeitig 2 Nachrichten zurückgibt.The optional request header, odata.maxpagesize, returning 2 messages at a time.
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 AntwortSample initial response

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.The response includes two messages and an @odata.nextLink response header. The nextLink URL indicates there are more messages in the folder to get.

{
  "@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.onmicrosoft.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.onmicrosoft.com"
        }
      },
      "id": "AQMkADNkNAAAVRMKAAAAA=="
    }
  ]
}

Beispiel für zweite AnforderungSample second request

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.The second request specifies the nextLink URL returned from the previous response. Notice that it no longer has to specify the same $select parameter as in the initial request, as the skipToken in the nextLink URL encodes and includes it.

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 AntwortSample second response

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.The second response returns the next 2 messages in the folder and another nextLink, indicating there are more messages to get from the folder.

{
  "@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.onmicrosoft.com"
        }
      },
      "id": "AQMkADNkNAAAgWJAAAA"
    }
  ]
}

Beispiel für dritte AnforderungSample third request

Die dritte Anforderung verwendet weiterhin die neueste aus der letzten Synchronisierungsanforderung zurückgegebene nextLink-URL.The third request continues to use the latest nextLink URL returned from the last sync request.

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 AntwortSample third and final response

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.The third response returns the only remaining message in the folder, and a deltaLink URL which indicates synchronization is complete for the time being for this folder. Save and use the deltaLink URL to synchronize the same folder in the next round.

{
  "@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 VorgangSynchronize messages in the same folder in the next round

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:Using the deltaLink from the last request in the last round, you will be able to get only those messages that have changed (by being added, deleted, or updated) in that folder since then. Your first request in the next round will look like the following, assuming you prefer to keep the same maximum page size in the response:

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 deltaLink.The response contains a deltaLink. Dies weist darauf hin, dass alle Änderungen im entfernten Nachrichtenordner jetzt synchronisiert sind.This indicates that all changes in the remote mail folder are now synchronized. Eine Nachricht wurde gelöscht und die andere Nachricht wurde geändert.One message was deleted and the other message was changed.

{
  "@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.onmicrosoft.com"
        }
      },
      "id": "AAMkADNkNAAASq35xAAA="
    }
  ]
}

Siehe auchSee also