group: delta

名前空間: microsoft.graph

グループ コレクション全体の完全な読み取りを実行することなく、グループ メンバーシップの変更を含む、新しく作成、更新、または削除されたグループを取得します。 詳細については、「 Delta Query の使用」 を参照してください。

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

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

アクセス許可

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

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

HTTP 要求

変更の追跡を開始するには、要求を行い、グループ リソースにデルタ関数を含めます。

GET /groups/delta

クエリ パラメーター

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

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

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

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

OData クエリ パラメーター

このメソッドは、応答のカスタマイズに役立つオプションの OData クエリ パラメーターをサポートします。

• GET 要求と同様にクエリ パラメーターを $select 使用して、最適なパフォーマンスを得るために必要なプロパティのみを指定できます。 id プロパティは常に返されます。
• を使用 $select=members して、メンバーシップの変更を取得できます。 さらに、directoryObject コレクション型の任意のグループリレーションシップを選択することで、所有権などの他の変更を追跡することもできます。
• のサポート $filterは限られています。
  • サポートされている唯一の $filter 式は、特定のオブジェクトでの変更を追跡する $filter=id+eq+{value} です。 複数のオブジェクトをフィルター処理することができます。 たとえば、https://graph.microsoft.com/v1.0/groups/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 応答コードと、応答本文で group コレクション オブジェクトを返します。 応答には、URL または @odata.deltaLink URL である@odata.nextLink状態トークンも含まれます。

• もし@odata.nextLink URL が返された場合:

  • これは、セッションで取得するデータのページが増え続ける可能性があることを示します。 アプリケーションは@odata.deltaLink URL が応答に含まれるまで@odata.nextLink URLを使用して要求を続けます。
  • 応答には、最初のデルタクエリ要求と同じ一連のプロパティが含まれています。 これにより、デルタサイクルを開始するときに、オブジェクトの現在の完全な状態をキャプチャできます。

• もし@odata.deltaLink URL が返された場合:

  • これは、返されるリソースの既存の状態に関するデータがそれ以上ないことを示します。 @odata.deltaLink URL を、次回のラウンドでリソースへの変更について学ぶために保存して使ってください。
  • Prefer:return=minimal ヘッダーを指定して、@odata.deltaLink発行後に変更されたプロパティのみをレスポンス値に含めるように選択することもできます。

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

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

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

注意:この動作では、応答を見ても、プロパティが変化しているかどうかを判断することはできません。 また、次の 2 番目の例 に示すように、すべてのプロパティ値が含まれているため、デルタ応答は大きくなる傾向があります。

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

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

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

注意: ヘッダーは、デルタサイクルのどの時点でも @odata.deltaLink要求に追加できます。 ヘッダーは応答に含まれる一連のプロパティにのみ影響し、デルタクエリの実行方法には影響しません。 以下の三番目の例を参照してください。

例

要求 1

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

HTTP

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

C#

// 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.Groups.Delta.GetAsDeltaGetResponseAsync();

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups delta get

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



delta, err := graphClient.Groups().Delta().GetAsDeltaGetResponse(context.Background(), nil)

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

応答 1

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

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

グループ内のメンバー オブジェクトの ID を含む members@delta プロパティが存在する点に注意してください。

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
  "value":[
    {
      "createdDateTime":"2021-03-12T10:36:14Z",
      "description":"This is the default group for everyone in the network",
      "displayName":"All Company",
      "groupTypes": [
        "Unified"
      ],
      "mail": "allcompany@contoso.com",
      "members@delta": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "693acd06-2877-4339-8ade-b704261fe7a0"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49320844-be99-4164-8167-87ff5d047ace"
        }
      ]
    }
  ]
}

要求 2

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

HTTP

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,mailNickname

C#

// 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.Groups.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","description","mailNickname" };
});

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups delta get --select "displayName,description,mailNickname"

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphgroups.GroupsDelta()RequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","mailNickname"},
}
configuration := &graphgroups.GroupsDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Groups().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.select('displayName,description,mailNickname')
	.get();

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PHP

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


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

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


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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Property "displayName,description,mailNickname" 

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Python

from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		select = ["displayName","description","mailNickname"],
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

応答 2

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

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "All Company",
      "description": null,
      "mailNickname": "allcompany@contoso.com"
    }
  ]
}

要求 3

次の例では、変更追跡用に 3 つのプロパティを選択する最初の要求を示します。代替の応答動作は最小限です。

HTTP

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,mailNickname
Prefer: return=minimal

C#

// 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.Groups.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","description","mailNickname" };
	requestConfiguration.Headers.Add("Prefer", "return=minimal");
});

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups delta get --select "displayName,description,mailNickname"

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

requestParameters := &graphgroups.GroupsDelta()RequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","mailNickname"},
}
configuration := &graphgroups.GroupsDelta()RequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

delta, err := graphClient.Groups().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.header('Prefer','return=minimal')
	.select('displayName,description,mailNickname')
	.get();

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PHP

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


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

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

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


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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Property "displayName,description,mailNickname" 

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Python

from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		select = ["displayName","description","mailNickname"],
)

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


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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

応答 3

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

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

関連コンテンツ

• デルタクエリを使用してMicrosoft Graphデータの変更を追跡します。
• グループの増分変更を取得します。