user: delta

[アーティクル]
10/22/2024

名前空間: microsoft.graph

ユーザーコレクション全体の完全な読み取りを実行することなく、新しく作成、更新、または削除されたユーザーを取得します。詳細については、「デルタクエリを使用して Microsoft Graph データの変更を追跡する」を参照してください。

注:

現在、licenseAssignmentStates プロパティの変更は追跡されません。

この API は、次の国内クラウド展開で使用できます。

グローバルサービス	米国政府機関 L4	米国政府機関 L5 (DOD)	21Vianet が運営する中国
✅	✅	✅	✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類	最小特権アクセス許可	より高い特権のアクセス許可
委任 (職場または学校のアカウント)	User.Read.All	Directory.Read.All、Directory.ReadWrite.All、User.ReadWrite.All
委任 (個人用 Microsoft アカウント)	サポートされていません。	サポートされていません。
アプリケーション	User.Read.All	Directory.Read.All、Directory.ReadWrite.All、User.ReadWrite.All

HTTP 要求

変更の追跡を開始するには、ユーザーリソースに delta 関数を含めることによって要求を行います。

GET /users/delta

クエリパラメーター

ユーザーの変更を追跡すると、一連の デルタ関数の呼び出しが発生します。任意のクエリパラメーター ($deltatoken と$skiptoken以外) を使用する場合は、最初のデルタ要求でこれを指定する必要があります。 Microsoft Graph は、応答で提供される @odata.nextLink または @odata.deltaLink の URL のトークン部分に指定したパラメーターを自動的にエンコードします。

必要なクエリパラメーターを前もって 1 回指定しておくだけで済みます。

その後の要求では、前の応答で得られた @odata.nextLink や @odata.deltaLink の URL をコピーして適用します。エンコード済みの必要なパラメーターがこの URL に既に含まれているためです。

クエリパラメーター	種類	説明
$deltatoken	string	同じユーザーコレクションの前のデルタ関数呼び出しの URL で`@odata.deltaLink`返された状態トークン。変更追跡のラウンドの完了を示します。このコレクションについて、このトークンを含む、`@odata.deltaLink` URL 全体を次の変更追跡のラウンドの最初の要求に保存し、適用します。
$skiptoken	string	前のデルタ関数の `@odata.nextLink` URL で状態トークンが返され、同じユーザーコレクションで追跡されるその他の変更があることを示します。

OData クエリパラメーター

このメソッドは、応答をカスタマイズするためのオプショナルの OData クエリパラメーターをサポートします。

GET 要求と同様にクエリパラメーターを $select 使用して、最適なパフォーマンスを得るために必要なプロパティのみを指定できます。 id プロパティは常に返されます。
のサポート $filterは限られています。
- サポートされている唯一の $filter 式は、特定のオブジェクトでの変更を追跡する $filter=id+eq+{value} です。複数のオブジェクトをフィルター処理することができます。たとえば、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 個に制限されています。

要求ヘッダー

名前	説明
Authorization	ベアラー {token}。必須です。認証と認可についての詳細をご覧ください。
Content-Type	application/json
Prefer	return=minimal. このヘッダーを指定する要求を使用すると、`@odata.deltaLink` は、最後のラウンド以降に変更されたオブジェクトのプロパティのみを返します。省略可能です。

要求本文

このメソッドには、要求本文を指定しません。

応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で user コレクションオブジェクトを返します。応答には@odata.nextLink URLまたは@odata.deltaLink URLも含まれます。

もし@odata.nextLink URL が返された場合:
- セッションで取得するデータに追加ページがあることを示しています。 URL が応答に含まれるまで@odata.deltaLink、@odata.nextLinkアプリケーションは URL を使用して要求を行い続けます。
- 応答には、最初のデルタクエリ要求と同じ一連のプロパティが含まれています。これにより、デルタサイクルを開始するときに、オブジェクトの現在の完全な状態をキャプチャできます。
もし@odata.deltaLink URL が返された場合:
- これは、返されるリソースの既存の状態に関するデータがそれ以上ないことを示します。 @odata.deltaLink URL を、次回のラウンドでリソースへの変更について学ぶために保存して使ってください。
- Prefer:return=minimal ヘッダーを指定して、@odata.deltaLink発行後に変更されたプロパティのみをレスポンス値に含めるように選択することもできます。

デフォルト：初期デルタリクエストと同じプロパティを返します

デフォルトでは、@odata.deltaLinkまたは@odata.nextLinkを使用したリクエストは、最初のデルタクエリで選択されたものと同じプロパティを次のように返します:

プロパティを変更した場合は、応答には新しい値が含まれます。これには、null 値に設定されているプロパティが含まれます。
プロパティが変更されていない場合は、古い値が応答に含まれます。
プロパティが設定されたことがない場合は、応答にまったく含まれません。

代替案：変更されたプロパティのみを返す

オプションのリクエストヘッダを追加すると、- prefer:return=minimal - 次のようになります:

