订阅云打印 API 中的更改通知 - Microsoft Graph

项目
11/07/2024

通用打印可帮助客户将其打印基础结构移动到云，是提供高级打印功能的合作伙伴解决方案强大生产力的一部分。当您使用 Microsoft Graph 中的云打印 API 与通用打印集成时，这些解决方案甚至会更加强大。

许多合作伙伴解决方案需要将打印作业从用户的设备发送到打印机时实时处理，这意味着当打印作业可进行处理时，需要收到通知。通用打印为在云中移动作业时通知打印供应商解决方案提供的连接，以及可管理打印机和打印作业的 API。

本文介绍如何订阅各种打印作业事件的通知。

更改通知入门

必须先在 Azure 中注册应用程序，并在客户Microsoft Entra租户中预配应用程序，然后才能通过 Microsoft Graph 利用更改通知。确保应用程序已启用所需的权限范围，如本文稍后所述。

通知和订阅

通用打印当前支持两种打印作业相关方案的通知：

PrintTask 被触发（作业启动）：应用程序可以在其 printTask（hook）触发时订阅以接收通知。有关如何触发任务的详细信息，请参阅启用拉式打印。目前，仅能为作业启动事件触发 printTask。成功创建打印作业、上传有效负载并开始作业处理后，将发生作业启动事件。
作业可保存：作业启动后，第三方打印应用程序或通用打印可能会执行某些处理（例如将 XPS 有效负载转换为 PDF，用于 PDF 打印机）。处理完成后，如果有效负载已准备好由打印机下载，则针对相应的打印作业将发生 JobFable 事件。

注意

为收听 JobFableable 事件更改通知， printTaskDefinition 更改通知。

应用程序应处理重复的通知。

创建可收听通知的应用程序

有关如何侦听 Microsoft Graph 通知的信息，请参阅设置用户数据更改通知 – 代码示例。

权限范围

若要订阅打印作业的通知，应用程序必须在客户的Microsoft Entra租户中批准以下权限范围：

对于 printTask 触发（作业启动）事件，"获取任务定义中列出的权限。
对于 JobFable 事件，"创建订阅" 中列出的。

应用程序必须在 Microsoft 图形 API 请求标头中生成并使用Microsoft Entra安全令牌。安全令牌包含根据管理员为其Microsoft Entra租户批准的作用域的声明。

创建订阅：printTask 触发（作业启动）事件

某些应用程序监视传入作业的打印队列，希望在队列中具有有效作业时收到通知。收到通知后，他们可以收集相关的作业元数据，甚至可以在打印作业中执行修改，包括中止作业或相应地修改作业属性后将作业从当前打印队列重定向到另一个队列。

在创建打印任务 -事件的通知之前，请确保应用程序创建了以下应用程序：

客户的Microsoft Entra租户的 printTaskDefinition。单个任务定义可以与同一Microsoft Entra租户中的一个或多个打印机相关联。
针对开始新打印作业时，合作伙伴希望接收其通知的每个打印机队列的 "PrintTaskTri你邮件"标签。 printTaskDefinition需要绑定到PrintTaskDefinition。

注意

一个打印机只能与一个 printTaskTriition 和一个 printTaskTriition 只能与一 printTaskDefinition。但是，一 printTaskDefinition 可以具有一 一个或多个 printTaskTriitions 与其关联。

借助客户的Microsoft Entra租户存在的 printTaskDefinition，应用程序可以使用 printTaskDefinition 为 (JobStarted) 事件触发的 printTask 创建订阅。创建订阅时：

resource 字段需要设置为 print/taskDefinitions/{printTaskDefinition ID}/tasks。
changeType 字段需要设置为 created。
" expirationDateTime "字段需要小于最大到期日期。

如需了解更多详情，请参阅 openTypeExtension 资源类型。

请求

以下示例显示了一个请求。

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 
}

创建订阅：作业可创建事件

一些云应用程序需要准备好后从通用打印中下载打印作业。由于在云中运行的这些应用程序不在客户的防火墙后面，因此可在下载打印作业时使用 Microsoft Graph 更改通知。

注意

打印作业进入作业可打印状态时不可修改。需要针对每个打印机队列创建可作业通知。创建订阅时：

" resource "字段需要设置为"print/printer/{printer id}/jobs"。
changeType 字段需要设置为 updated。
notificationQueryOptions 字段需要设置为 $filter = isFetchable eq true。
" expirationDateTime "字段需要小于最大到期日期。

如需了解更多详情，请参阅 openTypeExtension 资源类型。

请求

以下示例显示了一个请求。

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 更新定期续订。

获取或删除通知订阅

应用程序可获取订阅的详细信息，或者在需要时删除订阅。有关详细信息，请参阅 Microsoft Graph API 通过更改通知。

常见问题

Microsoft Graph 如何验证通知 URL？

Microsoft Graph 将验证创建订阅前订阅请求的 notificationurl 属性中提供的通知终结点。有关详细信息，请参阅终结点验证。

收到更改通知后，应用程序应执行哪些操作？

应用程序应处理和确认他们收到的每个更改通知。有关详细信息，请参阅更改通知。

如何验证通知的真实性？

可以使用 clientState 值验证通知的真实性，如处理更改通知或验证更改通知中的令牌中所述。

如何获取活动订阅列表？

若要详细了解如何检索 Web 网站订阅列表，请参阅订阅。

若要深入了解 Microsoft Graph 中的云打印 API，请参阅云打印 API 概述。
有关 Microsoft Graph 中的云打印 API 的建议或反馈，请访问通用打印技术社区。

通过

订阅使用 Microsoft Graph 更改云打印 API 的通知