Получение добавочных изменений для событий в представлении календаря
Используя дельта-запрос, вы можете получать новые, обновленные или удаленные события в указанном календаре или в определенной коллекции событий (как представление календаря) в календаре. В этой статье описывается последнее: получение таких добавочных изменений к событиям в представлении календаря.
Примечание.
Возможность первого — получение добавочных изменений в событиях в календаре, не привязанных к фиксированному диапазону дат начала и окончания, в настоящее время доступна только в бета-версии. Дополнительные сведения см. в статье функция delta.
Представление календаря — это коллекция событий в диапазоне даты и времени (.. /me/calendarView) из календаря по умолчанию или другого указанного календаря пользователя или из календаря группы. Возвращаемые события могут включать в себя отдельные экземпляры или вхождения и исключения из повторяющейся серии. Дельта-данные позволяют поддерживать и синхронизировать локальное хранилище событий пользователя без необходимости каждый раз получать весь набор событий пользователя с сервера.
Запрос изменений поддерживает как полную синхронизацию с получением всех событий в определенном представлении календаря, так и добавочную синхронизацию с получением тех событий, которые изменились в представлении календаря с момента последней синхронизации. Как правило, вы выполняете первоначальную полную синхронизацию, а затем периодически получаете дополнительные изменения в этом представлении календаря.
Отслеживание изменений событий в представлении календаря
Запрос изменений в представлении календаря для событий относится к указанным календарю и диапазону дат и времени. Чтобы отслеживать изменения в нескольких календарях, необходимо наблюдать за каждым календарем отдельно.
Как правило, цикл отслеживания изменений событий в представлении календаря состоит из одного или нескольких запросов GET с функцией delta. Первоначальный запрос GET очень похож на перечисление calendarView, за исключением того, что вы включаете функцию дельта. Ниже приведен исходный запрос GET delta для представления календаря в календаре, используемом по умолчанию пользователем, который вошел в систему.
GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}
Запрос GET с функцией delta возвращает одно из следующих значений:
- ссылку
@odata.nextLink
(содержащую URL-адрес с вызовом функции delta и$skipToken
), или - ссылку
@odata.deltaLink
(содержащую URL-адрес с вызовом функции delta и$deltaToken
).
Эти маркеры являются маркерами состояния, кодирующими параметры startDateTime и endDateTime, а также любой другой параметр в исходном разностном запросе GET. Эти параметры не нужно включать в последующих запросах, поскольку они закодированы в маркерах.
Маркеры состояния полностью непрозрачны для клиента.
Чтобы продолжить цикл отслеживания изменений, просто скопируйте и примените URL-адрес @odata.nextLink
или @odata.deltaLink
, возвращенный последним запросом GET, при следующем вызове функции delta для этого представления календаря. Ссылка @odata.deltaLink
в ответе означает, что текущий цикл отслеживания изменений завершен. Вы можете сохранить и использовать URL-адрес @odata.deltaLink
в начале следующего цикла.
См. пример использования этих URL-адресов @odata.nextLink
и @odata.deltaLink
.
Использование параметров запроса изменений для представления календаря
- Укажите параметры startDateTime и endDateTime, чтобы определить диапазон дат и времени для представления календаря.
- Параметр
$select
не поддерживается.
Необязательный заголовок запроса
Каждый разностный запрос GET возвращает коллекцию из одного или нескольких событий в отклике. При необходимости вы можете указать заголовок запроса Prefer: odata.maxpagesize={x}
, чтобы задать максимальное количество событий в отклике.
Пример: синхронизация событий в представлении календаря
В приведенном ниже примере показана серия из 3 запросов, синхронизирующих календарь пользователя по умолчанию в определенном диапазоне времени. Это представление календаря содержит 5 событий.
- Шаг 1. Пример исходного запроса и ответ
- Шаг 2. Пример второго запроса и ответ
- Шаг 3. Пример третьего запроса и последний ответ
В примерах показаны только некоторые свойства события. При фактическом вызове возвращается большинство свойств события.
Посмотрите, что вы будете делать в следующем раунде.
Шаг 1. Пример исходного запроса
В этом примере указанное представление календаря для календаря, используемого по умолчанию пользователем, который вошел в систему, синхронизируется впервые, поэтому исходный запрос на синхронизацию не содержит маркер состояния. В этом цикле возвращаются все события в представлении календаря.
Первый запрос задает следующие параметры:
- значения даты и времени для параметров startDateTime и endDateTime;
- необязательный заголовок запросаodata.maxpagesize, возвращающий 2 события одновременно.
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
Пример исходного ответа
Ответ включает два события и заголовок ответа @odata.nextLink
с маркером skipToken
.
URL-адрес @odata.nextLink
указывает, что получены не все события в представлении календаря.
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. Пример второго запроса
Второй запрос указывает URL-адрес @odata.nextLink
, полученный из предыдущего ответа. Обратите внимание, что в нем больше не требуется указывать те же параметры startDateTime и endDateTime, что и в исходном запросе, так как маркер skipToken
в URL-адресе @odata.nextLink
кодирует и включает их.
GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmcCM996atia_s HTTP/1.1
Prefer: odata.maxpagesize=2
Пример второго ответа
Второй ответ содержит следующие 2 события в представлении календаря и еще одну ссылку @odata.nextLink
, указывающую, что получены не все события в представлении календаря.
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. Пример третьего запроса
Третий запрос продолжает использовать маркер @odata.nextLink
, полученный из последнего запроса на синхронизацию.
GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmci39OQxqJrxK4 HTTP/1.1
Prefer: odata.maxpagesize=2
Пример третьего и последнего ответа
Третий ответ содержат последнее оставшееся событие из представления календаря и URL-адрес @odata.deltaLink
, указывающий, что синхронизация для этого представления календаря завершена. Сохраните URL-адрес @odata.deltaLink
и используйте его в следующем цикле синхронизации этого представления календаря.
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="
}
]
}
Следующий цикл: пример первого запроса
С помощью ссылки @odata.deltaLink
из последнего цикла прошлого запроса вы сможете получить только те события, которые изменились (путем добавления, удаления или обновления) в этом представлении календаря с момента последней синхронизации.
При условии, что вы не хотите менять максимальный размер страницы ответа, первый запрос следующего цикла будет выглядеть следующим образом:
GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcMDNGg0J1E HTTP/1.1
Prefer: odata.maxpagesize=2
Следующий цикл: пример первого ответа
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="
}
]
}