group: delta

命名空间：microsoft.graph

获取新创建、更新或删除的组，包括组成员身份更改，而无需对整个组集合执行完整读取。 有关详细信息，请参阅 使用 Delta 查询 。

Permissions

要调用此 API，需要以下权限之一。要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型	权限（从最低特权到最高特权）
委派（工作或学校帐户）	GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All
委派（个人 Microsoft 帐户）	不支持。
应用程序	GroupMember.Read.All, Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All

HTTP 请求

为开始跟踪更改，请在组资源上发出包含 delta 函数的请求。

GET /groups/delta

查询参数

跟踪组中的更改会触发一个或多个 delta 函数调用。如果使用任何查询参数（而不是 $deltatoken 和 $skiptoken），必须在初始 delta 请求中指定它。Microsoft Graph 会自动将任何指定参数编码为响应中返回的 @odata.nextLink 或 @odata.deltaLink URL 的令牌部分。

只需预先指定所需的任何查询参数一次。

在后续请求中，可以复制并应用之前响应中返回的 @odata.nextLink 或 @odata.deltaLink URL，因为此 URL 已包含所需的编码参数。

查询参数	类型	说明
$deltatoken	string	对同一个组集合之前的 delta 函数调用的 @odata.deltaLink URL 中返回的 状态令牌，指示该组更改跟踪的完成状态。将此令牌包含在对该集合的下一组更改追踪的首次请求中，并保存和应用整个 @odata.deltaLink URL。
$skiptoken	string	对之前的 delta 函数调用的 @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	持有者<令牌>
Content-Type	application/json
Prefer	return=minimal 在使用 @odata.deltaLink 的请求中执行此标头将仅返回自上一轮之后发生更改的对象属性。可选。

请求正文

请勿提供此方法的请求正文。

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和组集合对象。 响应还包括一个状态令牌，该令牌要么 @odata.nextLink 是 URL，要么是 @odata.deltaLink URL。

• 如果返回 @odata.nextLinkURL：

  • 这表明会话中存在要检索的其他数据页面。应用程序继续使用 @odata.nextLink URL 发出请求，直到响应中包含 @odata.deltaLink URL。
  • 响应包含与初始 Delta 查询请求相同的属性集。 这使你能够在发起 Delta 循环时捕获对象当前的完整状态。

• 如果返回 @odata.deltaLinkURL：

  • 这表示未返回关于资源现有状态的更多数据。 保存并使用 @odata.deltaLink URL 来了解下一轮资源更改。
  • 只有对于在签发 @odata.deltaLink 之后更改的属性，你才可以选择指定 Prefer:return=minimal 标头以包含在响应值中。

默认：返回与初始 Delta 请求相同的属性

默认情况下，使用 @odata.deltaLink 或 @odata.nextLink 的请求将通过以下方式返回与初始 Delta 查询中选择的相同属性：

• 如果属性已更改，则新值将包括在响应中。 这包括设为 Null 值的属性。
• 如果属性未更改，则旧值将包括在响应中。
• 如果之前从未设置属性，则它不会包括在响应中。

注意： 如果出现此行为，那么通过查看响应无法区分属性是否已更改。 此外，增量响应往往很大，因为它们包含所有属性值，如下 例 所示。

备用：仅返回更改的属性

添加可选请求标头 - prefer:return=minimal - 将导致出现以下行为：

• 如果属性已更改，则新值将包括在响应中。 这包括设为 Null 值的属性。
• 如果尚未更改属性，则该属性不会包括在响应中。（不同于默认行为。）

注意： 可以在 Delta 循环中的任何时间点将标头添加到 @odata.deltaLink 请求中。 标头仅影响响应中包含的属性集，它不会影响执行 Delta 查询的方式。 请参阅下面的第三个示例。

示例

请求 1

下面展示了示例请求。 没有 $select 参数，因为将跟踪并返回默认的属性集。

HTTP

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

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

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

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

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

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

const options = {
    authProvider,
};

