event: deltaevent: delta

命名空间:microsoft.graphNamespace: microsoft.graph

获取用户主日历的 calendarView(事件范围)中已添加、删除或更新的事件集。Get a set of events that have been added, deleted, or updated in a calendarView (a range of events) of the user's primary calendar.

对于用户主日历的日期范围,对事件的 delta 函数调用与 GET /calendarview 请求相似,但是可通过在对其的一次或多次调用中正确应用状态令牌来查询该日历视图中的增量更改这一点除外。通过此功能,你可以维护和同步本地存储的主日历的用户事件,而无需每次都从服务器中获取该日历的所有事件。A delta function call for events is similar to a GET /calendarview request for a range of dates in the user's primary calendar, except that by appropriately applying state tokens in one or more of these calls, you can query for incremental changes in that calender view. This allows you to maintain and synchronize a local store of a user's events in the primary calendar, without having to fetch all the events of that calendar from the server every time.

权限Permissions

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) Calendars.ReadCalendars.Read
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) Calendars.ReadCalendars.Read
应用程序Application Calendars.ReadCalendars.Read

HTTP 请求HTTP request

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

查询参数Query parameters

跟踪事件更改会引发一组对 delta 函数的一次或多次调用。如果要使用任意查询参数($deltatoken$skiptoken 除外),则必须在最初的 delta 请求中指定它。Microsoft Graph 自动将指定的任意参数编码为响应中提供的 nextLinkdeltaLink URL 的令牌部分。你只需预先指定任意所需查询参数一次。在后续的请求中,只需复制并应用以前响应中的 nextLinkdeltaLink URL,因为该 URL 已包含所需的编码参数。Tracking changes in events incurs a round of one or more delta function calls. If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response. You only need to specify any desired query parameters once upfront. In subsequent requests, simply copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded, desired parameters.

查询参数Query parameter 类型Type 说明Description
startDateTimestartDateTime StringString 时间范围的开始日期和时间以 ISO 8601 格式表示。例如,“2015-11-08T19:00:00.0000000”。The start date and time of the time range, represented in ISO 8601 format. For example, "2015-11-08T19:00:00.0000000".
endDateTimeendDateTime StringString 时间范围的结束日期和时间以 ISO 8601 格式表示。例如,“2015-11-08T20:00:00.0000000”。The end date and time of the time range, represented in ISO 8601 format. For example, "2015-11-08T20:00:00.0000000".
$deltatoken$deltatoken stringstring 对同一个日历视图之前的 delta 函数调用的 deltaLink URL 中返回的状态令牌,指示该组更改跟踪的完成状态。将此令牌包含在对该日历视图的下一组更改追踪的首次请求中,并保存和应用整个 deltaLink URL。A state token returned in the deltaLink URL of the previous delta function call for the same calendar view, indicating the completion of that round of change tracking. Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that calendar view.
$skiptoken$skiptoken stringstring 之前的 delta 函数调用的 nextLink URL 中返回的状态令牌,指示同一个日历视图中有进一步的更改需要跟踪。A state token returned in the nextLink URL of the previous delta function call, indicating there are further changes to be tracked in the same calendar view.

对日历视图执行 delta 查询时,预计获取通常从 GET /calendarview 请求获取的所有属性。在此情况下,不支持 $selectWhen you do a delta query on a calendar view, expect to get all the properties you'd normally get from a GET /calendarview request. $select is not supported in this case.

请求标头Request headers

名称Name 类型Type 说明Description
AuthorizationAuthorization stringstring Bearer {token}。必需。Bearer {token}. Required.
Content-TypeContent-Type stringstring application/json. Required.application/json. Required.
PreferPrefer stringstring odata.maxpagesize={x}。可选。odata.maxpagesize={x}. Optional.
PreferPrefer stringstring {Time zone}。可选,如果缺省,则采用 UTC。{Time zone}. Optional, UTC assumed if absent.

响应Response

如果成功,此方法在响应正文中返回 200 OK 响应代码和 event 集合对象。If successful, this method returns a 200 OK response code and event collection object in the response body.

示例Example

请求Request

以下示例演示了如何执行单次 delta 函数调用,并将响应正文中的事件最大数目限制为 2。The following example shows how to make a single delta function call, and limit the maximum number of events in the response body to 2.

若要跟踪日历视图的更改,要使用正确的状态令牌执行一次或多次 delta 函数调用来获取上次增量查询后的增量更改集。To track changes in a calendar view, you would make one or more delta function calls, with appropriate state tokens, to get the set of incremental changes since the last delta query.

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

Prefer: odata.maxpagesize=2
响应Response

如果请求成功,响应将包括状态令牌,即 skipToken(位于 _@odata.nextLink_ 响应头中)或 deltaToken(位于 _@odata.deltaLink_ 响应头中)。它们分别指示应继续此组调用还是已获取该组的所有更改。If the request is successful, the response would include a state token, which is either a skipToken (in an _@odata.nextLink_ response header) or a deltaToken (in an _@odata.deltaLink_ response header). Respectively, they indicate whether you should continue with the round or you have completed getting all the changes for that round.

以下响应显示了 _@odata.nextLink_ 响应头中的 skipTokenThe response below shows a skipToken in an _@odata.nextLink_ response header.

注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

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

{
  "@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"
      },
      "iCalUId": "iCalUId-value",
      "reminderMinutesBeforeStart": 99,
      "isReminderOn": true
    }
  ]
}

另请参阅See also