获取日历视图中事件的增量更改Get incremental changes to events in a calendar view

通过使用增量查询,你可以在指定的日历,或者日历中的定义事件集合(作为日历视图)中获取新的、更新的或删除的事件。By using delta query, you can get new, updated, or deleted events in a specified calendar(s), or within a defined collection of events (as a calendar view) in the calendar. 本文将介绍后一种情况(在日历视图中对事件进行此类增量更改)。This article describes the latter - getting such incremental changes to events in a calendar view.

注意 前者(对日历中的事件进行增量更改,而不受固定的开始日期和结束日期范围的约束)的功能目前仅在 beta 版中可用。Note The capability for the former - getting incremental changes to events in a calendar not bound to a fixed start and end date range - is currently available only in the beta version. 有关更多信息,请参阅 delta 函数。For more information, see delta function.

日历视图是某个日期/递减范围 (../me/calendarview) 内来自默认日历、用户的其他某个指定日历或者组日历的事件集合。A calendar view is a collection of events in a date/time range (../me/calendarview) from the default calendar or some other specified calendar of a user, or from a group calendar. 返回的事件可能包括定期系列事件的单个实例、发生次数和例外情况。The returned events may include single instances, or occurrences and exceptions of a recurring series. 借助增量数据,可以维护和同步用户事件的本地存储,而无需每次都从服务器提取整组用户事件。The delta data enables you to maintain and synchronize a local store of a user's events, without having to fetch the entire set of the user's events from the server every time.

增量查询既支持可检索指定日历视图中的所有事件的完全同步,也支持可检索自上次同步后日历视图中发生变化的事件的增量同步。通常情况下,开始时会执行一次完全同步,随后会定期获取相应日历视图的增量更改。Delta query supports both full synchronization that retrieves all the events in the specified calendar view, and incremental synchronization that retrieves those events that have changed in the calendar view since the last synchronization. Typically, you would do an initial full synchronization, and subsequently, get incremental changes to that calendar view periodically.

跟踪日历视图中的事件更改Track event changes in a calendar view

在日历视图中对事件执行增量查询专门针对你指定的日历和日期/时间范围。Delta query for events in a calendar view is specific to a calendar and date/time range that you specify. 若要跟踪多个日历中的更改,需要单独跟踪各个日历。To track the changes in multiple calendars, you need to track each calendar individually.

跟踪日历视图中的事件更改通常需要使用 delta 函数按轮发出一个或多个 GET 请求。Tracking event changes in a calendar view typically is a round of one or more GET requests with the delta function. 初始 GET 请求非常类似于列出 calendarView,区别在于要添加 delta 函数。The initial GET request is very much like the way you list a calendarView, except that you include the delta function. 下面是登录用户的默认日历中,“日历”视图的初始 GET 增量请求:The following is the initial GET delta request of a calendar view in the signed-in user's default calendar:

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

使用 delta 函数的 GET 请求返回以下任一内容:A GET request with the delta function returns either:

  • nextLink(包含具有 delta 函数调用和 skipToken 的 URL),或A nextLink (that contains a URL with a delta function call and a skipToken), or
  • deltaLink(包含具有 delta 函数调用和 deltaToken 的 URL)。A deltaLink (that contains a URL with a delta function call and deltaToken).

这些令牌是状态令牌,负责对 startDateTimeendDateTime 参数以及初始增量查询 GET 请求中的其他任何查询参数进行编码。These tokens are state tokens which encode the startDateTime and endDateTime parameters, and any other query parameter in your initial delta query GET request. 在后续请求中,无需包括这些参数,因为它们已在令牌中编码。You do not need to include these parameters in subsequent requests as they are encoded in the tokens.

状态令牌对客户端完全不透明。若要继续一轮事件更改跟踪,只需将最后一个 GET 请求返回的 nextLinkdeltaLink URL 复制并应用到同一日历视图的下一个 delta 函数调用即可。响应中返回的 deltaLink 表示当前一轮更改跟踪已完成。可以保存 deltaLink URL,并在开始下一轮时使用。State tokens are completely opaque to the client. To proceed with a round of change tracking, simply copy and apply the nextLink or deltaLink URL returned from the last GET request to the next delta function call for that same calendar view. A deltaLink returned in a response signifies that the current round of change tracking is complete. You can save and use the deltaLink URL when you begin the next round.

若要了解如何使用这些 nextLinkdeltaLink URL,请参阅下面的示例See the example below to learn how to use these nextLink and deltaLink URLs.

在日历视图的增量查询中使用查询参数Use query parameters in a delta query for calendar view

  • 添加 startDateTimeendDateTime 参数可以定义日历视图的日期/时间范围。Include the startDateTime and endDateTime parameters to define a date/time range for your calendar view.
  • 不支持 $select$select is not supported.

可选的请求头Optional request header

每个 delta 查询 GET 请求在响应中返回包含一个或多个事件的集合。Each delta query GET request returns a collection of one or more events in the response. 可以视需要指定请求头 Prefer: odata.maxpagesize={x},设置响应中可包含的事件数上限。You can optionally specify the request header, Prefer: odata.maxpagesize={x}, to set the maximum number of events in a response.

同步日历视图中事件的示例Example to synchronize events in a calendar view

以下示例展示了如何通过 3 个请求同步特定时间范围内的用户默认日历。此日历视图中有 5 个事件。The following example shows a series of 3 requests to synchronize the user's default calendar in a specific time range. There are 5 events in that calendar view.

