orgContact： delta

命名空间：microsoft.graph

获取新创建、更新或删除的组织联系人，而无需对整个集合执行完整读取。 有关详细信息，请参阅更改跟踪。

权限

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

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

HTTP 请求

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

GET /contacts/delta

查询参数

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

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

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

查询参数	类型	说明
$deltatoken	string	在上一个 增量 函数调用同一组织联系人集合的 URL 中@odata.deltaLink返回的 状态令牌，指示完成这一轮更改跟踪。 在该集合的下一轮更改跟踪的第一个请求中保存并应用整个 @odata.deltaLink URL（包括此令牌）。
$skiptoken	string	在上一个 增量 函数调用的 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 响应代码和 ab 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 值的属性。
• 如果属性未更改，则旧值将包括在响应中。
• 如果该属性以前从未设置过，则它根本不会包含在响应中。

注意： 使用此行为，无法通过查看响应来判断属性是否正在更改。 此外，增量响应往往很大，因为它们包含所有属性值，如示 例 2 所示。

备用：仅返回更改的属性

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

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

注意： 可以在 Delta 循环中的任何时间点将标头添加到 @odata.deltaLink 请求中。 标头仅影响响应中包含的属性集，并且不会影响增量查询的运行方式。 请参阅示例 3。

示例

示例 1：默认属性

请求

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

HTTP

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

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

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

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/contacts/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:@"/contacts/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];
        MSGraphOrgContact *orgContact = [[MSGraphOrgContact alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

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

Java

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

OrgContactDeltaCollectionPage delta = graphClient.contacts()
    .delta()
    .buildRequest()
    .get();

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

Go

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

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

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

PowerShell

Import-Module Microsoft.Graph.Identity.DirectoryManagement

Get-MgContactDelta

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

响应

以下示例所示为使用从查询初始化获得的 @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：选择三个属性

请求

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

HTTP

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Contacts
    .Delta()
    .Request()
    .Select("displayName,jobTitle,mail")
    .GetAsync();

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

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/contacts/delta')
    .select('displayName,jobTitle,mail')
    .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:@"/contacts/delta?$select=displayName,jobTitle,mail"]]];
[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];
        MSGraphOrgContact *orgContact = [[MSGraphOrgContact alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

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

Java

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

OrgContactDeltaCollectionPage delta = graphClient.contacts()
    .delta()
    .buildRequest()
    .select("displayName,jobTitle,mail")
    .get();

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

Go

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

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

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

PowerShell

Import-Module Microsoft.Graph.Identity.DirectoryManagement

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

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

响应

以下示例所示为使用从查询初始化获得的 @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：备用最小响应行为

请求

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

HTTP

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Contacts
    .Delta()
    .Request()
    .Header("Prefer","return=minimal")
    .Select("displayName,jobTitle,mail")
    .GetAsync();

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

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

let delta = await client.api('/contacts/delta')
    .header('Prefer','return=minimal')
    .select('displayName,jobTitle,mail')
    .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:@"/contacts/delta?$select=displayName,jobTitle,mail"]]];
[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];
        MSGraphOrgContact *orgContact = [[MSGraphOrgContact 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"));

OrgContactDeltaCollectionPage delta = graphClient.contacts()
    .delta()
    .buildRequest( requestOptions )
    .select("displayName,jobTitle,mail")
    .get();

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

Go

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

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

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

PowerShell

Import-Module Microsoft.Graph.Identity.DirectoryManagement

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

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

响应

以下示例所示为使用从查询初始化获得的 @odata.deltaLink 时的响应。 请注意，mail 属性不包括在内，这意味着它在上一轮 Delta 查询之后未发生更改；并且 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 数据更改。