Тип ресурса subscription
Пространство имен: microsoft.graph
Подписка позволяет клиентскому приложению получать уведомления об изменениях данных в Microsoft Graph.
Дополнительные сведения о подписках и уведомлениях об изменениях, включая ресурсы, поддерживающие уведомления об изменениях, см. в статье Настройка уведомлений об изменениях в данных ресурсов.
Методы
| Метод | Возвращаемый тип | Описание |
|---|---|---|
| Создание подписки | subscription | Создает подписку для приложения прослушивателя, позволяющую получать уведомления об изменениях данных в Microsoft Graph. |
| Обновление подписки | subscription | Обновление подписки путем изменения ее срока действия. |
| Перечисление подписок | subscription | Перечисление активных подписок. |
| Получение подписки | subscription | Чтение свойств и связей объекта subscription. |
| Удаление подписки | Нет | Удаление объекта subscription. |
| повторная авторизация | Нет | Повторная авторизация подписки при получении запроса reauthorizationRequired . |
Свойства
| Свойство | Тип | Описание |
|---|---|---|
| applicationId | String | Необязательный параметр. Идентификатор приложения, использованного для создания подписки. Только для чтения. |
| changeType | Строка | Обязательный. Указывает тип изменения в ресурсе, на который оформлена подписка и при возникновении которого будет создано уведомление об изменении. Поддерживаемые значения: created, updated, deleted. Вы можете объединить несколько значений, указав их в списке с разделителями-запятыми. Примечание. updated. updated и deleted. Используйте updated для получения уведомлений о создании, обновлении или обратимом удалении пользователя или группы. Используйте deleted для получения уведомлений при окончательном удалении пользователя или группы. |
| clientState | String | Необязательно. Указывает значение свойства clientState, отправляемого службой в каждом уведомлении об изменении. Максимальная длина — 128 символов. Клиент может проверить, пришло ли уведомление об изменении от службы, сравнив значение свойства clientState, отправленного с подпиской, со значением свойства clientState, получаемого с каждым уведомлением об изменении. |
| creatorId | String | Необязательный параметр. Идентификатор пользователя или субъекта-службы, которые создали подписку. Если в приложении использовались делегированные разрешения для создания подписки, это поле содержит идентификатор вошедшего пользователя, от имени которого вызвано приложение. Если в приложении использовались разрешения для приложений, это поле содержит идентификатор субъекта-службы, соответствующей приложению. Только для чтения. |
| encryptionCertificate | Строка | Необязательный параметр. Представление в кодировке Base64 сертификата с открытым ключом, используемое для шифрования данных ресурса в уведомлениях об изменениях. Необязательный, но необходимый при includeResourceData равном true. |
| encryptionCertificateId | String | Необязательный параметр. Предоставляемый приложением настраиваемый идентификатор, помогающий определить сертификат, необходимый для расшифровки данных ресурса. |
| 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. Дополнительные сведения см. в статье Уменьшение количества отсутствующих подписок и уведомлений об изменениях. |
| 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/v1.0/). См. возможные значения пути к ресурсу для всех поддерживаемых ресурсов. |
Время существования подписки
Время существования подписок ограничено. Приложения должны продлевать свои подписки до истечения срока действия; В противном случае необходимо создать новую подписку. Кроме того, приложение в любое время может отменить подписку, чтобы больше не получать уведомления об изменениях.
В следующей таблице показаны максимальные сроки действия подписок на ресурс в Microsoft Graph.
| Ресурс | Максимальный срок действия |
|---|---|
| Оповещение безопасности | 43 200 минут (до 30 дней) |
| callRecord в Teams | 4 230 минут (до 3 дней) |
| Вызовы TeamsRecording | 4 320 минут (3 дня) |
| Вызов TeamsTranscript | 4 320 минут (3 дня) |
| Канал Teams | 4 320 минут (3 дня) |
| Чат Teams | 4 320 минут (3 дня) |
| chatMessage Teams | 4 320 минут (3 дня) |
| conversationMember в Teams | 4 320 минут (3 дня) |
| onlineMeeting в Teams | 4 320 минут (3 дня) |
| Команда Teams | 4 320 минут (3 дня) |
| Групповая беседа | 4 230 минут (до 3 дней) |
| driveItem OneDrive | 42 300 минут (до 30 дней) |
| Список SharePoint | 42 300 минут (до 30 дней) |
| Сообщение, событие, контакт Outlook | 4 230 минут (до 3 дней) |
| Пользователь, группа, другие ресурсы каталога | 41 760 минут (до 29 дней) |
| onlineMeeting | 4 230 минут (до 3 дней) |
| presence | 60 минут (1 час) |
| printer печати | 4 230 минут (до 3 дней) |
| printTaskDefinition печати | 4 230 минут (до 3 дней) |
| todoTask | 4 230 минут (до 3 дней) Веб-перехватчики для этого ресурса доступны только в глобальной конечной точке, а не в национальных облаках. |
| baseTask (не рекомендуется) | 4 230 минут (до 3 дней) |
Примечание. Для существующих приложений и новых приложений не должно превышаться допустимое значение. В будущем любые запросы на создание или продление подписки со значением, превышающим максимальное, будут завершаться ошибкой.
Задержка
В следующей таблице указаны ожидаемые задержки между возникновением события в службе и доставкой уведомления об изменении.
| Ресурс | Средняя задержка | Максимальная задержка |
|---|---|---|
| оповещение1 | Менее 3 минут | 5 минут |
| 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 | Менее 2 минут | 15 минут |
| list | Менее 1 минуты | 5 минут |
| message | Менее 1 минуты | 3 минуты |
| onlineMeeting | Менее 10 секунд | 1 минута |
| presence | Менее 10 секунд | 1 минута |
| printer | Менее 1 минуты | 5 минут |
| printTaskDefinition | Менее 1 минуты | 5 минут |
| team | Менее 10 секунд | 60 минут |
| todoTask | Менее 2 минут | 15 минут |
| user | Менее 2 минут | 15 минут |
1 Задержка, предоставляемая для ресурса оповещений , применяется только после создания оповещения. Он не включает время, необходимое правилу для создания оповещений на основе данных.
Связи
Нет
Представление JSON
Ниже представлено описание ресурса в формате JSON.
{
"@odata.type": "#microsoft.graph.subscription",
"id": "String (identifier)",
"resource": "String",
"changeType": "String",
"clientState": "String",
"notificationUrl": "String",
"expirationDateTime": "String (timestamp)",
"applicationId": "String",
"creatorId": "String",
"includeResourceData": "Boolean",
"lifecycleNotificationUrl": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"latestSupportedTlsVersion": "String",
"notificationQueryOptions": "String",
"notificationUrlAppId": "String"
}