event: delta

项目
08/25/2021

命名空间：microsoft.graph

重要

Microsoft Graph版本下的 /beta API 可能会发生更改。不支持在生产应用程序中使用这些 API。若要确定 API 是否在 v1.0 中可用，请使用版本选择器。

获取一组已在一个或多个日历中添加、删除或更新的事件资源。

可以在邮箱的所有日历或特定日历中的事件，或日历的开始日期和结束日期) 定义的 calendarView (事件范围的事件集合中，获取这些增量更改的特定类型的信息。日历可以是默认日历或用户的其他一些指定日历。在 calendarView 上获取增量更改的情况下，日历还可以是组日历。

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

下表列出了事件上的 delta 函数与日历中 calendarView 上的 delta 函数之间的差异。

事件上的 Delta 函数	calendarView 上的 Delta 函数
获取日历中未受开始日期和结束日期范围限制的所有事件的增量更改。或者，可以从该日期/时间或之后开始，获取由开始时间绑定的日历中的事件的增量更改。	获取 calendarView 的开始日期和结束日期/时间内事件的增量更改。
出于性能原因，仅返回一组有限的事件属性。随后用于扩展 `GET /events/{id}` 任何事件的客户端。	服务器端扩展返回一组更完整的事件属性。
响应包括单个实例和定期系列主控对象。	响应包括单个实例，以及定期系列的发生次数和异常。
适用于用户日历中的事件，但不包括组日历。	适用于用户和组日历中的事件。
当前仅在 beta 版本中可用。	在 v1.0 和 beta 版本中可用。

权限

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

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

HTTP 请求

本节显示初始 delta 函数调用的 HTTP 请求语法，以启动检索指定日历或日历视图中的所有事件的完全同步。此语法不包含任何状态令牌。

成功响应的或 nextLink 中返回的查询 URL deltaLink 包括状态令牌。对于任何后续 delta 函数调用，请使用中或前面的 nextLink 查询 deltaLink URL。

用户日历中事件的 Delta 函数 (预览)

对从特定日期/时间开始或之后的所有事件应用 delta 函数，具体位置为 (日历) ：

若要获取用户邮箱中所有事件或从指定日期/时间开始或之后的事件的增量 更改：

GET /me/events/delta 
GET /users/{id | userPrincipalName}/events/delta 

GET /me/events/delta?startDateTime={start_datetime}
GET /users/{id | userPrincipalName}/events/delta?startDateTime={start_datetime}

若要获取用户默认日历中所有事件或自指定日期/时间开始或之后的事件的增量更改：

GET /me/calendar/events/delta 
GET /users/{id | userPrincipalName}/calendar/events/delta 

GET /me/calendar/events/delta?startDateTime={start_datetime} 
GET /users/{id | userPrincipalName}/calendar/events/delta?startDateTime={start_datetime}

若要获取所有事件的增量更改，或获取指定用户日历中指定日期/时间或之后开始 的事件的增量更改：

GET /me/calendars/{id}/events/delta 
GET /users/{id | userPrincipalName}/calendars/{id}/events/delta 

GET /me/calendars/{id}/events/delta?startDateTime={start_datetime} 
GET /users/{id | userPrincipalName}/calendars/{id}/events/delta?startDateTime={start_datetime}

若要获取增量更改，或获取指定日历组和日历中指定日期/时间或之后开始的事件：

GET /me/calendargroups/{id}/calendars/{id}/events/delta 
GET /users/{id | userPrincipalName}/calendargroups/{id}/calendars/{id}/events/delta 

GET /me/calendargroups/{id}/calendars/{id}/events/delta?startDateTime={start_datetime} 
GET /users/{id | userPrincipalName}/calendargroups/{id}/calendars/{id}/events/delta?startDateTime={start_datetime}

用户日历中 calendarView 上的 Delta 函数

在 指定的用户 日历中，对以开始日期和结束日期/时间分隔的事件范围应用 delta 函数：

若要获取用户默认日历的日历视图中 的增量更改：

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

若要获取指定用户日历的日历视图中 的增量更改：

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

组日历中 calendarView 上的 Delta 函数

若要获取组日历的日历视图中 的增量更改：

GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}

