group: delta

2025-07-24

命名空间：microsoft.graph

获取新创建、更新或删除的组，包括组成员身份更改，而无需执行整个组集合的完全读取。有关详细信息，请参阅使用增量查询跟踪Microsoft Graph 数据中的更改。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	✅	✅	✅

权限

为此 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 请求

若要开始跟踪更改，请发出请求并在组资源中包含 delta 函数。

GET /groups/delta

查询参数

跟踪组中的更改会导致一轮或多次 delta 函数调用。如果要使用任意查询参数（$deltatoken 和 $skiptoken 除外），则必须在最初的 delta 请求中指定它。 Microsoft Graph 自动将指定的任意参数编码为响应中提供的 @odata.nextLink 或 @odata.deltaLink URL 的令牌部分。

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

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

查询参数	类型	说明
$deltatoken	string	在上一个 delta 函数的 URL 中`@odata.deltaLink`返回的状态令牌调用同一组集合，指示完成这一轮更改跟踪。将此令牌包含在对该集合的下一组更改追踪的首次请求中，并保存和应用整个 `@odata.deltaLink` URL。
$skiptoken	string	对之前的 delta 函数调用的 `@odata.nextLink` URL 中返回的状态令牌，指示同一个组集合中有进一步的更改需要追踪。

OData 查询参数

此方法支持可选的 OData 查询参数，以帮助自定义响应。

像在任何 GET 请求中一样，你可以使用 $select 查询参数以仅指定获取最佳性能所需的属性。始终返回 id 属性。
可以使用 $select=members 获取成员身份更改。
- 还可以通过选择目录对象集合类型的任意组关系来跟踪其他更改，例如所有权等。
- 仅返回相关资源的 id 属性。
对的支持有限 $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 响应代码和组集合对象。响应还包括一个状态令牌，该令牌是 @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 值的属性。
如果属性未更改，则响应中根本不包含该属性。（不同于默认行为。）

示例

请求 1

以下示例显示了一个请求。没有 $select 参数，因此会跟踪并返回一组默认的属性。

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


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

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



// 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://free.blessedness.top/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Groups().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.groups().delta().get();


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?php
use Microsoft\Graph\GraphServiceClient;


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


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


Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta


# 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://free.blessedness.top/en-us/graph/sdks/create-client?from=snippets&tabs=python

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

响应 1

下面是使用 @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=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

下一个示例演示初始请求选择三个属性进行更改跟踪，并采用默认响应行为：

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


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

// To initialize your graphClient, see https://free.blessedness.top/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" };
});



// 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"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

requestParameters := &graphgroups.GroupsDeltaRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","mailNickname"},
}
configuration := &graphgroups.GroupsDeltaRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://free.blessedness.top/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Groups().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.groups().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "description", "mailNickname"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?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();


Import-Module Microsoft.Graph.Groups

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


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

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

响应 2

下面是使用 @odata.deltaLink 从查询初始化中获取的响应的示例。所有这三个属性都包含在响应中，并且不知道自获取后 @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

下一个示例演示初始请求选择三个属性进行更改跟踪，以及可选的最小响应行为：

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


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

// To initialize your graphClient, see https://free.blessedness.top/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");
});



// 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"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

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

requestParameters := &graphgroups.GroupsDeltaRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","mailNickname"},
}
configuration := &graphgroups.GroupsDeltaRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://free.blessedness.top/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Groups().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.groups().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "description", "mailNickname"};
	requestConfiguration.headers.add("Prefer", "return=minimal");
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?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();


Import-Module Microsoft.Graph.Groups

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


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

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


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

响应 3

下面是使用 @odata.deltaLink 从查询初始化中获取的响应的示例。属性 mailNickname 未包含在内，这意味着它自上次增量查询以来没有更改; 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
    }
  ]
}

反馈

此页面是否有帮助？