フォルダー内のメッセージへの増分の変更を取得する

[アーティクル]
02/13/2024

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

ローカルストア内のメッセージ項目を同期すると、最初の完全同期とその後の増分同期に デルタ クエリを使用できます。通常、フォルダー内のすべてのメッセージ (ユーザーの受信トレイなど) の初期完全同期を行い、そのフォルダーに対する増分変更を定期的に取得します。

最初の同期以降に作成、更新、または削除された特定の種類のメッセージのみの増分変更を取得するには、フォルダー内のすべてのメッセージの初期同期を行い、後続のラウンドで特定の目的の種類の増分変更を取得します。最初のデルタ要求でクエリオプションとして目的の変更の種類を指定します。Microsoft Graph は、OData およびカスタムクエリオプションを応答で指定された @odata.deltaLink に@odata.nextLink自動的にエンコードします。

フォルダー内のメッセージの変更を追跡する

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

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

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

デルタ関数を使用した GET 要求は、次のいずれかを返します。

@odata.nextLink (デルタ関数の呼び出しと skipToken を使用した URL を含む)、または
@odata.deltaLink (デルタ関数の呼び出しと deltaToken を使用した URL を含む)。

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

この記事の残りの部分には、次の 2 つの例が含まれています。

URL と @odata.deltaLink URL の使用方法@odata.nextLinkについては、例 1 を参照してください。
最初のラウンド以降に作成されたメッセージのみを段階的に取得する方法については、例 2 を参照してください。

メッセージのデルタクエリでクエリパラメーターを使用する

GET 要求と同様にクエリパラメーターを $select 使用して、最適なパフォーマンスを得るために必要なプロパティのみを指定できます。プロパティは id 常に返されます。
デルタクエリは、メッセージの $select、$top、および $expand をサポートします。
$filter と $orderby に対するサポートには制限があります。
- サポートされている唯一の $filter 式は、$filter=receivedDateTime+ge+{value} または $filter=receivedDateTime+gt+{value} です。
- デルタクエリに $filter を適用すると、最大 5,000 件のメッセージが返されます。
- サポートされている唯一の $orderby 式は、$orderby=receivedDateTime+desc です。式を $orderby 含めない場合、戻り値の順序は保証されません。
$search に対するサポートはありません。

さらに、デルタクエリの応答で特定の種類の変更 (作成、更新、または削除) のみを返すには、必要に応じて、カスタムクエリオプション changeTypeを使用して目的の種類の変更をフィルター処理できます。指定できる値は、 created、 updated または 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

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

各デルタクエリの GET 要求は、応答で 1 つ以上のメッセージのコレクションを返します。必要に応じて、要求ヘッダー Prefer: odata.maxpagesize={x} を指定して、応答内の最大メッセージ数を設定できます。

例 1: フォルダー内のメッセージを同期する

次の例では、初めに 5 件のメッセージを含む特定のフォルダーを 2 回同期しています。

最初のラウンドには、フォルダー内の 5 つのメッセージをすべて同期するための一連の 3 つの要求が含まれます。

サンプルの最初の要求と応答
サンプルの 2 番目の要求と応答
サンプルの 3 番目の要求と最後の応答

最初のラウンドの後、メッセージの 1 つが削除され、別の 1 つのメッセージが既読としてマークされます。同期の 2 回目のラウンドでは、変更されていない他のメッセージは返さず、デルタ (削除と更新) のみを返します。

最初の要求のサンプル

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

最初の要求では、次のものを指定しています。

応答の各メッセージの subject プロパティ、sender プロパティ、isRead プロパティを返す $select パラメーター。
オプションの要求ヘッダーである odata.maxpagesize。一度に 2 通のメッセージを返すよう指定しています。

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2

最初の応答のサンプル

応答には、2 つのメッセージと応答ヘッダーが @odata.nextLink 含まれます。 URL は、取得するフォルダーにさらにメッセージがあることを示します。

{
  "@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=="
    }
  ]
}

2 番目の要求のサンプル

2 番目の要求では、前の応答で返された @odata.nextLink URL が指定されます。 URL 内のと同じパラメーターがエンコードされて含まれるのskipTokenで、最初の要求と同じ$selectパラメーターを@odata.nextLink指定する必要がなくなりました。

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM HTTP/1.1
Prefer: odata.maxpagesize=2

2 番目の応答のサンプル

2 番目の応答は、フォルダーから取得するメッセージがまだあることを示す、フォルダー内の次の 2 つのメッセージと別の @odata.nextLink を返します。

{
  "@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"
    }
  ]
}

3 番目の要求のサンプル

3 番目の要求は、最後の同期要求から返された最新の @odata.nextLink URL を引き続き使用します。

GET https://graph.microsoft.com/v1.0/me/mailFolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU HTTP/1.1
Prefer: odata.maxpagesize=2

3 番目と最後の応答のサンプル

3 番目の応答は、フォルダー内の残りの唯一のメッセージと @odata.deltaLink 、このフォルダーの同期が完了したことを示す URL を返します。 URL を @odata.deltaLink 保存して使用して、次のラウンドで同じフォルダーを同期します。

{
  "@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="
    }
  ]
}

次のラウンドで同じフォルダー内のメッセージを同期する

@odata.deltaLink最後のラウンドの最後の要求からを使用すると、そのフォルダー内で変更 (追加、削除、または更新) されたメッセージのみを取得できます。次のラウンドの最初の要求は、同じ最大ページサイズを維持することを前提とすると、次のようになります。

GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY HTTP/1.1
Prefer: odata.maxpagesize=2

応答には @odata.deltaLink が含まれます。これは、リモートメールフォルダー内のすべての変更が同期されていることを示します。 1 つのメッセージは削除され、その他のメッセージは変更されました。

{
  "@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="
    }
  ]
}

例 2: 変更の種類に基づいてフォルダー内のメッセージを同期する

次の例は、最初の同期以降に特定のフォルダーに作成されたメッセージのみを取得する方法を示しています。この例では、最初に 4 つのメッセージを含むフォルダーの同期を 2 回行います。

最初のラウンドでは、フォルダー内のすべての 4 つのメッセージを同期するための一連の 2 つの要求が含まれます。

指定された変更の種類と応答を持つサンプルの初期要求
指定された変更の種類と応答を含む 2 番目の要求のサンプル

最初のラウンドの後、さらに 2 つのメッセージが作成され、1 つのメッセージが削除され、もう 1 つのメッセージが読み取りとしてマークされます。

2 回目の同期では、変更の種類 (作成された 2 つの新しいメッセージ) のフォルダー内の created 変更のみが返されます。最後の同期以降も同じ、削除、または更新された他のメッセージは返されません。

指定された変更の種類を持つサンプルの初期要求

最初の要求では、次のものを指定しています。

後続の changeType デルタ応答で作成されたメッセージのみを返すパラメーター。
応答の各メッセージの subject プロパティ、sender プロパティ、isRead プロパティを返す $select パラメーター。
オプションの要求ヘッダーである odata.maxpagesize。一度に 2 通のメッセージを返すよう指定しています。

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

指定された変更の種類を持つサンプルの初期応答

応答には、2 つのメッセージと応答ヘッダーが @odata.nextLink 含まれます。 URL は、取得するフォルダーにさらにメッセージがあることを示します。

{
    "@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"
                }
            }
        }
    ]
}

指定された変更の種類を持つ 2 番目の要求のサンプル

2 番目の要求では、前の応答で返された @odata.nextLink URL が指定されます。 URL 内のがエンコードして含めるので、skipToken最初の要求と同じ$selectまたはchangeTypeパラメーターを@odata.nextLink指定する必要がなくなったことに注意してください。

GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs HTTP/1.1
Prefer: odata.maxpagesize=2

指定された変更の種類を持つ 2 番目の応答のサンプル

2 番目の応答は、フォルダー内の次の 2 つのメッセージと、 @odata.deltaLink このフォルダーの同期が完了したことを示す URL を返します。 URL を @odata.deltaLink 保存して使用して、次のラウンドで同じフォルダーを同期します。

{
    "@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"
                }
            }
        }
    ]
}

指定した変更の種類に基づいて、次のラウンドで同じフォルダー内のメッセージを同期する

@odata.deltaLink最後のラウンドの最後の応答からを使用すると、そのフォルダーに追加されたメッセージのみを取得できます。次のラウンドの最初の要求は、同じ最大ページサイズを維持することを前提とすると、次のようになります。

GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8 HTTP/1.1
Prefer: odata.maxpagesize=2

応答には @odata.deltaLink が含まれます。これは、リモートメールフォルダー内のすべての変更が同期されていることを示します。前回の同期以降に 2 つのメッセージが追加されました。最後の同期以降に更新 & 削除されたメッセージは、この差分応答では返されません。

{
    "@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"
                }
            }
        }
    ]
}

フォルダー内のメッセージへの増分の変更を取得する

フォルダー内のメッセージの変更を追跡する

メッセージのデルタクエリでクエリパラメーターを使用する

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

例 1: フォルダー内のメッセージを同期する

最初の要求のサンプル

最初の応答のサンプル

2 番目の要求のサンプル

2 番目の応答のサンプル

3 番目の要求のサンプル

3 番目と最後の応答のサンプル

次のラウンドで同じフォルダー内のメッセージを同期する

例 2: 変更の種類に基づいてフォルダー内のメッセージを同期する

指定された変更の種類を持つサンプルの初期要求

指定された変更の種類を持つサンプルの初期応答

指定された変更の種類を持つ 2 番目の要求のサンプル

指定された変更の種類を持つ 2 番目の応答のサンプル

指定した変更の種類に基づいて、次のラウンドで同じフォルダー内のメッセージを同期する

フィードバック

フィードバック

その他のリソース

フォルダー内のメッセージへの増分の変更を取得する

フォルダー内のメッセージの変更を追跡する

メッセージのデルタ クエリでクエリ パラメーターを使用する

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

例 1: フォルダー内のメッセージを同期する

最初の要求のサンプル

最初の応答のサンプル

2 番目の要求のサンプル

2 番目の応答のサンプル

3 番目の要求のサンプル

3 番目と最後の応答のサンプル

次のラウンドで同じフォルダー内のメッセージを同期する

例 2: 変更の種類に基づいてフォルダー内のメッセージを同期する

指定された変更の種類を持つサンプルの初期要求

指定された変更の種類を持つサンプルの初期応答

指定された変更の種類を持つ 2 番目の要求のサンプル

指定された変更の種類を持つ 2 番目の応答のサンプル

指定した変更の種類に基づいて、次のラウンドで同じフォルダー内のメッセージを同期する

関連コンテンツ

フィードバック

フィードバック

その他のリソース

メッセージのデルタクエリでクエリパラメーターを使用する