查询参数

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

查询参数	类型	说明
startDateTime	String	时间范围的开始日期和时间，以 ISO 8601 格式表示。例如，“2019-11-08T19:00:00-08:00”。时区在参数值的时区偏移部分指定，如果存在，则不会影响 `Prefer: outlook.timezone` 标头。如果值中未包含时区偏移量，则将其解释为 UTC。对于日历中事件的增量是可选的。对于 calendarView 上的 delta 是必需的。
endDateTime	String	时间范围的结束日期和时间，以 ISO 8601 格式表示。例如，“2019-11-08T20:00:00-08:00”。时区在参数值的时区偏移部分指定，如果存在，则不会影响 `Prefer: outlook.timezone` 标头。如果值中未包含时区偏移量，则将其解释为 UTC。不受日历中事件上的 delta 支持。对于 calendarView 上的 delta 是必需的。
$deltatoken	string	对同一个日历视图之前的 delta 函数调用的 `deltaLink` URL 中返回的状态令牌，指示该组更改跟踪的完成状态。将此令牌包含在对该日历视图的下一组更改追踪的首次请求中，并保存和应用整个 `deltaLink` URL。
$skiptoken	string	之前的 delta 函数调用的 `nextLink` URL 中返回的状态令牌，指示同一个日历视图中有进一步的更改需要跟踪。

OData 查询参数

预计 calendarView 上的 delta 函数调用将返回通常从请求获取的相同 GET /calendarview 属性。不能使用 $select 仅获取这些属性的子集。
delta 函数不支持用户日历中的事件或 calendarView 中的事件的以下查询参数：、 $expand 和 $filter $orderby $search $select 。

请求标头

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

响应

事件和预览 (Delta)

如果成功，此方法在响应正文中返回响应代码 200 OK 和事件集合。出于性能原因，响应中的每个事件仅包含 id 、type 、start 和 end 属性。随后 GET /events/{id} 使用展开响应中的任意事件。

calendarView 上的 Delta 函数

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

希望获取通常从请求获取的所有 GET /calendarview 属性。

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

日期范围内且自上一个 delta 调用以来 已删除 的事件。
超出日期范围且自上一次 delta 调用以来已添加、删除 或更新的事件 。

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

示例

示例 1：日历中事件的 Delta 函数 (预览)

请求

以下示例显示获取已登录用户的默认日历中事件的初始同步请求，这些事件发生在指定参数上或之后 startDateTime 。初始请求不包括任何状态令牌。

请求使用 Prefer: odata.maxpagesize 标头将每个响应中的最大事件数限制为 1。继续使用中 delta 返回的查询调用函数 @odata.nextLink ，直到响应 @odata.deltaLink 中收到。

GET https://graph.microsoft.com/beta/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z

Prefer: odata.maxpagesize=1

响应

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

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

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

{
  "@odata.nextLink":"https://graph.microsoft.com/beta/me/calendar/events/delta?$skiptoken=R0usmcdvmMu7jxWP8",
  "value": [
    { 
      "id": " AAMkADllMWMwNDkzLWJlY2EtNDIyOS1iZjAA=", 
      "type": "singleInstance", 
      "start": {  
             "DateTime": "2020-02-19T10:00:00.0000000",  
             "TimeZone": "UTC" 
         },  
       "end": {  
                "DateTime": "2020-02-19T11:00:00.0000000",  
                "TimeZone": "UTC"        
          }  
        } 
  ]
}

示例 2：calendarView 上的 Delta 函数

请求

以下示例显示获取已登录用户指定日历中的事件的初始同步请求，该请求位于 calendarView 指示的日期范围内。初始请求不包括任何状态令牌。

请求使用 Prefer: odata.maxpagesize 标头将每个响应中事件的最大数量限制为 2 个。继续使用中返回的查询调用函数，直到获取该日历视图中的所有事件和响应 delta @odata.nextLink 中的 @odata.deltaLink 。

HTTP

GET https://graph.microsoft.com/beta/me/calendars/AAMkADI5M1BbeAAA=/calendarview/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z

Prefer: odata.maxpagesize=2

响应