event: delta

项目
10/02/2023

命名空间：microsoft.graph

获取一组事件已在用户主日历的 calendarView （由开始和结束日期定义的事件范围）中添加、删除或更新的资源。

通常，同步本地存储中 calendarView 中的事件需要一轮多次增量函数调用。初始调用是完全同步，每个后续增量调用在同一轮中获取增量更改（添加、删除或更新）。这样，就可以在指定的 calendarView中维护和同步指定事件的本地存储，而无需每次从服务器中提取该日历的所有事件。

以下国家云部署支持此 API。

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

权限

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

权限类型	权限（从最低特权到最高特权）
委派（工作或学校帐户）	Calendars.ReadBasic、Calendars.Read
委派（个人 Microsoft 帐户）	Calendars.ReadBasic、Calendars.Read
应用程序	Calendars.ReadBasic、Calendars.Read

HTTP 请求

GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}
GET /users/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}

查询参数

跟踪事件中的更改会导致一轮或多次增量函数调用。如果要使用任意查询参数（$deltatoken 和 $skiptoken 除外），则必须在最初的 delta 请求中指定它。 Microsoft Graph 自动将指定的任意参数编码为响应中提供的 @odata.nextLink 或 @odata.deltaLink URL 的令牌部分。只需预先指定所需的任何查询参数一次。在后续请求中，只需复制并应用 @odata.nextLink 上一响应中的或 @odata.deltaLink URL，因为该 URL 已包含编码的所需参数。

查询参数	类型	说明
startDateTime	String	时间范围的开始日期和时间以 ISO 8601 格式表示。例如，“2015-11-08T19:00:00.0000000”。
endDateTime	String	时间范围的结束日期和时间以 ISO 8601 格式表示。例如，“2015-11-08T20:00:00.0000000”。
$deltatoken	string	在上一个 delta 函数的 URL 中`@odata.deltaLink`返回的状态令牌调用同一日历视图，指示完成这一轮更改跟踪。在该日历视图的下一轮更改跟踪的第一个请求中保存并应用包括此令牌的整个 `@odata.deltaLink` URL。
$skiptoken	string	之前的 delta 函数调用的 `@odata.nextLink` URL 中返回的状态令牌，指示同一个日历视图中有进一步的更改需要跟踪。

OData 查询参数

calendarView需要增量函数调用，以返回通常从GET /calendarView请求中获取的相同属性。不能使用 $select 只获取这些属性的子集。
calendarView 的增量函数不支持其他 OData 查询参数：$expand、$filter、$orderby和 $search。

请求标头

名称	类型	说明
Authorization	string	持有者 {token}。必填。
Content-Type	string	application/json. 必需。
Prefer	string	odata.maxpagesize={x}。可选。
Prefer	string	{Time zone}。可选，如果缺省，则采用 UTC。

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 event 集合对象。

在calendarView的日期范围绑定的增量函数调用中，你可能会发现增量调用在@removed下返回两种类型的事件，原因deleted：

在日期范围内且自上一次增量调用以来已删除的事件。
在日期范围外部的事件，以及自上一次增量调用以来已添加、删除或更新的事件。

根据方案所需的日期范围筛选 @removed 下的事件。

示例

请求

以下示例演示了如何执行单次 delta 函数调用，并将响应正文中的事件最大数目限制为 2。

若要跟踪日历视图的更改，要使用正确的状态令牌执行一次或多次 delta 函数调用来获取上次增量查询后的增量更改集。

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?startdatetime={start_datetime}&enddatetime={end_datetime}
Prefer: odata.maxpagesize=2


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

var graphClient = new GraphServiceClient(requestAdapter);

var result = await graphClient.Me.CalendarView.Delta.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.StartDateTime = "{start_datetime}";
	requestConfiguration.QueryParameters.EndDateTime = "{end_datetime}";
	requestConfiguration.Headers.Add("Prefer", "odata.maxpagesize=2");
});

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



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "odata.maxpagesize=2")


requestStartDateTime := "{start_datetime}"
requestEndDateTime := "{end_datetime}"

requestParameters := &graphusers.ItemCalendarViewDelta()RequestBuilderGetQueryParameters{
	StartDateTime: &requestStartDateTime,
	EndDateTime: &requestEndDateTime,
}
configuration := &graphusers.ItemCalendarViewDelta()RequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

delta, err := graphClient.Me().CalendarView().Delta().Get(context.Background(), configuration)

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


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

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("Prefer", "odata.maxpagesize=2"));
requestOptions.add(new QueryOption("startdatetime", "{start_datetime}"));
requestOptions.add(new QueryOption("enddatetime", "{end_datetime}"));

EventDeltaCollectionPage delta = graphClient.me().calendarView()
	.delta()
	.buildRequest( requestOptions )
	.get();

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


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendarView/delta?startdatetime={start_datetime}&enddatetime={end_datetime}')
	.header('Prefer','odata.maxpagesize=2')
	.get();

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


<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$headers = [
		'Prefer' => 'odata.maxpagesize=2',
	];
$requestConfiguration->headers = $headers;

$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->startDateTime = "{start_datetime}";
$queryParameters->endDateTime = "{end_datetime}";
$requestConfiguration->queryParameters = $queryParameters;


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

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


# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(request_adapter)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		start_date_time = "{start_datetime}",
		end_date_time = "{end_datetime}",
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
headers = {
			'Prefer' : "odata.maxpagesize=2",
}

)

result = await graph_client.me.calendar_view.delta.get(request_configuration = request_configuration)

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

响应

如果请求成功，响应将包括状态令牌，该令牌是@odata.nextLink 响应标头) 中的 skipToken (，或者是 @odata.deltaLink 响应标头) 中的 deltaToken (。它们分别指示是应继续执行回合，还是已完成获取该回合的所有更改。

以下响应显示了 @odata.nextLink 响应头中的 skipToken。

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

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

{
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken={_skipToken_}",
  "value": [
    {
      "originalStartTimeZone": "originalStartTimeZone-value",
      "originalEndTimeZone": "originalEndTimeZone-value",
      "responseStatus": {
        "response": "response-value",
        "time": "datetime-value"
      },
      "transactionId": null,
      "iCalUId": "iCalUId-value",
      "reminderMinutesBeforeStart": 99,
      "isDraft": false,
      "isReminderOn": true
    }
  ]
}

event: delta

权限

HTTP 请求

查询参数

OData 查询参数

请求标头

响应

示例

请求

响应

另请参阅

其他资源

其他资源