user: deltauser: delta

ユーザーコレクション全体を完全に読み取ることなく、新しく作成、更新、または削除されたユーザーを取得します。Get newly created, updated, or deleted users without having to perform a full read of the entire user collection. 詳細は.、変更の追跡をご覧ください。See Track changes for details.

アクセス許可Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) User.Read、User.ReadWrite、User.ReadBasic.All、User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All、Directory.AccessAsUser.AllUser.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) User.Read、User.ReadWriteUser.Read, User.ReadWrite
アプリケーションApplication User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.AllUser.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

HTTP 要求HTTP request

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

GET /users/delta

クエリ パラメーターQuery parameters

ユーザーの変更を追跡すると、一連の デルタ関数の呼び出しが発生します。Tracking changes in users incurs a round of one or more delta function calls. 任意のクエリ パラメーター ($deltatoken$skiptoken以外) を使用する場合は、最初のデルタ要求でこれを指定する必要があります。If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. Microsoft Graph は、応答で提供される nextLink または deltaLink の URL のトークン部分に指定したパラメーターを自動的にエンコードします。Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response.

必要なクエリ パラメーターを前もって 1 回指定しておくだけで済みます。You only need to specify any desired query parameters once upfront.

その後の要求では、前の応答で得られた nextLinkdeltaLink の URL をコピーして適用します。エンコード済みの必要なパラメーターがこの URL に既に含まれているためです。In subsequent requests, copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded, desired parameters.

クエリ パラメーターQuery parameter 種類Type 説明Description
$deltatoken$deltatoken stringstring 同じユーザー コレクションの前のデルタ関数の deltaLink URL で状態トークンが返され、変更追跡のその回が完了したことを示します。このコレクションについて、このトークンを含む、deltaLink URL 全体を次の変更追跡のラウンドの最初の要求に保存し、適用します。A state token returned in the deltaLink URL of the previous delta function call for the same user collection, indicating the completion of that round of change tracking. Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that collection.
$skiptoken$skiptoken stringstring 前のデルタ関数の nextLink URL で状態トークンが返され、同じユーザー コレクションで追跡されるその他の変更があることを示します。A state token returned in the nextLink URL of the previous delta function call, indicating there are further changes to be tracked in the same user collection.

OData クエリ パラメーターOData query parameters

このメソッドは、応答をカスタマイズするためのオプショナルの OData クエリ パラメーターをサポートします。This method supports optional OData Query Parameters to help customize the response.

  • 任意の 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.
  • $filter に対するサポートには制限があります。There is limited support for $filter:
    • サポートされている唯一の $filter 式は、特定のオブジェクトでの変更を追跡する $filter=id+eq+{value} です。The only supported $filter expression is for tracking changes on a specific object: $filter=id+eq+{value}. 複数のオブジェクトをフィルター処理することができます。You can filter multiple objects. たとえば、https://graph.microsoft.com/v1.0/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff' などです。For example, https://graph.microsoft.com/v1.0/users/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'. フィルター処理されるオブジェクトには 50 の数量制限があります。There is a limit of 50 filtered objects.

要求ヘッダーRequest headers

名前Name 説明Description
AuthorizationAuthorization Bearer <token>Bearer <token>
Content-TypeContent-Type application/jsonapplication/json
PreferPrefer return=minimal.return=minimal

このヘッダーを指定する要求を使用すると、deltaLink は、最後のラウンド以降に変更されたオブジェクトのプロパティのみを返します。Specifying this header with a request that uses a deltaLink would return only the object properties that have changed since the last round. 省略可能です。Optional.

要求本文Request body

このメソッドには、要求本文を指定しません。Do not supply a request body for this method.

応答Response

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で user コレクション オブジェクトを返します。If successful, this method returns 200 OK response code and user collection object in the response body. 応答にはnextLink URLまたはdeltaLink URLも含まれます。The response also includes a nextLink URL or a deltaLink URL.

  • もしnextLink URL が返された場合:If a nextLink URL is returned:

    • セッションで取得するデータに追加ページがあることを示しています。This indicates there are additional pages of data to be retrieved in the session. アプリケーションはdeltaLink URL が応答に含まれるまでnextLink URLを使用して要求を続けます。The application continues making requests using the nextLink URL until a deltaLink URL is included in the response.
    • 応答には、最初のデルタクエリ要求と同じ一連のプロパティが含まれています。The response includes the same set of properties as in the initial delta query request. これにより、デルタサイクルを開始するときに、オブジェクトの現在の完全な状態をキャプチャできます。This allows you to capture the full current state of the objects when initiating the delta cycle.
  • もしdeltaLink URL が返された場合:If a deltaLink URL is returned:

    • これは、返されるリソースの既存の状態に関するデータがこれ以上ないことを示します。This indicates there is no more data about the existing state of the resource to be returned. deltaLink URL を、次回のラウンドでリソースへの変更について学ぶために保存して使ってください。Save and use the deltaLink URL to learn about changes to the resource in the next round.
    • Prefer:return=minimal ヘッダーを指定して、deltaLink発行後に変更されたプロパティのみをレスポンス値に含めるように選択することもできます。You have a choice to specify the Prefer:return=minimal header, to include in the response values for only the properties that have changed since the time the deltaLink was issued.

デフォルト:初期デルタリクエストと同じプロパティを返しますDefault: return the same properties as initial delta request