プロパティを変更した場合は、応答には新しい値が含まれます。これには、null 値に設定されているプロパティが含まれます。
プロパティが変更されていない場合、プロパティは応答にまったく含まれません。 (既定の動作と異なる)

例

例 1: 既定のプロパティ

要求

次の例は要求を示しています。パラメーターがないため $select 、プロパティの既定のセットが追跡され、返されます。

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.Delta.GetAsDeltaGetResponseAsync();



mgc users delta get



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Users().Delta().GetAsDeltaGetResponse(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.users().delta().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->users()->delta()->get()->wait();


Import-Module Microsoft.Graph.Users.Functions

Get-MgUserDelta


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.users.delta.get()

応答

クエリの初期化から取得したを使用 @odata.deltaLink する場合の応答の例を次に示します。

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": [
          "+1 425 555 0109"
      ],
      "displayName": "Adele Vance",
      "givenName": "Adele",
      "jobTitle": "Retail Manager",
      "mail": "AdeleV@contoso.com",
      "mobilePhone": "+1 425 555 0109",
      "officeLocation": "18/2111",
      "preferredLanguage": "en-US",
      "surname": "Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

例 2: 3 つのプロパティの選択

要求

次の例は、既定の応答動作で、変更追跡のために 3 つのプロパティを選択する最初の要求を示しています。

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","jobTitle","mobilePhone" };
});



mgc users delta get --select "displayName,jobTitle,mobilePhone"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

requestParameters := &graphusers.UsersDeltaRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","jobTitle","mobilePhone"},
}
configuration := &graphusers.UsersDeltaRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Users().Delta().GetAsDeltaGetResponse(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.users().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "jobTitle", "mobilePhone"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
	.select('displayName,jobTitle,mobilePhone')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","jobTitle","mobilePhone"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->delta()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users.Functions

Get-MgUserDelta -Property "displayName,jobTitle,mobilePhone"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		select = ["displayName","jobTitle","mobilePhone"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.delta.get(request_configuration = request_configuration)

応答

クエリの初期化から取得したを使用 @odata.deltaLink する場合の応答の例を次に示します。 3 つのプロパティはすべて応答に含まれており、が取得されてから @odata.deltaLink 変更されたものは不明です。

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": "Adele Vance",
      "jobTitle": "Retail Manager",
      "mobilePhone": "+1 425 555 0109"
    }
  ]
}

例 3: 代替の最小限の応答の動作

要求

次の例は、最初のリクエストが代替の最小限の応答の変更追跡のために 3 つのプロパティを選択していることを示しています。

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","jobTitle","mobilePhone" };
	requestConfiguration.Headers.Add("Prefer", "return=minimal");
});



mgc users delta get --select "displayName,jobTitle,mobilePhone"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "return=minimal")

requestParameters := &graphusers.UsersDeltaRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","jobTitle","mobilePhone"},
}
configuration := &graphusers.UsersDeltaRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Users().Delta().GetAsDeltaGetResponse(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.users().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "jobTitle", "mobilePhone"};
	requestConfiguration.headers.add("Prefer", "return=minimal");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/users/delta')
	.header('Prefer','return=minimal')
	.select('displayName,jobTitle,mobilePhone')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$headers = [
		'Prefer' => 'return=minimal',
	];
$requestConfiguration->headers = $headers;

$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","jobTitle","mobilePhone"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->delta()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users.Functions

Get-MgUserDelta -Property "displayName,jobTitle,mobilePhone"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		select = ["displayName","jobTitle","mobilePhone"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("Prefer", "return=minimal")


result = await graph_client.users.delta.get(request_configuration = request_configuration)

応答

クエリの初期化から取得したを使用 @odata.deltaLink する場合の応答の例を次に示します。プロパティは mobilePhone 含まれていません。つまり、最後のデルタクエリ以降は変更されておらず、 displayNamejobTitle 値が変更されたことを意味します。

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": "Vance Adele",
      "jobTitle": "Product Marketing Manager"
    }
  ]
}

次の方法で共有

user: delta

アクセス許可

HTTP 要求

クエリパラメーター

OData クエリパラメーター

要求ヘッダー

要求本文

応答

デフォルト：初期デルタリクエストと同じプロパティを返します

代替案：変更されたプロパティのみを返す

例

例 1: 既定のプロパティ

要求

応答

例 2: 3 つのプロパティの選択

要求

応答

例 3: 代替の最小限の応答の動作

要求

応答

フィードバック

その他のリソース

次の方法で共有

user: delta

アクセス許可

HTTP 要求

クエリ パラメーター

OData クエリ パラメーター

要求ヘッダー

要求本文

応答

デフォルト：初期デルタリクエストと同じプロパティを返します

代替案：変更されたプロパティのみを返す

例

例 1: 既定のプロパティ

要求

応答

例 2: 3 つのプロパティの選択

要求

応答

例 3: 代替の最小限の応答の動作

要求

応答

関連コンテンツ

フィードバック

その他のリソース

クエリパラメーター

OData クエリパラメーター