Подписка на уведомления об изменениях из API облачной печати с использованием Microsoft Graph

  • Статья

Универсальная печать помогает пользователям переносить инфраструктуру печати в облако и является частью надежной экосистемы партнерских решений, предлагающих расширенные возможности печати. Эти решения могут быть еще эффективнее, если использовать API облачной печати в Microsoft Graph для интеграции с универсальной печатью.

Многие партнерские решения должны обрабатывать задания печати в режиме реального времени при их отправке с устройств пользователей на принтеры. Это означает, что они должны получать уведомления, когда задания печати доступны для обработки. Универсальная печать предоставляет обработчики для уведомления решений поставщиков печати, когда задания перемещаются в облаке, а также API, позволяющие управлять принтерами и заданиями печати.

В этой статье объясняется, как подписаться на уведомления о различных событиях заданий печати.

Начало работы с уведомлениями об изменениях

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

Уведомления и подписки

В настоящее время универсальная печать поддерживает уведомления для двух сценариев, связанных с заданиями печати.

  • Инициирована задача PrintTask (JobStarted): приложение может подписаться на получение уведомлений при инициировании printTask(hook). Подробнее о том, как запускать задачу, см. в Включение печати по запросу. В настоящее задачу printTask можно инициировать только для события JobStarted. Событие JobStarted возникает, когда создано задание печати, загружены его полезные данные и запущена обработка задания.

  • JobFetchable: после запуска задания сторонние приложения печати или универсальная печать могут выполнять некоторую обработку (например, преобразовать полезные данные XPS в формат PDF для принтера PDF). После завершения обработки и готовности полезных данных к загрузке принтером возникает событие JobFetchable для соответствующего задания печати.

Примечание.

Чтобы прослушивать уведомления об изменениях для события JobFetchable, не требуется ресурс printTaskDefinition.

Приложение должно обрабатывать повторяющиеся уведомления.

Создание приложения для прослушивания уведомлений

Сведения о том, как прослушивать уведомления Microsoft Graph, см. в статье Настройка уведомлений об изменениях в пользовательских данных — примеры кода.

Области разрешений

Чтобы подписаться на уведомления о заданиях печати, приложения должны иметь следующие области разрешений, утвержденные в клиенте Microsoft Entra клиента:

Приложения должны создавать и использовать маркер безопасности Microsoft Entra в заголовке запроса microsoft API Graph. Маркер безопасности содержит утверждения согласно областям, утвержденным для клиента Microsoft Entra клиента администратором.

Создание подписки: инициировано событие printTask (JobStarted)

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

Перед созданием уведомления для инициированного события printTask, убедитесь, что приложение создало следующие элементы:

  • PrintTaskDefinition для клиента Microsoft Entra клиента. Одно определение задачи можно связать с одним или несколькими принтерами в пределах одного Microsoft Entra клиента.

  • printTaskTrigger для всех очередей принтеров, для которых партнер хочет получать уведомление при запуске нового задания печати. printTaskTrigger требуется связать с printTaskDefinition.

Примечание.

Один принтер можно связать только с одним объектом printTaskTrigger, а один объект printTaskTrigger можно связать только с одним элементом printTaskDefinition. Однако один элемент printTaskDefinition можно связать с несколькими объектами printTaskTriggers.

С помощью printTaskDefinition, существующего для клиента Microsoft Entra клиента, приложение может создать подписку для события, активированного printTask (JobStarted), с помощью printTaskDefinition. При создании подписки:

  • Полю resource требуется присвоить значение print/taskDefinitions/{printTaskDefinition ID}/tasks.
  • Полю changeType требуется присвоить значение created.
  • Поле expirationDateTime не должное превышать максимальный срок действия.

Дополнительные сведения см. в разделе Свойства типа ресурса subscription.

Запрос

Ниже показан пример запроса.

POST https://graph.microsoft.com/v1.0/subscriptions 
Content-Type: application/json
{ 
    "changeType":"created", 
    "resource":"print/taskDefinitions/{printTaskDefinition ID}/tasks", 
    "clientState":"secret", 
    "notificationUrl":"{URL for receiving the event – e.g. https://webhookappexample.azurewebsites.net/api/notifications}", 
    "expirationDateTime":"2020-01-30T22:42:09Z" 
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity", 
    "id": "{Subscription ID}", 
    "resource": "print/taskDefinitions/{printTaskDefinition ID}/tasks", 
    "applicationId": "{application ID}", 
    "changeType": "created", 
    "clientState": "secret", 
    "notificationUrl": "{URL for receiving the event – e.g. https://webhookappexample.azurewebsites.net/api/notifications}", 
    "notificationQueryOptions": null, 
    "lifecycleNotificationUrl": null, 
    "expirationDateTime": "2020-12-30T22:42:09Z", 
    "creatorId": "{Creator ID}", 
    "includeResourceData": null, 
    "latestSupportedTlsVersion": "v1_2", 
    "encryptionCertificate": null, 
    "encryptionCertificateId": null 
}

Создание подписки: событие JobFetchable

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

Примечание.

Задания печати нельзя изменить после их перехода в состояние JobFetchable. Уведомление JobFetchable требуется создавать для каждой очереди принтера. При создании подписки:

  • Полю resource требуется присвоить значение "print/printers/{printer id}/jobs".
  • Полю changeType требуется присвоить значение updated.
  • Полю notificationQueryOptions требуется присвоить значение $filter = isFetchable eq true.
  • Поле expirationDateTime не должное превышать максимальный срок действия.

Дополнительные сведения см. в разделе Свойства типа ресурса subscription.

Запрос

Ниже показан пример запроса.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
    "changeType":"updated",
    "resource":"print/printers/{printer id}/jobs",
    "notificationQueryOptions": "$filter = isFetchable eq true", 
    "notificationUrl":"{URL for receiving the event – e.g. https://webhookappexample.azurewebsites.net/api/notifications}",
    "expirationDateTime":"2020-12-30T22:42:09Z",
    "clientState":"mysecret"
}

Отклик

Ниже показан пример отклика.

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity", 
    "id": "{Subscription ID}", 
    "resource": "print/printers/{printer ID}/jobs", 
    "applicationId": "{Application ID}", 
    "changeType": "updated", 
    "clientState": "mysecret", 
    "notificationUrl": "{URL for receiving the event – e.g. https://webhookappexample.azurewebsites.net/api/notifications}", 
    "notificationQueryOptions": "$filter = isFetchable eq true", 
    "lifecycleNotificationUrl": null, 
    "expirationDateTime": "2020-12-30T22:42:09Z", 
    "creatorId": "{Creator ID}", 
    "includeResourceData": null, 
    "latestSupportedTlsVersion": "v1_2", 
    "encryptionCertificate": null, 
    "encryptionCertificateId": null
}

Возобновить подписку на уведомления

В Microsoft Graph срок действия ограничен. Дополнительные сведения см. в разделе о максимальном сроке действия. Чтобы продолжать получать уведомления, подписку требуется периодически обновлять с помощью API обновления подписки.

Получение или удаление подписок на уведомления

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

Вопросы и ответы

Как Microsoft Graph проверяет URL-адреса уведомлений?

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

Каковы предполагаемые действия приложений после получения уведомления об изменении?

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

Как проверить подлинность уведомлений?

Подлинность уведомлений можно проверять, используя значения clientState, как описано в разделе Обработка уведомления об изменении, или маркеры проверки в уведомлении об изменении.

Как получить список активных подписок?

Сведения о том, как получить список подписок на веб-перехватчики, см. в разделе Перечисление подписок.

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