デフォルトでは、deltaLinkまたはnextLinkを使用したリクエストは、最初のデルタクエリで選択されたものと同じプロパティを次のように返します:By default, requests using a deltaLink or nextLink return the same properties as selected in the initial delta query in the following ways:

  • プロパティを変更した場合は、応答には新しい値が含まれます。If the property has changed, the new value is included in the response. これには、null 値に設定されているプロパティが含まれます。This includes properties being set to null value.
  • プロパティが変更されていない場合は、古い値が応答に含まれています。If the property has not changed, the old value is included in the response.
  • プロパティが設定されたことがない場合は、応答にまったく含まれません。If the property has never been set before it will not be included in the response at all.

注意: この動作では、応答を見ても、プロパティが変化しているかどうかを判断することはできません。Note: With this behavior, by looking at the response it is not possible to tell whether a property is changing or not. また、デルタ応答は-以下の2番目の例に示されるようにすべてのプロパティ値を含むため、大きくなる傾向があります 。Also, the delta responses tend to be large because they contain all property values - as shown in the second example below.

代替案:変更されたプロパティのみを返すAlternative: return only the changed properties

オプションのリクエストヘッダを追加すると、- prefer:return=minimal - 次のようになります:Adding an optional request header - prefer:return=minimal - results in the following behavior:

  • プロパティを変更した場合は、応答には新しい値が含まれます。If the property has changed, the new value is included in the response. これには、null 値に設定されているプロパティが含まれます。This includes properties being set to null value.
  • プロパティが変更されていない場合、そのプロパティは応答にまったく含まれません。If the property has not changed, the property is not included in the response at all. (既定の動作と異なる)(Different from the default behavior.)

注意: ヘッダーは、デルタサイクルのどの時点でも deltaLink要求に追加できます。Note: The header can be added to a deltaLink request at any point in time in the delta cycle. ヘッダーは応答に含まれる一連のプロパティにのみ影響し、デルタクエリの実行方法には影響しません。The header only affects the set of properties included in the response and it does not affect how the delta query is executed. 以下の三番目の例を参照してください。See the third example below.

Example

要求 1Request 1

要求の例を次に示します。The following is an example of the request. $selectパラメータがないため、デフォルトのプロパティセットが追跡されて返されます。There is no $select parameter, so a default set of properties is tracked and returned.

GET https://graph.microsoft.com/v1.0/users/delta

応答 1Response 1

以下は、クエリ初期化から取得したdeltaLink を使用した場合の応答の例です。The following is an example of the response when using deltaLink obtained from the query initialization.

注: 読みやすくするために、ここに示す応答オブジェクトは短縮されている場合があります。実際の呼び出しからは、すべてのプロパティが返されます。Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "businessPhones": [
          "businessPhones-value"
      ],
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "jobTitle": "jobTitle-value",
      "mail": "mail-value",
      "mobilePhone": "mobilePhone-value",
      "officeLocation": "officeLocation-value",
      "preferredLanguage": "preferredLanguage-value",
      "surname": "surname-value",
      "userPrincipalName": "userPrincipalName-value",
      "id": "id-value"
    }
  ]
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Users.Delta()
    .Request()
    .GetAsync();

SDK をプロジェクトに追加し、 authproviderインスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

要求 2Request 2

次の例は、デフォルトの応答動作で、変更追跡のために3つのプロパティを選択する最初の要求を示しています。The next example shows the initial request selecting 3 properties for change tracking, with default response behavior:

GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,jobTitle,mobilePhone

応答 2Response 2

以下は、クエリ初期化から取得したdeltaLink を使用した場合の応答の例です。The following is an example of the response when using deltaLink obtained from the query initialization. 3つのプロパティすべてがレスポンスに含まれており、deltaLinkが取得されてからどのプロパティが変更されたのかはわかりません。Note that all 3 properties are included in the response and it is not known which ones have changed since the deltaLink was obtained.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": "jobTitle-value",
      "mobilePhone": null
    }
  ]
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Users.Delta()
    .Request()
    .Select( e => new {
             e.DisplayName,
             e.JobTitle,
             e.MobilePhone 
             })
    .GetAsync();

SDK をプロジェクトに追加し、 authproviderインスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

要求 3Request 3

次の例は、最初のリクエストが代替の最小限の応答の変更追跡のために3つのプロパティを選択していることを示しています。The next example shows the initial request selecting 3 properties for change tracking, with alternative minimal response behavior:

GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,jobTitle,mobilePhone
Prefer: return=minimal

応答 3Response 3

以下は、クエリ初期化から取得したdeltaLink を使用した場合の応答の例です。The following is an example of the response when using deltaLink obtained from the query initialization. このmobilePhoneプロパティは含まれていないことに注意してください 。つまり、最後のデルタクエリ以降変更されていません;displayNamejobTitle が含まれており、それらの値は変更されていることを意味します。Note that the mobilePhone property is not included, which means it has not changed since the last delta query; displayName and jobTitle are included which means their values have changed.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": null
    }
  ]
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Users.Delta()
    .Request()
    .Header("Prefer","return=minimal")
    .Select( e => new {
             e.DisplayName,
             e.JobTitle,
             e.MobilePhone 
             })
    .GetAsync();

SDK をプロジェクトに追加し、 authproviderインスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.