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


event: delta

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

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

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

Как правило, синхронизация событий в календаре или calendarView в локальном хранилище влечет за собой цикл из нескольких разностных вызовов функций. Исходный вызов связан с полной синхронизацией, а каждый последующий вызов delta из того же цикла — с дополнительными изменениями (добавлениями, удалениями или обновлениями). Это позволяет поддерживать и синхронизировать локальное хранилище событий в указанном календаре без необходимости каждый раз получать все события этого календаря с сервера.

В следующей таблице перечислены различия между функцией delta для событий и функцией delta в calendarView в календаре.

Функция Delta для событий Функция Delta в calendarView
Возвращает добавочные изменения всех событий в календаре, не ограниченных диапазоном дат начала и окончания. Кроме того, можно получать добавочные изменения событий в календаре, ограниченном временем начала, начиная с этой даты и времени. Возвращает добавочные изменения событий в начальной и конечной дате и времени элемента calendarView.
Возвращает только ограниченный набор свойств события по соображениям производительности. Клиент для последующего использования GET /events/{id} для развертывания любых событий. Расширение на стороне сервера возвращает полный набор свойств события .
Ответ включает отдельные экземпляры и повторяющийся хозяин рядов. Ответ включает отдельные экземпляры, а также вхождения и исключения повторяющихся рядов.
Применяется к событиям в пользовательских календарях, но не к групповым календарям. Применяется к событиям в календарях пользователей и групп.
В настоящее время доступно только в бета-версии. Доступно в версии 1.0 и бета-версиях.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet

Разрешения

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

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) Calendars.ReadBasic Calendars.Read, Calendars.ReadWrite
Делегированные (личная учетная запись Майкрософт) Calendars.ReadBasic Calendars.Read, Calendars.ReadWrite
Для приложений Calendars.Read Calendars.ReadBasic, Calendars.ReadWrite

HTTP-запрос

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

URL-адрес запроса, возвращаемый в @odata.nextLink или @odata.deltaLink успешного ответа, включает маркер состояния. Для любого последующего вызова функции delta используйте URL-адрес запроса в @odata.nextLink или @odata.deltaLink перед ним.

Функция Delta для событий в пользовательском календаре (предварительная версия)

Примените функцию 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}
    

Функция Delta в calendarView в пользовательском календаре

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

Параметр запроса Тип Описание
startDateTime String Дата и время начала диапазона, представленные в формате ISO 8601. Например, "2019-11-08T19:00:00-08:00".
Часовой пояс указывается в части смещения часового пояса значения параметра и не влияет на Prefer: outlook.timezone заголовок, если он присутствует. Если в значении не указано смещение часового пояса, оно интерпретируется в формате UTC.
Необязательный параметр для разностных событий в календаре.
Требуется для delta в calendarView.
endDateTime String Дата и время окончания диапазона, представленные в формате ISO 8601. Например, "2019-11-08T20:00:00-08:00".
Часовой пояс указывается в части смещения часового пояса значения параметра и не влияет на Prefer: outlook.timezone заголовок, если он присутствует. Если в значении не указано смещение часового пояса, оно интерпретируется в формате UTC.
Не поддерживаетсяразностными событиями в календаре.
Требуется для delta в calendarView.
$deltatoken string Маркер состояния, возвращенный в @odata.deltaLink URL-адресе предыдущего вызова разностной функции для того же представления календаря, указывающий на завершение этого цикла отслеживания изменений. Сохраните и примените весь @odata.deltaLink URL-адрес, включая этот маркер, в первом запросе следующего цикла отслеживания изменений для этого представления календаря.
$skiptoken string Этот маркер состояния возвращается в URL-адресе @odata.nextLink при предыдущем вызове функции delta и указывает на то, что в представлении календаря остаются не отслеженные изменения.

Параметры запросов OData

  • Ожидайте вызова функции delta в calendarView, чтобы вернуть те же свойства, которые обычно получают с помощью запроса GET /calendarView. Вы не можете использовать $select для получения только подмножества этих свойств.

  • Функция delta не поддерживает следующие параметры запроса для событий в пользовательском календаре или событий в calendarView: $expand, $filter,$orderby$search и $select.

Заголовки запросов

Имя Тип Описание
Authorization string Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type string application/json. Обязательный параметр.
Prefer string odata.maxpagesize={x}. Необязательный параметр.
Prefer string outlook.timezone={Строка часового пояса}. Необязательный, предполагается в формате UTC, если отсутствует.

Отклик

Функция Delta для событий (предварительная версия)

В случае успешного выполнения этот метод возвращает код отклика 200 OK и коллекцию событий в тексте отклика. Каждое событие в ответе содержит только свойства id, type, start и end по соображениям производительности. Затем используйте GET /events/{id} для развертывания всех событий из ответа.

Функция Delta в calendarView

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

Ожидается получение всех свойств, которые вы обычно получаете из GET /calendarView запроса.

В цикле вызовов функции delta, ограниченном диапазоном дат calendarView,, можно найти вызов delta, возвращающий два типа событий в @removed с причиной deleted:

  • События, которые находятся в диапазоне дат и удалены с момента предыдущего вызова delta.
  • События, которые находятся за пределами диапазона дат и добавлены, удалены или обновлены с момента предыдущего вызова delta.

Отфильтруйте события в @removed для диапазона дат, которого требует сценарий.

Примеры

Пример 1. Функция Delta для событий в календаре (предварительная версия)

Запрос

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

Запрос использует заголовок, Prefer: odata.maxpagesize чтобы ограничить максимальное количество событий в каждом ответе до 1. Продолжайте вызывать функцию delta с помощью запроса, возвращенного в , @odata.nextLink пока не получите в ответе @odata.deltaLink .

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

Prefer: odata.maxpagesize=1

Отклик

Если запрос выполнен успешно, ответ включает маркер состояния, который представляет собой skipToken (в заголовке ответа @odata.nextLink ) или deltaToken (в заголовке ответа @odata.deltaLink ). Соответственно, они указывают, следует ли продолжить цикл или вы завершили получение всех изменений для этого раунда.

Ниже показан отклик с маркером состояния skipToken в заголовке отклика @odata.nextLink.

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. Функция Delta в calendarView

Запрос

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

Запрос использует заголовок, Prefer: odata.maxpagesize чтобы ограничить максимальное количество событий в каждом ответе до 2. Продолжайте вызывать функцию delta с помощью возвращенного запроса, @odata.nextLink пока не получите все события в этом представлении календаря и в @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

Отклик

Если запрос выполнен успешно, ответ включает маркер состояния, который представляет собой skipToken (в заголовке ответа @odata.nextLink ) или deltaToken (в заголовке ответа @odata.deltaLink ). Соответственно, они указывают, следует ли продолжить цикл или вы завершили получение всех изменений для этого раунда.

Ниже показан отклик с маркером состояния skipToken в заголовке отклика @odata.nextLink.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

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"
                }
            }
        }
    ]
}