ユーザーに対する増分の変更を取得するGet incremental changes for users

デルタ クエリでは、一連のデルタ関数呼び出しを使用して、ユーザーへの追加、削除、または更新に対してクエリを実行できます。デルタ クエリを使用すると、Microsoft Graph からユーザーのセット全体をフェッチして、変更を比較せずに、ユーザーへの変更を検出できます。Delta query lets you query for additions, deletions, or updates to users, by way of a series of delta function calls. Delta query enables you discover changes to users without having to fetch the entire set of users from Microsoft Graph and compare changes.

同期するユーザーとローカル プロファイル ストアを使用するクライアントは、最初の完全同期とその後の増分同期の両方でデルタ クエリを使用できます。通常なら、クライアントはテナント内のすべてのユーザーの最初の完全同期を実行し、その後、ユーザーへの増分の変更を定期的に取得します。Clients using synchronizing users with a local profile store can use Delta Query for both their initial full synchronization along with incremental synchronizations in the future. Typically, a client would do an initial full synchronization of all the users in a tenant, and subsequently, get incremental changes to users periodically.

ユーザー変更の追跡Tracking user changes

ユーザー変更の追跡は、デルタ関数を使用した、1 つ以上の GET 要求のラウンドです。GET 要求は、次を含めることを除き、ユーザーの一覧表示とほぼ同じ方法で実行します。Tracking user changes is a round of one or more GET requests with the delta function. You make a GET request much like the way you list users, except that you include the following:

  • デルタ関数。The delta function.
  • 以前の GET デルタ関数呼び出しからの状態トークン (deltaToken または skipToken)。A state token (deltaToken or skipToken) from the previous GET delta function call.

Example

次の例は、ユーザーへの変更を追跡するための一連の要求を示しています。The following example shows a series requests to track changes to users:

  1. 最初の要求応答Initial request and response
  2. nextLink 要求応答nextLink request and response
  3. 最後の nextLink 要求応答Final nextLink request and response
  4. deltaLink 要求deltaLink 応答deltaLink request and deltaLink response

最初の要求Initial request

ユーザー リソースの変更の追跡を開始するには、ユーザー リソースにデルタ関数を含む要求を実行します。To begin tracking changes in the user resource, you make a request including the delta function on the user resource.

以下の点に注意してください。Note the following:

  • オプションの $Select クエリ パラメーターは、クエリ パラメーターが将来の要求に自動的に含まれる方法をデモンストレーションする要求に含まれています。The optional $select query parameter is included in the request to demonstrate how query parameters are automatically included in future requests.
  • 最初の要求には、状態トークンは含まれません。状態トークンはそれ以降の要求で使用されます。The initial request does not include a state token. State tokens will be used in subsequent requests.
GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,givenName,surname

最初の応答Initial response

成功した場合、このメソッドは 200 OK 応答コードと、応答本文でユーザー コレクション オブジェクトを返します。ユーザーのセット全体が大きすぎると仮定した場合、応答には nextLink 状態トークンも含まれます。If successful, this method returns 200 OK response code and user collection object in the response body. Assuming the entire set of users is too large, the response will also include a nextLink state token.

この例では、セッションで取得するデータの追加ページがあることを示す nextLink URL が返されます。最初の要求からの $select クエリ パラメーターは、nextLink URL にエンコードされます。In this example, a nextLink URL is returned indicating there are additional pages of data to be retrieved in the session. The $select query parameter from the initial request is encoded into the nextLink URL.

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":"Testuser1",
      "givenName":"John",
      "surname":"Doe",
      "id":"ffff7b1a-13b6-477b-8c0c-380905cd99f7"
    },
    {
      "displayName":"Testuser2",
      "givenName":"Jane",
      "surname":"Doe",
      "id":"605d1257-ffff-40b6-8e6f-528a53f5dc55"
    }
  ]
}

2 番目の要求は、前の応答から返された skipToken を指定します。$select パラメーターは、skipToken によってエンコードされ含まれるため必須ではないことに注意してください。The second request specifies the skipToken returned from the previous response. Notice the $select parameter is not required, as the skipToken encodes and includes it.

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

応答には nextLink および skipToken が含まれ、利用可能な他のユーザーがあることを示しています。deltaLink URL が応答で返されるまで、nextLink URL を使用して要求を実行し続けます。The response contains a nextLink and another skipToken, indicating there are more users available. You continue making requests using the nextLink URL until a deltaLink URL is returned in the response.

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":"Testuser3",
      "givenName":"Pat",
      "surname":"Doe",
      "id":"d8c37826-ffff-4cae-b348-e2725b1e814b"
    },
    {
      "displayName":"Testuser4",
      "givenName":"Meghan",
      "surname":"Doe",
      "id":"8b1ee412-cd8f-4d59-ffff-24010edb9f1f"
    }
  ]
}

3 番目の要求は、最後の同期要求から返された最新の skipToken を引き続き使用します。The third request continues to use the latest skipToken returned from the last sync request.

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

deltaLink URL が返されると、返されるリソースの既存の状態に関するデータはなくなります。以降の要求では、アプリケーションは deltaLink URL を使用して、リソースへの変更点について説明します。deltaToken を保存して、ユーザーへの変更を検出するために要求 URL で使用します。When the deltaLink URL is returned, there is no more data about the existing state of the resource to be returned. For future requests, the application uses the deltaLink URL to learn about changes to the resource. Save the deltaToken and use it in the request URL to discover changes to users.

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":"Testuser5",
      "givenName":"Al",
      "surname":"Doe",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "displayName":"Testuser6",
      "givenName":"Sam",
      "surname":"Doe",
      "id":"f6ede700-27d0-4c42-bfb9-4dffff43c74a"
    }
  ]
}

最後の応答からの deltaToken を使用すると、最後の要求以降に (追加、削除、または更新によって) 変更されたユーザーを取得できます。Using the deltaToken from the last response, you will be able to get changed (by being added, deleted, or updated) users since the last request.

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

変更が行われなかった場合は、結果のない同じ deltaToken が返されます。If no changes have occurred, the same deltaToken is returned with no results.

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": []
}

変更が行われた場合は、変更されたユーザーのコレクションを含む、同じ deltaToken が返されます。If changes have occurred, the same deltaToken is returned including a collection of changed users.

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":"Testuser7",
      "givenName":"Joe",
      "surname":"Doe",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "id":"8ffff70c-1c63-4860-b963-e34ec660931d",
      "@removed": {
         "reason": "changed"
      }
    }
  ]
}

上記のサンプル応答に関する注意事項:Some things to note about the example response above:

  • ユーザーが削除されると、項目には "reason": "changed" の値が含まれた @removed のコメントが含まれます。When the user is deleted, the item contains an annotation: @removed with value of "reason": "changed".

  • ユーザーが完全に削除されると、項目には "reason": "deleted" の値が含まれた @removed のコメントが含まれます。When the user is permanently deleted, the item contains an annotation: @removed with value of "reason": "deleted".

  • ユーザーを作成または復元しても、コメントはありません。When the user is created, or restored, there is no annotation.

関連項目See also

Microsoft Graph デルタ クエリの概要。Microsoft Graph delta query overview.