Поделиться через


Получение добавочных изменений для событий в представлении календаря

Используя дельта-запрос, вы можете получать новые, обновленные или удаленные события в указанном календаре или в определенной коллекции событий (как представление календаря) в календаре. В этой статье описывается последнее: получение таких добавочных изменений к событиям в представлении календаря.

Примечание.

Возможность для первого — получение добавочных изменений в событиях в календаре, не привязанном к фиксированному диапазону дат начала и окончания, в настоящее время доступна только в бета-версии. Дополнительные сведения см. в статье функция 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. Пример исходного запроса

В этом примере указанное представление календаря для календаря, используемого по умолчанию пользователем, который вошел в систему, синхронизируется впервые, поэтому исходный запрос на синхронизацию не содержит маркер состояния. В этом цикле возвращаются все события в представлении календаря.

Первый запрос задает следующие параметры:

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.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.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.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.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.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.com"
                }
            },
            "id":"AAMkADj1HvAAA="
        }
    ]
}