event: delta

Статья
08/23/2023

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

Важно!

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

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

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

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

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

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


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users calendar events delta get --user-id {user-id} --start-date-time "2020-06-12T00:00:00Z"

Важно!

Пакеты SDK для Microsoft Graph по умолчанию используют версию API версии 1.0 и поддерживают не все типы, свойства и API, доступные в бета-версии. Дополнительные сведения о доступе к бета-API с помощью SDK см. в статье Использование пакетов Microsoft Graph SDK с бета-API.

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z')
	.version('beta')
	.get();

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

Если запрос выполнен успешно, ответ включает маркер состояния, который представляет собой 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


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta users calendars calendar-view delta get --user-id {user-id} --calendar-id {calendar-id} --start-date-time "2020-06-01T00:00:00Z" --end-date-time "2020-06-10T00:00:00Z"

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z')
	.version('beta')
	.get();

Важно!

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

Ниже показан отклик с маркером состояния 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"
                }
            }
        }
    ]
}

event: delta

Разрешения

HTTP-запрос

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

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

Функция Delta в календареПросмотр в календаре группы

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

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

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

Отклик

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

Функция Delta в calendarView

Примеры

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

Запрос

Отклик

Пример 2. Функция Delta в calendarView

Запрос

Отклик

Обратная связь

Обратная связь

Дополнительные ресурсы

event: delta

Разрешения

HTTP-запрос

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

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

Функция Delta в календареПросмотр в календаре группы

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

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

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

Отклик

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

Функция Delta в calendarView

Примеры

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

Запрос

Отклик

Пример 2. Функция Delta в calendarView

Запрос

Отклик

Связанные материалы

Обратная связь

Обратная связь

Дополнительные ресурсы