orgContact： delta

2024-11-06

命名空间：microsoft.graph

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

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

权限

为此 API 选择标记为最低特权的权限。只有在应用需要它时，才使用更高的特权权限。有关委派权限和应用程序权限的详细信息，请参阅权限类型。要了解有关这些权限的详细信息，请参阅权限参考。

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

重要

在具有工作或学校帐户的委托方案中，必须为登录用户分配受支持的Microsoft Entra角色或具有支持的角色权限的自定义角色。此操作支持以下最低特权角色。

目录读取器 - 读取基本属性
全局读取者
目录作者
Intune管理员
用户管理员

HTTP 请求

若要开始跟踪更改，请发出一个请求，包括联系人资源上的 delta 函数。

GET /contacts/delta

查询参数

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

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

在后续请求中，复制并应用上一 @odata.nextLink 响应中的或 @odata.deltaLink URL。该 URL 已包含编码参数。

查询参数	类型	说明
$deltatoken	string	在同一组织联系人集合的`@odata.deltaLink`上一个 delta 函数的 URL 中返回的状态令牌调用，指示完成这一轮更改跟踪。在该集合的下一轮更改跟踪的第一个请求中保存并应用整个 `@odata.deltaLink` URL，包括此令牌。
$skiptoken	string	在上一个 delta 函数调用的 URL 中`@odata.nextLink`返回的状态令牌，指示在同一组织联系人集合中要跟踪进一步的更改。

OData 查询参数

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

像在任何 GET 请求中一样，你可以使用 $select 查询参数以仅指定获取最佳性能所需的属性。始终返回 id 属性。
对的支持有限 $filter：
- 唯一支持的 $filter 表达式用于跟踪对特定对象 $filter=id+eq+{value} 的更改。可以筛选多个对象。例如，https://graph.microsoft.com/v1.0/contacts/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'。筛选对象限制为 50 个。

请求标头

名称	说明
Authorization	持有者 {token}。必填。详细了解身份验证和授权。
Prefer	return=minimal 在使用 `@odata.deltaLink` 的请求中执行此标头将仅返回自上一轮之后发生更改的对象属性。可选。

请求正文

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

响应

如果成功，此方法在 200 OK 响应正文中返回响应代码和 orgContact 集合对象。该响应还包括 @odata.nextLinkURL 或 @odata.deltaLinkURL。

如果返回 @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/contacts/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.Contacts.Delta.GetAsDeltaGetResponseAsync();



mgc contacts 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.Contacts().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.contacts().delta().get();


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?php
use Microsoft\Graph\GraphServiceClient;


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


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


Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgContactDelta


# 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.contacts.delta.get()

响应

下面是使用 @odata.deltaLink 从查询初始化中获取的响应的示例。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "companyName": "companyName-value",
      "department": "department-value",
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "id": "string (identifier)",
      "jobTitle": "jobTitle-value",
      "mail": "mail-value",
      "mailNickname": "mailNickname-value",
      "surname": "surname-value"
    }
  ]
}

示例 2：选择三个属性

请求

下一个示例所示为通过默认响应行为选择三种更改跟踪属性时的初始请求。

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


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



mgc contacts delta get --select "displayName,jobTitle,mail"



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

requestParameters := &graphcontacts.ContactsDeltaRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","jobTitle","mail"},
}
configuration := &graphcontacts.ContactsDeltaRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Contacts().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.contacts().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "jobTitle", "mail"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


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


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

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


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


Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgContactDelta -Property "displayName,jobTitle,mail"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.contacts.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","mail"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

响应

下面是使用 @odata.deltaLink 从查询初始化中获取的响应的示例。所有这三个属性都包含在响应中，并且不知道自获取后 @odata.deltaLink 哪些属性已更改。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": "jobTitle-value",
      "mail": null
    }
  ]
}

示例 3：备用最小响应行为

请求

下一个示例所示为通过备用最小响应行为选择三种更改跟踪属性时的初始请求。

GET https://graph.microsoft.com/v1.0/contacts/delta?$select=displayName,jobTitle,mail
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.Contacts.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","jobTitle","mail" };
	requestConfiguration.Headers.Add("Prefer", "return=minimal");
});



mgc contacts delta get --select "displayName,jobTitle,mail"



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

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

requestParameters := &graphcontacts.ContactsDeltaRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","jobTitle","mail"},
}
configuration := &graphcontacts.ContactsDeltaRequestBuilderGetRequestConfiguration{
	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.Contacts().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.contacts().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "jobTitle", "mail"};
	requestConfiguration.headers.add("Prefer", "return=minimal");
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


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


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

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

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


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


Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgContactDelta -Property "displayName,jobTitle,mail"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.contacts.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","mail"],
)

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


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

响应

下面是使用 @odata.deltaLink 从查询初始化中获取的响应的示例。属性 mail 未包含在内，这意味着它自上次增量查询以来没有更改; displayName 并且 jobTitle 包含此属性意味着其值已更改。

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#contacts",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/contacts/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "displayName-value",
      "jobTitle": null
    }
  ]
}

使用 Delta 查询跟踪 Microsoft Graph 数据更改。

通过