Тип ресурса subscription

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

Представляет подписку, которая позволяет клиентскому приложению получать уведомления об изменениях данных в Microsoft Graph.

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

Методы

Метод Возвращаемый тип Описание
Перечисление подписок subscription Перечисление активных подписок.
Создание подписки subscription Создает подписку для приложения прослушивателя, позволяющую получать уведомления об изменениях данных в Microsoft Graph.
Получение подписки subscription Чтение свойств и связей объекта subscription.
Обновление подписки subscription Обновление подписки путем изменения ее срока действия.
Удаление подписки Нет Удаление объекта subscription.
Повторная авторизация Нет Повторная авторизация подписки при получении запроса reauthorizationRequired .

Свойства

Свойство Тип Описание
applicationId String Необязательный параметр. Идентификатор приложения, использованного для создания подписки. Только для чтения.
changeType Строка Обязательный. Указывает тип изменения в подписанном ресурсе, который создает уведомление об изменении. Поддерживаемые значения: created, updated, deleted. Вы можете объединить несколько значений, указав их в списке с разделителями-запятыми.

Примечание.
  • Уведомления об изменении корневого элемента диска и списка поддерживают только changeType updated.
  • Уведомления об изменении пользователей и групп поддерживают changeType 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",
      "applicationId": "String",
      "changeType": "String",
      "clientState": "String",
      "creatorId": "String",
      "encryptionCertificate": "String",
      "encryptionCertificateId": "String",
      "expirationDateTime": "String (timestamp)",
      "id": "String (identifier)",
      "includeResourceData": "Boolean",
      "latestSupportedTlsVersion": "String",
      "lifecycleNotificationUrl": "String",
      "notificationQueryOptions": "String",
      "notificationUrl": "String",
      "notificationUrlAppId": "String",
      "resource": "String"
    }