const client = Client.init(options);

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

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/groups/delta"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphGroup *group = [[MSGraphGroup alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/groups/delta"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphGroup *group = [[MSGraphGroup alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

GroupDeltaCollectionPage delta = graphClient.groups()
    .delta()
    .buildRequest()
    .get();

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

GroupDeltaCollectionPage delta = graphClient.groups()
    .delta()
    .buildRequest()
    .get();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

result, err := graphClient.Groups().Delta()().Get()

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

result, err := graphClient.Groups().Delta()().Get()

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

响应 1

以下示例所示为使用从查询初始化获得的 @odata.deltaLink 时的响应。

注意： 为了提高可读性，可能缩短了此处显示的响应对象。

请注意 members@delta 属性的存在，其中包括组中成员对象的 ID。

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#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Groups
    .Delta()
    .Request()
    .Select("displayName,description,mailNickname")
    .GetAsync();

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Groups
    .Delta()
    .Request()
    .Select("displayName,description,mailNickname")
    .GetAsync();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

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

const options = {
    authProvider,
};

const client = Client.init(options);

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

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/groups/delta?$select=displayName,description,mailNickname"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphGroup *group = [[MSGraphGroup alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/groups/delta?$select=displayName,description,mailNickname"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphGroup *group = [[MSGraphGroup alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

GroupDeltaCollectionPage delta = graphClient.groups()
    .delta()
    .buildRequest()
    .select("displayName,description,mailNickname")
    .get();

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

GroupDeltaCollectionPage delta = graphClient.groups()
    .delta()
    .buildRequest()
    .select("displayName,description,mailNickname")
    .get();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName,description,mailNickname",
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
}
result, err := graphClient.Groups().Delta()().GetWithRequestConfigurationAndResponseHandler(options, nil)

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName,description,mailNickname",
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
}
result, err := graphClient.Groups().Delta()().GetWithRequestConfigurationAndResponseHandler(options, nil)

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

PowerShell

Import-Module Microsoft.Graph.Groups

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

Import-Module Microsoft.Graph.Groups

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

有关如何将 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#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Groups
    .Delta()
    .Request()
    .Header("Prefer","return=minimal")
    .Select("displayName,description,mailNickname")
    .GetAsync();

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Groups
    .Delta()
    .Request()
    .Header("Prefer","return=minimal")
    .Select("displayName,description,mailNickname")
    .GetAsync();

有关如何将 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();

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 文档。

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/groups/delta?$select=displayName,description,mailNickname"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"return=minimal" forHTTPHeaderField:@"Prefer"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphGroup *group = [[MSGraphGroup alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/groups/delta?$select=displayName,description,mailNickname"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"return=minimal" forHTTPHeaderField:@"Prefer"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphGroup *group = [[MSGraphGroup alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("Prefer", "return=minimal"));

GroupDeltaCollectionPage delta = graphClient.groups()
    .delta()
    .buildRequest( requestOptions )
    .select("displayName,description,mailNickname")
    .get();

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("Prefer", "return=minimal"));

GroupDeltaCollectionPage delta = graphClient.groups()
    .delta()
    .buildRequest( requestOptions )
    .select("displayName,description,mailNickname")
    .get();

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName,description,mailNickname",
}
headers := map[string]string{
    "Prefer": "return=minimal"
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
    Headers: headers,
}
result, err := graphClient.Groups().Delta()().GetWithRequestConfigurationAndResponseHandler(options, nil)

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.DeltaRequestBuilderGetQueryParameters{
    Select: "displayName,description,mailNickname",
}
headers := map[string]string{
    "Prefer": "return=minimal"
}
options := &msgraphsdk.DeltaRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
    Headers: headers,
}
result, err := graphClient.Groups().Delta()().GetWithRequestConfigurationAndResponseHandler(options, nil)

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

PowerShell

Import-Module Microsoft.Graph.Groups

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

Import-Module Microsoft.Graph.Groups

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

有关如何将 SDK 添加 到项目并 创建 authProvider 实例的 详细信息，请参阅 SDK 文档。

响应 3

以下示例所示为使用从查询初始化获得的 @odata.deltaLink 时的响应。 请注意，mailNickname 属性不包括在内，这意味着它在上一轮 Delta 查询之后未发生更改；并且 displayName 和 description 将包括在内，这意味着其值已发生更改。

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
    }
  ]
}

另请参阅

• 使用 Delta 查询跟踪 Microsoft Graph 数据更改。
• 获取组的增量更改。