Тип ресурса subscription
Пространство имен: microsoft.graph
Важно!
API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Предостережение
Существующие приложения, использующие эту функцию с baseTask или baseTaskList , должны быть обновлены, так как набор API задач, основанный на этих ресурсах, устарел с 31 мая 2022 г. Этот набор API прекратит возвращать данные 31 августа 2022 г. Используйте набор API, основанный на todoTask.
Представляет подписку, которая позволяет клиентскому приложению получать уведомления об изменениях данных в Microsoft Graph.
Дополнительные сведения о подписках и уведомлениях об изменениях, включая ресурсы, поддерживающие уведомления об изменениях, см. в статье Настройка уведомлений об изменениях в данных ресурсов.
Методы
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| Список | subscription | Вывод списка активных подписок. |
| Создание | subscription | Подпишитесь на приложение-прослушиватель для получения уведомлений об изменениях при изменении данных Microsoft Graph. |
| Получение | subscription | Чтение свойств и связей объекта подписки. |
| Обновление | subscription | Продлить подписку, обновив срок ее действия. |
| удаление; | Нет | Удаление объекта подписки. |
| Повторная авторизация | Нет | Повторная авторизация подписки при получении запроса reauthorizationRequired . |
Свойства
| Свойство | Тип | Описание |
|---|---|---|
| applicationId | String | Необязательный параметр. Идентификатор приложения, использованного для создания подписки. Только для чтения. |
| changeType | Строка | Обязательный. Указывает тип изменения в подписанном ресурсе, который создает уведомление об изменении. Поддерживаемые значения: created, updated, deleted. Вы можете объединить несколько значений, указав их в списке с разделителями-запятыми. Примечание. updated. updated и deleted. Используйте для updated получения уведомлений о создании, обновлении или обратимом удалении пользователя или группы. Используйте deleted для получения уведомлений при окончательном удалении пользователя или группы. |
| clientState | String | Необязательный параметр. Задает значение свойства clientState , отправляемого службой в каждом уведомлении об изменении. Максимальная длина: 255 символов. Клиент может проверка, что уведомление об изменении поступило от службы, сравнив значение свойства clientState, отправленного с подпиской, со значением свойства clientState, полученного при каждом уведомлении об изменении. |
| creatorId | String | Необязательный параметр. Идентификатор пользователя или субъекта-службы, которые создали подписку. Если приложение использовало делегированные разрешения для создания подписки, это поле содержит идентификатор пользователя, вошедшего в систему, от имени вызываемого приложением. Если приложение использовало разрешения приложения, это поле содержит идентификатор субъекта-службы, соответствующего приложению. Только для чтения. |
| encryptionCertificate | Строка | Необязательный параметр. Представление в кодировке Base64 сертификата с открытым ключом, используемое для шифрования данных ресурса в уведомлениях об изменениях. Необязательный, но необходимый при includeResourceData равном true. |
| encryptionCertificateId | String | Необязательный параметр. Предоставляемый приложением настраиваемый идентификатор, помогающий определить сертификат, необходимый для расшифровки данных ресурса. Требуется, если параметр includeResourceData имеет значение true. |
| expirationDateTime | DateTimeOffset | Обязательное. Указывает дату и время истечения срока действия подписки на веб-перехватчик. Используется время в формате UTC, и оно может представлять собой время с момента создания подписки, которое зависит от ресурса, на который оформлена подписка. Максимальный поддерживаемый период времени подписки см. в разделе Время существования подписки. |
| id | String | Необязательный параметр. Уникальный идентификатор для подписки. Только для чтения. |
| includeResourceData | Boolean | Необязательное свойство. Если присвоено значение true, уведомления об изменениях включают данные ресурса (например, содержимое сообщения чата). |
| latestSupportedTlsVersion | Строка | Необязательный параметр. Указывает последнюю версию протокола TLS, поддерживаемую конечной точкой уведомлений, указанной с помощью свойства notificationUrl. Допустимые значения: v1_0, v1_1, v1_2, v1_3.
Для подписчиков, конечная точка уведомлений которых поддерживает версию ниже рекомендуемой в настоящее время версии (TLS 1.2), указание этого свойства набором временная шкала позволяет им временно использовать устаревшую версию TLS до завершения обновления до TLS 1.2. Если такие подписчики не настроят это свойство согласно соответствующим срокам, действия с подпиской будут завершаться сбоем. Для подписчиков, конечная точка уведомлений которых уже поддерживает TLS 1.2, установка этого свойства является необязательной. В таких случаях Microsoft Graph по умолчанию присваивает свойству значение v1_2. |
| lifecycleNotificationUrl | String | Требуется для ресурсов Teams, expirationDateTime если значение превышает 1 час; в противном случае необязательно. URL-адрес конечной точки, которая получает уведомления о жизненном цикле, включая subscriptionRemovedуведомления , reauthorizationRequiredи missed . Этот URL-адрес должен использовать протокол HTTPS. Дополнительные сведения см. в статье Уменьшение количества отсутствующих подписок и уведомлений об изменениях. |
| notificationContentType | Строка | Необязательный параметр. Желаемый тип контента для уведомлений об изменении Microsoft Graph для поддерживаемых типов ресурсов. Тип контента по умолчанию – application/json. |
| notificationQueryOptions | Строка | Необязательный параметр. Параметры запроса OData для указания значения целевого ресурса. Клиенты получают уведомления, когда ресурс достигает состояния, соответствующего указанным здесь параметрам запроса. Используя это новое свойство в полезных данных создания подписки вместе со всеми существующими свойствами, веб-перехватчики доставляют уведомления всякий раз, когда ресурс достигает требуемого состояния, указанного в свойстве notificationQueryOptions . Например, по окончании печати или когда свойство ресурса печати isFetchable приобретает значение true и т.п. Поддерживается только для универсальной службы печати. Дополнительные сведения см. в статье Подписка на уведомления об изменениях из API облачной печати с помощью Microsoft Graph. |
| notificationUrl | Строка | Обязательный. URL-адрес конечной точки, получающей уведомления об изменениях. Этот URL-адрес должен использовать протокол HTTPS. Любой параметр строки запроса, включенный в свойство notificationUrl, включается в HTTP-запрос POST, когда Microsoft Graph отправляет уведомления об изменениях. |
| notificationUrlAppId | String | Необязательный параметр. Идентификатор приложения, который служба подписки может использовать для создания маркера проверки. Значение позволяет клиенту проверить подлинность полученного уведомления. |
| resource | Строка | Обязательный. Указывает ресурс, отслеживаемый на наличие изменений. Не включайте базовый URL-адрес (https://graph.microsoft.com/beta/). См. возможные значения пути к ресурсу для всех поддерживаемых ресурсов. |
Время существования подписки
Время существования подписок ограничено. Приложения должны продлевать свои подписки до истечения срока действия; В противном случае необходимо создать новую подписку. Кроме того, приложение в любое время может отменить подписку, чтобы больше не получать уведомления об изменениях.
В следующей таблице показаны максимальные сроки действия подписок на ресурс в Microsoft Graph.
| Ресурс | Максимальный срок действия |
|---|---|
| Оповещение безопасности | 43 200 минут (до 30 дней) |
| Утверждения Teams | 43 200 минут (до 30 дней) |
| callRecord в Teams | 4 230 минут (до трех дней) |
| Вызовы TeamsRecording | 4320 минут (три дня) |
| Вызов TeamsTranscript | 4320 минут (три дня) |
| Канал Teams | 4320 минут (три дня) |
| Чат Teams | 4320 минут (три дня) |
| chatMessage Teams | 4320 минут (три дня) |
| conversationMember в Teams | 4320 минут (три дня) |
| onlineMeeting в Teams | 4320 минут (три дня) |
| Команда Teams | 4320 минут (три дня) |
| Teams teamsAppInstallation | 4 320 минут (3 дня) |
| Предложение Смены TeamsShiftRequest | 360 минут (6 часов) |
| Teams Shifts openShiftChangeRequest | 360 минут (6 часов) |
| Смена "Смены" в Teams | 360 минут (6 часов) |
| Teams Shifts swapShiftsChangeRequest | 360 минут (6 часов) |
| Время смен TeamsOffRequest | 360 минут (6 часов) |
| Групповая беседа | 4 230 минут (до трех дней) |
| driveItem OneDrive | 42 300 минут (до 30 дней) |
| Список SharePoint | 42 300 минут (до 30 дней) |
| Сообщение, событие, контакт Outlook | 10 080 минут (до семи дней) |
| Пользователь, группа, другие ресурсы каталога | 41 760 минут (до 29 дней) |
| onlineMeeting | 4 230 минут (до трех дней) |
| presence | 60 минут (1 час) |
| printer печати | 4 230 минут (до трех дней) |
| printTaskDefinition печати | 4 230 минут (до трех дней) |
| todoTask | 4 230 минут (до трех дней) Веб-перехватчики для этого ресурса доступны только в глобальной конечной точке, а не в национальных облаках. |
| baseTask (не рекомендуется) | 4 230 минут (до трех дней) |
Примечание. Для существующих приложений и новых приложений не должно превышаться допустимое значение. В будущем любые запросы на создание или продление подписки со значением, превышающим максимальное, будут завершаться ошибкой.
Задержка
В следующей таблице указаны ожидаемые задержки между возникновением события в службе и доставкой уведомления об изменении.
| Ресурс | Средняя задержка | Максимальная задержка |
|---|---|---|
| оповещение1 | Менее 3 минут | 5 минут |
| Утверждения | Менее 10 секунд | 40 секунд |
| calendar | Менее 1 минуты | 3 минуты |
| callRecord | Менее 15 минут | 60 минут |
| callRecording | Менее 10 секунд | 60 минут |
| callTranscript | Менее 10 секунд | 60 минут |
| channel | Менее 10 секунд | 60 минут |
| chat | Менее 10 секунд | 60 минут |
| chatMessage | Менее 10 секунд | 1 минута |
| contact | Менее 1 минуты | 3 минуты |
| conversation | Неизвестно | Неизвестно |
| conversationMember | Менее 10 секунд | 60 минут |
| driveItem | Менее 1 минуты | 5 минут |
| event | Неизвестно | Неизвестно |
| group | Неизвестно | Неизвестно |
| list | Менее 1 минуты | 5 минут |
| message | Менее 1 минуты | 3 минуты |
| offerShiftRequest | Менее 1 минуты | 60 минут |
| onlineMeeting | Менее 10 секунд | 1 минута |
| openShiftChangeRequest | Менее 1 минуты | 60 минут |
| presence | Менее 10 секунд | 1 минута |
| printer | Менее 1 минуты | 5 минут |
| printTaskDefinition | Менее 1 минуты | 5 минут |
| shift | Менее 1 минуты | 60 минут |
| swapShiftsChangeRequest | Менее 1 минуты | 60 минут |
| team | Менее 10 секунд | 60 минут |
| teamsAppInstallation | Менее 10 секунд | 60 минут |
| timeOffRequest | Менее 1 минуты | 60 минут |
| todoTask | Менее 2 минут | 15 минут |
| user | Неизвестно | Неизвестно |
1 Задержка, предоставляемая для ресурса оповещений , применяется только после создания оповещения. Он не включает время, необходимое правилу для создания оповещений на основе данных.
Связи
Отсутствуют.
Представление JSON
В следующем представлении JSON показан тип ресурса.
{
"@odata.type": "#microsoft.graph.subscription",
"applicationId": "String",
"changeType": "String",
"clientState": "String",
"creatorId": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"expirationDateTime": "String (timestamp)",
"id": "String (identifier)",
"includeResourceData": "Boolean",
"latestSupportedTlsVersion": "String",
"lifecycleNotificationUrl": "String",
"notificationContentType": "String",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String"
}