event: delta

项目
10/28/2023

命名空间：microsoft.graph

重要

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

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

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

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

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

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

此 API 可用于以下国家级云部署。

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

权限

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

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

HTTP 请求

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

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

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

在指定的用户日历 (s) 中，对从特定日期/时间开始或之后的所有事件或事件应用 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}

日历上的 Delta 函数组日历中的视图

若要在组日历的日历视图中获取增量更改，请执行以下操作：

GET /groups/{id}/calendarView?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 格式表示。例如，“2019-11-08T19：00：00-08：00”。时区在参数值的时区偏移量部分中指定，并且不受标头（如果存在）的影响 `Prefer: outlook.timezone` 。如果值中未包含时区偏移量，则将其解释为 UTC。对于日历中事件的增量，可选。对于 calendarView 上的增量是必需的。
endDateTime	String	时间范围的结束日期和时间以 ISO 8601 格式表示。例如，“2019-11-08T20：00：00-08：00”。时区在参数值的时区偏移量部分中指定，并且不受标头（如果存在）的影响 `Prefer: outlook.timezone` 。如果值中未包含时区偏移量，则将其解释为 UTC。对日历中的事件不支持delta。对于 calendarView 上的增量是必需的。
$deltatoken	string	在上一个 delta 函数的 URL 中`@odata.deltaLink`返回的状态令牌调用同一日历视图，指示完成这一轮更改跟踪。在该日历视图的下一轮更改跟踪的第一个请求中保存并应用包括此令牌的整个 `@odata.deltaLink` URL。
$skiptoken	string	之前的 delta 函数调用的 `@odata.nextLink` URL 中返回的状态令牌，指示同一个日历视图中有进一步的更改需要跟踪。

OData 查询参数

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

请求标头

名称	类型	说明
Authorization	string	持有者 {token}。必填。详细了解身份验证和授权。
Content-Type	string	application/json. 必需。
Prefer	string	odata.maxpagesize={x}。可选。
Prefer	string	outlook.timezone={时区字符串}。可选，如果缺省，则采用 UTC。

响应

事件 (预览) 的 Delta 函数

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

calendarView 上的 Delta 函数

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

应获取通常从 GET /calendarView 请求获取的所有属性。

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

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

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

示例

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

请求

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

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

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

Prefer: odata.maxpagesize=1



mgc-beta users calendar events delta get --user-id {user-id} --start-date-time "2020-06-12T00:00:00Z"

重要

Microsoft Graph SDK 默认使用 v1.0 版本的 API，并且不支持 beta 版本中提供的所有类型、属性和 API。有关使用 SDK 访问 beta API 的详细信息，请参阅将 Microsoft Graph SDK 与 beta API 配合使用。

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


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z')
	.version('beta')
	.get();

重要

有关如何将 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/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。使用返回@odata.nextLink的查询继续调用 delta 函数，直到在该日历视图中获取所有事件，并在@odata.deltaLink响应中获取。

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



mgc-beta users calendars calendar-view delta get --user-id {user-id} --calendar-id {calendar-id} --start-date-time "2020-06-01T00:00:00Z" --end-date-time "2020-06-10T00:00:00Z"

重要

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


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z')
	.version('beta')
	.get();

重要

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

