次の方法で共有


ユーザーに対する増分の変更を取得する

Microsoft Graph のデルタ クエリを使用すると、一連のデルタ要求を使用して、サポートされているリソースへの追加、削除、更新のクエリを実行できます。 ユーザーの場合、デルタ クエリを使用すると、変更を比較するためにユーザーのセット全体をフェッチすることなく、変更を検出できます。

ローカル プロファイル ストアとユーザーを同期させるクライアントは、最初の完全同期とその後の増分同期の両方でデルタ クエリを使用できます。 通常、クライアントはテナント内のすべてのユーザーの初期完全同期を行い、ユーザーに対して定期的に増分変更を取得します。

ユーザーに対する変更を追跡する

delta 関数のある 1 つ以上の GET 要求でユーザーの変更を追跡します。 GET 要求には、次の特性があります。

  • URL パスの前に追加された デルタ 関数。
  • 前の GET デルタ関数呼び出しからの状態トークン (deltatoken または skipToken)。
  • [省略可能]サポートされているクエリ パラメーター

この記事では、ユーザーへの変更を追跡するための一連の要求例を示します。

  1. 最初の要求応答
  2. nextLink 要求応答
  3. 最後の nextLink 要求応答
  4. deltaLink 要求deltaLink 応答

最初の要求

ユーザー リソースの変更を追跡するには、要求を行い、URL セグメントとして delta 関数を含めます。

ヒント

/delta は完全修飾名のショートカットです /microsoft.graph.delta。 Microsoft Graph SDK によって生成された要求では、完全修飾名が使用されます。

以下の項目にご注意ください:

  • オプションの $select クエリ パラメーターが要求に含められているのは、クエリ パラメーターが将来の要求に自動的に含まれる方法を示すためです。 必要に応じて、クエリ パラメーターを最初の要求で指定する必要があります。
    • に含まれる $select プロパティのみが変更のために追跡されます。 が指定されていない場合 $select 、オブジェクトのすべてのプロパティが変更のために追跡されます。
  • 最初の要求には状態トークンは含まれません。 状態トークンは、後続の要求で使用されます。
GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,givenName,surname

最初の応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で user コレクション オブジェクトを返します。 ユーザーのセット全体が大きすぎると仮定すると、応答にはパラメーターに @odata.nextLink 状態トークンが @odata.nextLink 含まれます。

この例では、セッションで取得するデータの追加ページがあることを示す @odata.nextLink URL が返されます。 URL 内の に $skiptoken 注目してください。 最初の要求の $select クエリ パラメーターは @odata.nextLink URL にエンコードされます。

応答には、ID 86462606-fde0-4fc4-9e0c-a20eb73e54c6@removed持つユーザーの注釈も含まれています。 注釈は @removed 、次のシナリオで追加されます。

  • ユーザーが削除されると、項目には "reason": "changed" の値が含まれた @removed のコメントが含まれます。
  • ユーザーが 完全に削除されると、項目に注釈が含まれます。 @removed 値は "reason": "deleted"です。
  • ユーザーが作成されたとき、または削除されたアイテム コンテナーから復元された場合、注釈はありません。
HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users(displayName,givenName,surname)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa",
  "value": [
    {
      "displayName":"Cameron White",
      "givenName":"Cameron",
      "surname":"White",
      "id":"ffff7b1a-13b6-477b-8c0c-380905cd99f7"
    },
    {
      "displayName":"Delia Dennis",
      "givenName":"Delia",
      "surname":"Dennis",
      "id":"605d1257-ffff-40b6-8e6f-528a53f5dc55"
    },
    {
      "id": "86462606-fde0-4fc4-9e0c-a20eb73e54c6",
      "@removed": {
        "reason": "deleted"
      }
    },
    {
      "displayName": "Conf Room Adams",
      "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
    }
  ]
}

2 番目の要求では、前の応答で返された skipToken を指定します。 $select パラメーターがエンコードされ、skipToken に含まれていることに注意してください。

GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa

応答には、別の @odata.nextLink と新しい skipToken 値が含まれています。これは、ユーザーに対して追跡された変更がさらに使用可能であることを示します。 値が空の配列であっても、(@odata.deltaLink パラメーター内の) @odata.deltaLink URL が最終的な応答で返されるまで、@odata.nextLink URL を使用します。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"Mallory Cortez",
      "givenName":"Mallory",
      "surname":"Cortez",
      "id":"d8c37826-ffff-4cae-b348-e2725b1e814b"
    },
    {
      "displayName":"Diego Sicilian",
      "givenName":"Diego",
      "surname":"Sicilian",
      "id":"8b1ee412-cd8f-4d59-ffff-24010edb9f1f"
    }
  ]
}

3 番目の要求では、最後の同期要求から返された最新の skipToken を使用します。

GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7

この応答には、ユーザー オブジェクトの既存の状態に関するデータがないことを示す URL が含まれています @odata.deltaLink 。 今後の要求では、アプリケーションは @odata.deltaLink URL を使用して、ユーザーへのその他の変更点を確認します。 deltatoken を保存し、後続の要求 URL でそれを使用して、ユーザーに対するその他の変更を検出します。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460",
  "value": [
    {
      "displayName":"Lidia Holloway",
      "givenName":"Lidia",
      "surname":"Holloway",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "displayName":"Patti Fernandez",
      "givenName":"Patti",
      "surname":"Fernandez",
      "id":"f6ede700-27d0-4c42-bfb9-4dffff43c74a"
    }
  ]
}

最後の応答から を deltatoken 使用して、 前回の要求以降にユーザーに対する変更 (追加、削除、または更新) を取得します。

GET https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460

変更 @odata.deltaLink がない場合、 は結果なしで返されます。 value プロパティは空の配列です。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=MF1LuFYbK6Lw4DtZ4o9PDrcGekRP65WEJfDmM0H26l4v9zILCPFiPwSAAeRBghxgiwsXEfywcVQ9R8VEWuYAB50Yw3KvJ-8Z1zamVotGX2b_AHVS_Z-3b0NAtmGpod",
  "value": []
}

変更がある場合は、変更されたユーザー オブジェクトのコレクションが含まれます。 さらに応答には、@odata.nextLink (取得対象の変更のページが複数ある場合) と @odata.deltaLink のどちらかも含まれています。 @odata.nextLink の後もそれまでと同じパターンを実装し、最後の @odata.deltaLink を将来の呼び出しに備えて保持しておいてください。

注:

この要求には、最近作成、更新、または削除されたユーザーのレプリケーションの遅延が発生する可能性があります。 しばらくしてから、@odata.nextLink または @odata.deltaLink を再試行して、最新の変更を取得してください。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=MF1LuFYbK6Lw4DtZ4o9PDrcGekRP65WEJfDmM0H26l4v9zILCPFiPwSAAeRBghxgiwsXEfywcVQ9R8VEWuYAB50Yw3KvJ-8Z1zamVotGX2b_AHVS_Z-3b0NAtmGpod",
  "value": [
    {
      "displayName":"MOD Administrator",
      "givenName":"MOD",
      "surname":"Administrator",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "id":"8ffff70c-1c63-4860-b963-e34ec660931d",
      "@removed": {
         "reason": "changed"
      }
    }
  ]
}