グループに対する増分の変更を取得するGet incremental changes for groups

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

同期するグループとローカル プロファイル ストアを使用するクライアントは、最初の完全同期とその後の増分同期の両方でデルタ クエリを使用できます。通常なら、クライアントはテナント内のすべてのグループの最初の完全同期を実行し、その後、グループへの増分の変更を定期的に取得します。Clients using synchronizing groups 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 groups in a tenant, and subsequently, get incremental changes to groups periodically.

グループ変更の追跡Tracking group changes

グループ変更の追跡は、デルタ関数を使用した、1 つ以上の GET 要求のラウンドです。GET 要求は、次を含めることを除き、グループの一覧表示とほぼ同じ方法で実行します。Tracking group 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 groups, 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 groups:

  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 group resource, you make a request including the delta function on the group 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.
  • オプションの $expand クエリ パラメーターが含められているのは、グループのメンバーをグループ オブジェクトと共に取り出す方法を示すためです。The optional $expand query parameter is included to show how group members can be retrieved together with group objects. それにより、グループのユーザーの追加や削除など、メンバーシップの変更を追跡できます。This allows tracking of membership changes, such as when users are added or removed from groups.
  • 最初の要求には、状態トークンは含まれません。状態トークンはそれ以降の要求で使用されます。The initial request does not include a state token. State tokens will be used in subsequent requests.
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description&$expand=members

最初の応答Initial response

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で group コレクション オブジェクトを返します。If successful, this method returns 200 OK response code and group collection object in the response body. グループ セット全体が大きすぎて 1 つの応答では収まらない場合、状態トークンが含まれる nextLink も含められます。If the entire set of groups is too large to fit in one response, a nextLink containing a state token will also be included.

この例の場合、nextLink が含められました。元の $select および $expand クエリ パラメーターは、状態トークンの中にエンコードされています。In this example, a nextLink was included; the original $select and $expand query parameters are encoded in the state token.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups(displayName,description)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
  "value": [
    {
      "displayName":"TestGroup1",
      "description":"Employees in test group 1",
      "id":"c2f798fd-f95d-4623-8824-63aec21fffff",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "693acd06-2877-4339-8ade-b704261fe7a0"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    },
    {
      "displayName":"TestGroup2",
      "description":"Employees in test group 2",
      "id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
    }
  ]
}

注:  最初のグループ オブジェクト - TestGroup1 - には members@delta プロパティが含まれています。それにはグループの現在の 2 つのメンバーが含まれています。Note: The members@delta property is included in the first group object - TestGroup1 - and contains the two current members of the group. TestGroup2 にはメンバーがないため、このグループにはそのプロパティが含まれていません。TestGroup2 does not contain that property because the group does not have any members.

2 番目の要求では、前の応答の nextLink を使用しています。それには、skipToken が含まれています。The second request uses the nextLink from the previous response, which contains the skipToken. $select パラメーターと $expand パラメーターは、トークンの中にエンコードされているため、明示的には存在しないことに注意してください。Notice the $select and $expand parameters are not explicitly present as they are encoded in the token.

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ

応答には新たな skipToken 値を指定した別の nextLink が含まれています。これは、利用可能な他のグループがあることを示しています。The response contains another nextLink with a new skipToken value, indicating there are more groups available. 最後の応答で deltaLink URL が返されるまで、nextLink URL を使用して要求の発行を続けます。You continue making requests using the nextLink URL until a deltaLink URL is returned in the final response.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"TestGroup3",
      "description":"Employees in test group 3",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "632f6bb2-3ec8-4c1f-9073-0027a8c68593"
               }
      ]
    },
    {
      "displayName":"TestGroup4",
      "description":"Employees in test group 4",
      "id":"421e797f-9406-4934-b778-4908421e3505",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "3c8ac7c4-d365-4df9-abfa-356a9dd7763c"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    }
  ]
}

3 番目の要求では、最新の nextLink を再び使用します。The third request again uses the latest nextLink.

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7

最後に、deltaLink URL が返されます。これは、グループの既存の状態ではそれ以上のデータがないことを意味します。Finally, the deltaLink URL is returned, which means there is no more data for the existing state of groups. アプリケーションは、その後の要求のため、deltaLink およびそれに含まれる deltaToken 値を使用して、グループに対する新たな変更について調べます。For future requests, the application uses the deltaLink and the deltaToken value it contains to learn about new changes to groups.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
    {
      "displayName":"TestGroup5",
      "description":"Employees in test group 5",
      "id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
    },
    {
      "displayName":"TestGroup6",
      "description":"Employees in test group 6",
      "id":"421e797f-9406-ffff-b778-4908421e3505"
    }
  ]
}

最後の応答deltaLink を使用することにより、最後の要求以降にグループに対して加えられた、実質的な新たな変更を入手できます。Using the deltaLink from the last response, you will be able to get net new changes to groups since the last request. 変更内容には、次のものが含まれます。Changes include:

  • 新たに作成されたグループ オブジェクト。Newly created group objects.
  • 削除されたグループ オブジェクト。Deleted group objects.
  • プロパティに変更が加えられたグループ オブジェクト (displayName が変更されたなど)。Group objects for which a property has changed (e.g. displayName has been modified).
  • メンバー オブジェクトが追加または削除されたグループ オブジェクト。Group objects for which member objects have been added or removed.