响应

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(event)",
    "@odata.nextLink": "https://graph.microsoft.com/beta/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?$skiptoken=R0usmcdvmMu7jxWP8",
    "value": [
        {
            "@odata.type": "#microsoft.graph.event",
            "@odata.etag": "W/\"Jdsb3FEkPk2qoUHCdliYowACwixTgw==\"",
            "createdDateTime": "2020-06-16T04:05:43.8668791Z",
            "lastModifiedDateTime": "2020-06-16T04:08:27.354268Z",
            "changeKey": "Jdsb3FEkPk2qoUHCdliYowACwixTgw==",
            "categories": [],
            "transactionId": null,
            "originalStartTimeZone": "Pacific Standard Time",
            "originalEndTimeZone": "Pacific Standard Time",
            "uid": "040000008200E00074C5B7101A82E00800000000F088B8B95843D601000000000000000010000000165CD5547CFC9545B6492B261750B48C",
            "reminderMinutesBeforeStart": 15,
            "isReminderOn": false,
            "hasAttachments": false,
            "subject": "Summer party",
            "bodyPreview": "",
            "importance": "normal",
            "sensitivity": "normal",
            "isAllDay": false,
            "isCancelled": false,
            "isOrganizer": true,
            "IsRoomRequested": false,
            "AutoRoomBookingStatus": "None",
            "responseRequested": true,
            "seriesMasterId": null,
            "showAs": "busy",
            "type": "singleInstance",
            "webLink": "https://outlook.office365.com/owa/?itemid=AAMkADI5MAAKkeE1QAAA%3D&exvsurl=1&path=/calendar/item",
            "onlineMeetingUrl": null,
            "isOnlineMeeting": false,
            "onlineMeetingProvider": "unknown",
            "allowNewTimeProposals": true,
            "OccurrenceId": null,
            "isDraft": false,
            "recurrence": null,
            "AutoRoomBookingOptions": null,
            "onlineMeeting": null,
            "id": "AAMkADI5MAAKkeE1QAAA=",
            "responseStatus": {
                "response": "none",
                "time": "0001-01-01T00:00:00Z"
            },
            "body": {
                "contentType": "html",
                "content": "<html>\r\n<head></head>\r\n<body lang=\"EN-US\" link=\"#0563C1\" vlink=\"#954F72\" style=\"\">\r\n<div class=\"WordSection1\">\r\n<p class=\"MsoNormal\">&nbsp;</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "start": {
                "dateTime": "2020-06-02T20:00:00.0000000",
                "timeZone": "UTC"
            },
            "end": {
                "dateTime": "2020-06-02T22:30:00.0000000",
                "timeZone": "UTC"
            },
            "location": {
                "displayName": "",
                "locationType": "default",
                "uniqueIdType": "unknown",
                "address": {
                    "type": "unknown"
                },
                "coordinates": {}
            },
            "locations": [],
            "attendees": [
                {
                    "type": "required",
                    "status": {
                        "response": "none",
                        "time": "0001-01-01T00:00:00Z"
                    },
                    "emailAddress": {
                        "name": "Samantha Booth",
                        "address": "samanthab@contoso.com"
                    }
                }
            ],
            "organizer": {
                "emailAddress": {
                    "name": "Samantha Booth",
                    "address": "samanthab@contoso.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.event",
            "@odata.etag": "W/\"Jdsb3FEkPk2qoUHCdliYowACwixTfw==\"",
            "createdDateTime": "2020-06-16T04:06:18.386713Z",
            "lastModifiedDateTime": "2020-06-16T04:08:19.5694048Z",
            "changeKey": "Jdsb3FEkPk2qoUHCdliYowACwixTfw==",
            "categories": [],
            "transactionId": null,
            "originalStartTimeZone": "Pacific Standard Time",
            "originalEndTimeZone": "Pacific Standard Time",
            "uid": "040000008200E00074C5B7101A82E0080000000060074BC55843D6010000000000000000100000002D33A89F36B10D43A12FD990B62858B2",
            "reminderMinutesBeforeStart": 15,
            "isReminderOn": true,
            "hasAttachments": false,
            "subject": "Summer party part 2",
            "bodyPreview": "",
            "importance": "normal",
            "sensitivity": "normal",
            "isAllDay": false,
            "isCancelled": false,
            "isOrganizer": true,
            "IsRoomRequested": false,
            "AutoRoomBookingStatus": "None",
            "responseRequested": true,
            "seriesMasterId": null,
            "showAs": "busy",
            "type": "singleInstance",
            "webLink": "https://outlook.office365.com/owa/?itemid=AAMkADI5MAAKkeE1RAAA%3D&exvsurl=1&path=/calendar/item",
            "onlineMeetingUrl": null,
            "isOnlineMeeting": false,
            "onlineMeetingProvider": "unknown",
            "allowNewTimeProposals": true,
            "OccurrenceId": null,
            "isDraft": false,
            "recurrence": null,
            "AutoRoomBookingOptions": null,
            "onlineMeeting": null,
            "id": "AAMkADI5MAAKkeE1RAAA=",
            "responseStatus": {
                "response": "none",
                "time": "0001-01-01T00:00:00Z"
            },
            "body": {
                "contentType": "html",
                "content": "<html>\r\n<head></head>\r\n<body lang=\"EN-US\" link=\"#0563C1\" vlink=\"#954F72\" style=\"\">\r\n<div class=\"WordSection1\">\r\n<p class=\"MsoNormal\">&nbsp;</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "start": {
                "dateTime": "2020-06-04T19:30:00.0000000",
                "timeZone": "UTC"
            },
            "end": {
                "dateTime": "2020-06-04T22:30:00.0000000",
                "timeZone": "UTC"
            },
            "location": {
                "displayName": "",
                "locationType": "default",
                "uniqueIdType": "unknown",
                "address": {
                    "type": "unknown"
                },
                "coordinates": {}
            },
            "locations": [],
            "attendees": [
                {
                    "type": "required",
                    "status": {
                        "response": "none",
                        "time": "0001-01-01T00:00:00Z"
                    },
                    "emailAddress": {
                        "name": "Samantha Booth",
                        "address": "samanthab@contoso.com"
                    }
                }
            ],
            "organizer": {
                "emailAddress": {
                    "name": "Samantha Booth",
                    "address": "samanthab@contoso.com"
                }
            }
        }
    ]
}

通过

event: delta

权限

HTTP 请求

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

用户日历中的 calendarView 上的 Delta 函数

日历上的 Delta 函数组日历中的视图

查询参数

OData 查询参数

请求标头

响应

事件 (预览) 的 Delta 函数

calendarView 上的 Delta 函数

示例

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

请求

响应

示例 2：calendarView 上的 Delta 函数

请求

响应

反馈

其他资源

通过

event: delta

权限

HTTP 请求

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

用户日历中的 calendarView 上的 Delta 函数

日历上的 Delta 函数组日历中的视图

查询参数

OData 查询参数

请求标头

响应

事件 (预览) 的 Delta 函数

calendarView 上的 Delta 函数

示例

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

请求

响应

示例 2：calendarView 上的 Delta 函数

请求

响应

相关内容

反馈

其他资源