为简洁起见,示例响应仅显示一部分事件属性。在实际调用中,大多数事件属性都会返回。For brevity, the sample responses show only a subset of the properties for an event. In an actual call, most event properties are returned.

另请了解下一轮该执行哪些操作。See also what you'll do in the next round.

第 1 步:示例第一个请求Step 1: sample initial request

在该示例中,由于登录用户的默认日历中的指定日历视图为首次同步,因此第一个同步请求不含任何状态令牌。In this example, the specified calendar view in the signed-in user's default calendar is being synchronized for the first time, so the initial sync request does not include any state token. 这一轮将返回此日历视图中的所有事件。This round will return all the events in that calendar view.

第一个请求指定以下内容:The first request specifies the following:

  • startDateTimeendDateTime 参数的日期/时间值。Date/time values for the startDateTime and endDateTime parameters.
  • 可选的请求头 odata.maxpagesize,表示一次返回 2 个事件。The optional request header, odata.maxpagesize, returning 2 events at a time.
GET https://graph.microsoft.com/v1.0/me/calendarView/delta?startdatetime=2016-12-01T00:00:00Z&enddatetime=2016-12-30T00:00:00Z HTTP/1.1
Prefer: odata.maxpagesize=2

示例第一个响应Sample initial response

响应中返回两个事件和一个包含 skipToken@odata.nextLink 响应头。nextLink URL 表示此日历视图中还有更多事件可获取。The response includes two events and a @odata.nextLink response header with a skipToken. The nextLink URL indicates there are more events in the calendar view to get.

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmcCM996atia_s",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIQ==\"",
            "subject":"Plan shopping list",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-09T20:30:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-09T22:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },      
            "id":"AAMkADNVxRAAA="
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIg==\"",
            "subject":"Pick up car",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T01:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-10T02:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxSAAA="
        }
    ]
}

第 2 步:示例第二个请求Step 2: sample second request

第二个请求指定上一个响应中返回的 nextLink URL。请注意,不再需要像第一个请求一样指定相同的 startDateTimeendDateTime 参数,因为 nextLink URL 中的 skipToken 已将其编码并包含在内。The second request specifies the nextLink URL returned from the previous response. Notice that it no longer has to specify the same startDateTime and endDateTime parameters as in the initial request, as the skipToken in the nextLink URL encodes and includes them.

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmcCM996atia_s HTTP/1.1
Prefer: odata.maxpagesize=2

示例第二个响应Sample second response

第二个响应中返回此日历视图中接下来的 2 个事件和另一个 nextLink(表示此日历视图中还有更多事件可获取)。The second response returns the next 2 events in the calendar view and another nextLink, indicating there are more events to get from the calendar view.

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmci39OQxqJrxK4",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIw==\"",
            "subject":"Get food",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T19:30:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-10T21:30:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxTAAA="
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvJA==\"",
            "subject":"Prepare food",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T22:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-11T00:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxUAAA="
        }
    ]
}

第 3 步:示例第三个请求Step 3: sample third request

第三个请求继续使用上一个同步请求返回的最新 nextLinkThe third request continues to use the latest nextLink returned from the last sync request.

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmci39OQxqJrxK4 HTTP/1.1
Prefer: odata.maxpagesize=2

示例第三个响应(即最终响应)Sample third and final response

第三个响应中返回此日历视图中仅剩的事件,以及表示已完成同步此日历视图的 deltaLink URL。保存并使用 deltaLink URL 在下一轮中同步此日历视图The third response returns the only remaining event in the calendar view, and a deltaLink URL which indicates synchronization is complete for this calendar view. Save and use the deltaLink URL to synchronize that calendar view in the next round.

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.deltaLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcMDNGg0J1E",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAALZu97g==\"",
            "subject":"Rest!",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-12T02:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-12T07:30:00.0000000",
                "timeZone":"UTC"
            },
            "location":{
                "displayName":"Home"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADj1HuAAA="
        }
    ]
}

下一轮:示例第一个请求The next round: sample first request

使用上一轮中最后一个请求返回的 deltaLink,可以只获取从那以后此日历视图中发生变化(已添加、删除或更新)的事件。假设你愿意在响应中保持页面大小上限不变,下一轮的第一个请求如下所示:Using the deltaLink from the last request in the last round, you will be able to get only those events that have changed (by being added, deleted, or updated) in that calendar view since then. Your first request in the next round will look like the following, assuming you prefer to keep the same maximum page size in the response:

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcMDNGg0J1E HTTP/1.1
Prefer: odata.maxpagesize=2

下一轮:示例第一个响应The next round: sample first response

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.deltaLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcFuQtZdtpk4",
    "value":[
        {
            "@odata.type": "#microsoft.graph.event",
            "id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQLkRkXbBznTvAADb6ytyAAA=",
            "@removed": {
                "reason": "deleted"
            }
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAALZu97w==\"",
            "subject":"Attend service",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-25T06:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-25T07:30:00.0000000",
                "timeZone":"UTC"
            },
            "location":{
                "displayName":"Chapel of Saint Ignatius",
                "address":{
                    "street":"900 Broadway",
                    "city":"Seattle",
                    "state":"WA",
                    "countryOrRegion":"United States",
                    "postalCode":""
                },
                "coordinates":{
                    "latitude":47.6105,
                    "longitude":-122.321
                }
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADj1HvAAA="
        }
    ]
}

另请参阅See also