Тип ресурса 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 дней) |
callRecord в Teams | 4 230 минут (до трех дней) |
Вызовы TeamsRecording | 4320 минут (три дня) |
Вызов TeamsTranscript | 4320 минут (три дня) |
Канал Teams | 4320 минут (три дня) |
Чат Teams | 4320 минут (три дня) |
chatMessage Teams | 4320 минут (три дня) |
conversationMember в Teams | 4320 минут (три дня) |
onlineMeeting в Teams | 4320 минут (три дня) |
Команда Teams | 4320 минут (три дня) |
Предложение Смены 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 | 4 230 минут (до трех дней) |
Пользователь, группа, другие ресурсы каталога | 41 760 минут (до 29 дней) |
onlineMeeting | 4 230 минут (до трех дней) |
presence | 60 минут (1 час) |
printer печати | 4 230 минут (до трех дней) |
printTaskDefinition печати | 4 230 минут (до трех дней) |
todoTask | 4 230 минут (до трех дней) Веб-перехватчики для этого ресурса доступны только в глобальной конечной точке, а не в национальных облаках. |
baseTask (не рекомендуется) | 4 230 минут (до трех дней) |
Примечание. Для существующих приложений и новых приложений не должно превышаться допустимое значение. В будущем любые запросы на создание или продление подписки со значением, превышающим максимальное, будут завершаться ошибкой.
Задержка
В следующей таблице указаны ожидаемые задержки между возникновением события в службе и доставкой уведомления об изменении.
Ресурс | Средняя задержка | Максимальная задержка |
---|---|---|
оповещение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 | Неизвестно | Неизвестно |
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 минут |
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"
}
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по