GET https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw

変更がなかった場合は、結果なしで deltaLink が返されます。value プロパティは空になります。If no changes have occurred, a deltaLink is returned with no results - the value property is empty. アプリケーションでは将来の呼び出しに備えて、以前のリンクを新しいリンクに必ず置き換えてください。Make sure to replace the previous link in the application with the new one for use in future calls.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": []
}

変更があった場合は、変更されたグループのコレクションが含められます。If changes have occurred, a collection of changed groups is included. さらに応答には、nextLink (取得対象の変更のページが複数ある場合) と deltaLink のどちらかも含まれています。The response also contains either a nextLink - in case there are multiple pages of changes to retrieve - or a deltaLink. nextLinks の後もそれまでと同じパターンを実装し、最後の deltaLink を将来の呼び出しに備えて保持しておいてください。You should implement the same pattern of following the nextLinks as before and persist the final deltaLink for future calls.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
          {
              "displayName": "TestGroup3",
              "description": "A test group for change tracking",
              "id": "2e5807ce-58f3-4a94-9b37-ffff2e085957",
              "members@delta": [
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
                      "@removed": {
                          "reason": "deleted"
                      }
                  },
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "37de1ae3-408f-4702-8636-20824abda004"
                  }
              ]
          }
      ]
}

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

  • オブジェクトは、当初 $select および $expand のクエリ パラメーターで指定されたのと同じプロパティ セットを伴って返されます。The objects are returned with the same set of properties originally specified via the $select and $expand query parameters.

  • 変更されたプロパティと変更されていないプロパティの両方が含まれています。Both changed and unchanged properties are included. 上記の例の場合、description プロパティの値は新しいものになっていますが、displayName プロパティは変更されていません。In the example above, the description property has a new value, while the displayName property has not changed.

  • members@delta には、メンバーシップに対して加えられた変更内容が含まれています。members@delta contains any changes to membership.

    • リスト中の最初のユーザーが、メンバーシップを削除するか、またはユーザー オブジェクト自体を削除することにより、グループから削除されました。The first user in the list has been removed from the group - either by removing the membership or by deleting the user object itself. @removed プロパティがそのことを記述しています。The @removed property describes that.

    • 2 番目のユーザーはグループに追加されました。The second user has been added to the group.

大規模グループ内のメンバー間のページングPaging through members in a large group

members@delta プロパティは、$select クエリ パラメーターが指定されていない場合、または $expand=members パラメーターが明示的に指定されている場合、既定でグループ オブジェクトに含められます。The members@delta property is included in group objects by default, when the $select query parameter has not been specified, or when the $expand=members parameter is explicitly specified. メンバー数の多いグループの場合、1 つの応答に全メンバーが収まらないことがあります。このセクションでは、そのような状況を処理するために実装しなければならないパターンについて説明します。For groups with many members it is possible that all members cannot fit into a single response; in this section we describe the pattern you should implement to handle such cases.

注: このパターンは、グループ状態を最初に取得する際にも、それ以降にデルタ変更を取得するために呼び出す際にも適用されます。Note: This pattern applies to both the initial retrieval of group state as well as to subsequent calls to get delta changes.

グループの初期状態のすべてを取得するため、またはそれ以降にデルタ変更を取得するために、次のデータ クエリを実行しているとします。Let's assume you are executing the following delta query - either to capture the initial full state of groups, or later on to get delta changes:

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description&$expand=members
  1. Microsoft Graph は、members@delta プロパティに多くのメンバーが含まれる 1 つのグループ オブジェクトのみ含まれる応答を返すことがあります。Microsoft Graph may return a response that contains just one group object, with a large list of members in the members@delta property:

最初のページFirst page

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "37de1ae3-408f-4702-8636-20824abda004"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}
  1. nextLink をたどる際、再び同じグループ オブジェクトが含まれる応答を受け取ることがあります。When you follow the nextLink you may receive a response again containing the same group object. 同じプロパティ値が返されますが、展開された members@delta プロパティの内容は、異なるユーザー リストになっています。The same property values will be returned but the expanded members@delta property now contains a different list of users.

2 番目のページSecond page

HTTP/1.1 200 OK
Content-type: application/json
{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "c08a463b-7b8a-40a4-aa31-f9bf690b9551",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "23423fa6-821e-44b2-aae4-d039d33884c2"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}
  1. このようにしてメンバー リスト全体が返され、他のグループが応答に出現し始めます。Eventually, the entire member list will be returned in this fashion, and other groups will start showing up in the response.

このパターンを処理する際には、次のベスト プラクティスに従うことをお勧めします。We recommend the following best practices to correctly handle this pattern:

  • 常に nextLink をたどり、各グループの状態をローカルでマージします。同じグループに関連する複数の応答を受信したなら、アプリケーションの中でその応答を使用してメンバーシップ リスト全体を作成します。Always follow nextLink and locally merge each group's state: as you receive responses related to the same group, use them to build the full membership list in your application.
  • 特定の応答シーケンスを前提にしないようにするのが最善です。It is best not to assume a specific sequence of the responses. nextLink シーケンスのどこにでも同じグループが出現する可能性があると想定し、マージ ロジックの中でそれを処理します。Assume that the same group could show up anywhere in the nextLink sequence and handle that in your merge logic.

関連項目See also

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