フォルダー内のメッセージへの増分の変更を取得するGet incremental changes to messages in a folder

デルタ クエリでは、一連のデルタ関数呼び出しを使用して、フォルダー内のメッセージへの追加、削除、または更新に対してクエリを実行できます。デルタ データを使用すると、毎回サーバーからユーザーのメッセージのセット全体をフェッチせずに、ユーザーのメッセージのローカル ストアの保守と同期が行えます。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.

デルタ クエリでは、フォルダー内 (ユーザーの受信トレイなど) のすべてのメッセージを取得する完全な同期と、最後の同期以降、そのフォルダー内で変更されたすべてのメッセージを取得する増分同期の両方がサポートされています。通常は、フォルダー内のすべてのメッセージの最初の完全同期を実行して、その後、そのフォルダーの増分の変更を定期的に取得します。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.

フォルダー内のメッセージの変更を追跡するTrack message changes in a folder

デルタ クエリはフォルダー単位の操作です。フォルダー階層内のメッセージの変更を追跡するには、各フォルダーを個別に追跡する必要があります。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.

通常、メール フォルダー内のメッセージ変更の追跡は、デルタ関数を使用した、1 つ以上の GET 要求のラウンドです。最初の GET 要求は、デルタ関数を含めることを除いて、メッセージの取得方法とほぼ同じです。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

デルタ関数を使用した GET 要求は、次のいずれかを返します。A GET request with the delta function returns either:

  • nextLink (デルタ関数の呼び出しと skipToken を使用した URL を含む)、またはA nextLink (that contains a URL with a delta function call and a skipToken), or
  • deltaLink (デルタ関数の呼び出しと deltaToken を使用した URL を含む)。A deltaLink (that contains a URL with a delta function call and deltaToken).

これらのトークンは、クライアントに対して完全に不透明な状態トークンです。変更追跡のラウンドを続行する手順は、最後の GET 要求から返された URL を、同じフォルダーの次のデルタ関数呼び出しにコピーして適用するだけです。応答で返される deltaLink は、変更追跡の現在のラウンドが完了したことを示します。deltaLink URL を保存して、次のラウンドを開始する際に使用することができます。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.

nextLinkdeltaLink の URL を使用する方法については、以下のを参照してください。See the example below to learn how to use the nextLink and deltaLink URLs.

メッセージのデルタ クエリでクエリ パラメーターを使用するUse query parameters in a delta query for messages

  • 任意の GET リクエストと同様に $select クエリ パラメーターを使用して、最善のパフォーマンスを得るために必要なプロパティのみを指定することができます。id プロパティは常に返されます。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.
  • デルタ クエリは、メッセージの $select$top、および $expand をサポートします。Delta query support $select, $top, and $expand for messages.
  • $filter$orderby に対するサポートには制限があります。There is limited support for $filter and $orderby:
    • サポートされている唯一の $filter 式は、$filter=receivedDateTime+ge+{value} または $filter=receivedDateTime+gt+{value} です。The only supported $filter expressions are $filter=receivedDateTime+ge+{value} or $filter=receivedDateTime+gt+{value}.
    • サポートされている唯一の $orderby 式は、$orderby=receivedDateTime+desc です。$orderby 式を含めない場合、戻り値の順序は保証されません。The only supported $orderby expression is $orderby=receivedDateTime+desc. If you do not include an $orderby expression, the return order is not guaranteed.
  • $search に対するサポートはありません。There is no support for $search.

オプションの要求ヘッダーOptional request header

各デルタ クエリの GET 要求は、応答で 1 つ以上のメッセージのコレクションを返します。Each delta query GET request returns a collection of one or more messages in the response. 必要に応じて、要求ヘッダー Prefer: odata.maxpagesize={x} を指定して、応答内の最大メッセージ数を設定できます。You can optionally specify the request header, Prefer: odata.maxpagesize={x}, to set the maximum number of messages in a response.

ファルダー内のメッセージを同期する例Example to synchronize messages in a folder

次の例では、最初に 5 つのメッセージを含んでいる特定のフォルダーの同期の 2 つのラウンドを示します。The following example shows 2 rounds of synchronization of a specific folder which initially contains 5 messages.

最初のラウンドには、フォルダー内の 5 つのメッセージをすべて同期するための一連の 3 つの要求が含まれます。The first round involves a series of 3 requests to synchronize all 5 messages in the folder:

最初のラウンドの後、メッセージの 1 つが削除され、別の 1 つのメッセージが既読としてマークされます。After the first round, one of the messages is deleted, and another is marked as read. 同期の 2 回目のラウンドでは、変更されていない他のメッセージは返さず、デルタ (削除と更新) のみを返します。The second round of synchronization returns only the delta (the deletion and update), without returning the other messages that have remained the same.

最初の要求のサンプルSample initial request

この例では、指定されたフォルダーは初めて同期されるため、最初の同期要求には状態トークンは含まれません。このラウンドは、そのフォルダー内のすべてのメッセージを返します。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.

最初の要求では、次のものを指定しています。The first request specifies the following:

  • 応答の各メッセージの subject プロパティ、sender プロパティ、isRead プロパティを返す $select パラメーター。A $select parameter to return the subject, sender, and isRead properties for each message in the response.
  • オプションの要求ヘッダーである odata.maxpagesize。一度に 2 通のメッセージを返すよう指定しています。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

最初の応答のサンプルSample initial response

応答には、2 つのメッセージと @odata.nextLink 応答ヘッダーが含まれています。nextLink URL は、取得するフォルダーにさらにメッセージがあることを示します。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=="
    }
  ]
}

2 番目の要求のサンプルSample second request

2 番目の要求では、前の応答で返された nextLink URL を指定します。最初の要求にあるような同じ $select パラメーターを指定する必要はなくなりましたのでご注意ください。これは、nextLink URL の skipToken によってこのパラメーターがエンコードされて含まれるためです。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

2 番目の応答のサンプルSample second response

2 番目の応答は、フォルダーから取得するメッセージがまだあることを示す、フォルダー内の次の 2 つのメッセージと別の nextLink を返します。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"
    }
  ]
}

3 番目の要求のサンプルSample third request

3 番目の要求は、最後の同期要求から返された最新の 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

3 番目と最後の応答のサンプルSample third and final response

3 番目の応答では、フォルダーに残っている 1 つだけのメッセージと、そのフォルダーの同期が当面の間完了していることを示す deltaLink URL が返されます。deltaLink URL を保存して、次のラウンドで同じフォルダーを同期するために使用します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="
    }
  ]
}

次のラウンドで同じフォルダー内のメッセージを同期するSynchronize messages in the same folder in the next round

最後のランドの最後の応答からの deltaLink を使用すると、それ以降にそのフォルダーで (追加、削除、または更新によって) 変更されたこれらのメッセージのみを取得できます。次のラウンドの最初の要求は、同じ最大ページ サイズを維持することを前提とすると、次のようになります。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

応答には deltaLink が含まれます。The response contains a deltaLink. これは、リモート メール フォルダー内のすべての変更が同期されていることを示します。This indicates that all changes in the remote mail folder are now synchronized. 1 つのメッセージは削除され、その他のメッセージは変更されました。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="
    }
  ]
}

関連項目See also