订阅使用 Microsoft Graph 更改云打印 API 的通知Subscribe to change notifications from cloud printing APIs using Microsoft Graph

通用打印可帮助客户将其打印基础结构移动到云,是提供高级打印功能的合作伙伴解决方案强大生产力的一部分。Universal Print helps customers move their print infrastructure to the cloud, and is part of a robust ecosystem of partner solutions that offer advanced print functionality. 当您使用 Microsoft Graph 中的云打印 API 与通用打印集成时,这些解决方案甚至会更加强大。These solutions can become even more powerful when you use the cloud printing APIs in Microsoft Graph to integrate with Universal Print.

许多合作伙伴解决方案需要将打印作业从用户的设备发送到打印机时实时处理,这意味着当打印作业可进行处理时,需要收到通知。Many partner solutions need to process print jobs in real time as they're sent from users' devices to printers, which means they need to be notified when print jobs are available for processing. 通用打印为在云中移动作业时通知打印供应商解决方案提供的连接,以及可管理打印机和打印作业的 API。Universal Print provides hooks for print vendor solutions to be notified as jobs move through the cloud, and APIs that enable management of printers and print jobs.

本文介绍如何订阅各种打印作业事件的通知。This article describes how to subscribe to notifications for various print job events.

更改通知入门Get started with change notifications

必须先在 Azure 中注册应用程序, Azure Active Directory (Azure AD) 租户中预配应用程序,才能利用通过 Microsoft Graph 更改通知。Before you can take advantage of change notifications via Microsoft Graph, you must register your application in Azure and provision your application in the customers Azure Active Directory (Azure AD) tenant. 确保应用程序已启用所需的权限范围,如本文稍后所述。Make sure that the application has the required permission scopes enabled, as described later in this article.

通知和订阅Notifications and subscriptions

通用打印当前支持两种打印作业相关方案的通知:Universal Print currently supports notifications for two scenarios related to print jobs:

  • PrintTask 被触发(作业启动):应用程序可以在其 printTask(hook) 触发时订阅以接收通知。PrintTask is triggered (JobStarted): An application can subscribe to receive notifications when their printTask(hook) is triggered. 若要详细了解如何触发任务,请参阅扩展通用 以支持将打印内容拉取For details about how to trigger a task, see Extending Universal Print to support pull printing. 目前,仅能为作业启动事件触发 printTask。Currently, a printTask can be triggered only for a JobStarted event. 成功创建打印作业、上传有效负载并开始作业处理后,将发生作业启动事件。A JobStarted event is raised when a print job has been successfully created, its payload has been uploaded, and job processing has started.

  • 作业可保存:作业启动后,第三方打印应用程序或通用打印可能会执行某些处理(例如将 XPS 有效负载转换为 PDF,用于 PDF 打印机)。JobFetchable: After the job has started, third-party print applications or Universal Print might do some processing (like converting XPS payload to PDF for a PDF printer). 处理完成后,如果有效负载已准备好由打印机下载,则针对相应的打印作业将发生 JobFable 事件。After processing is complete and the payload is ready to be downloaded by a printer, a JobFetchable event is raised for the corresponding print job.

备注

为收听 JobFableable 事件更改通知, printTaskDefinition 更改通知。For listening to the change notifications for JobFetchable event, a printTaskDefinition resource is not required.

创建可收听通知的应用程序Create an application to listen to notifications

若要了解如何收听 Microsoft Graph 通知,请参阅 通过 Microsoft Graph 使用更改通知和修订 设置用户数据更改通知 - 代码示例For information about how to listen for Microsoft Graph notifications, see Use change notifications and track changes with Microsoft Graph and Set up notifications for changes in user data – Code Samples.

ScopesScopes

若要订阅打印作业通知,应用程序必须具有在客户的 Azure AD 租户中批准的下列权限范围:To subscribe to notifications for print jobs, applications must have the following permission scopes approved in the customer’s Azure AD tenant:

应用程序必须 Microsoft Graph API 请求标头中生成 Azure AD 安全令牌。Applications must generate and use the Azure AD security token in the Microsoft Graph API request header. 安全令牌包含按管理员批准的客户 Azure AD 租户范围内声明声明。The security token contains the claims as per the scopes approved for the customer’s Azure AD tenant by its administrator.

创建订阅:printTask 触发(作业启动)事件Create subscription: printTask triggered (JobStarted) event

某些应用程序监视传入作业的打印队列,希望在队列中具有有效作业时收到通知。Some applications monitor print queues for incoming jobs and want to be notified as soon as there is a valid job in the queue. 收到通知后,他们可以收集相关的作业元数据,甚至可以在打印作业中执行修改,包括中止作业或相应地修改作业属性后将作业从当前打印队列重定向到另一个队列。After theyt're notified, they can collect the relevant job metadata or even perform modifications in the print job – including aborting the job or redirecting the job from the current print queue to another queue after modifying the job attributes accordingly.

在创建打印任务 - 事件的通知之前,请确保应用程序创建了以下应用程序:Before creating a notification for a printTask-triggered event, ensure that application has created the following:

  • Azure AD printTaskDefinition 应用程序。A printTaskDefinition for the customer’s Azure AD tenant. 单个任务定义可在同一 Azure AD 租户中的一个或多个打印机关联。A single task definition can be associated with one or more printers within the same Azure AD tenant.

  • 针对 开始新打印作业时,合作伙伴希望接收其通知的每个打印机队列的 "PrintTaskTri你邮件"标签。A printTaskTrigger for each of the printer queues for which the partner wants to receive a notification when a new print job starts. printTaskDefinition 需要绑定到 PrintTaskDefinitionThe printTaskTrigger needs to be bound to the printTaskDefinition.

备注

一个打印机只能与一个 printTaskTriition 和一个 printTaskTriition 只能与一 printTaskDefinitionOne printer can be associated with only one printTaskTrigger and one printTaskTrigger can be associated with only one printTaskDefinition. 但是,一 printTaskDefinition 可以具有一 一个或多个 printTaskTriitions 与其关联。However, one printTaskDefinition can have one or more printTaskTriggers associated with it.

使用客户的 Azure A D 租户 printTaskDefinition,该应用程序可以使用 printTaskDefinition为 printTask 触发(作业启动)事件创建订阅。With the printTaskDefinition that exists for customer’s Azure AD tenant, the application can create a subscription for a printTask triggered (JobStarted) event using the printTaskDefinition. 创建订阅时:While creating the subscription:

  • resource 字段需要设置为 print/taskDefinitions/{printTaskDefinition ID}/tasksThe resource field needs to be set as print/taskDefinitions/{printTaskDefinition ID}/tasks.
  • changeType 字段需要设置为 createdThe changeType field needs to be set as created.
  • " expirationDateTime "字段需要小于 最大到期日期The expirationDateTime field needs to be less than the maximum expiration time.

如需了解更多详情,请参阅 openTypeExtension 资源类型For more details, see Subscription resource type properties.

下面展示了示例请求。The following is an example of the request.

POST https://graph.microsoft.com/beta/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" 
} 

响应Response

以下示例显示了相应的响应。The following example shows the response.

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "@odata.context": "https://graph.microsoft.com/beta/$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 
}

创建订阅:作业可创建事件Create subscription: JobFetchable event

一些云应用程序需要准备好后从通用打印中下载打印作业。Some cloud applications need to download print jobs from Universal Print when they are ready. 由于在云中运行的这些应用程序不在客户的防火墙后面,因此可在下载打印作业时使用 Microsoft Graph 更改通知。Because these applications running in the cloud are not behind the customer's firewall, they can use Microsoft Graph change notifications to be notified when a print job is ready to be downloaded.

备注

打印作业进入作业可打印状态时不可修改。Print jobs can't be modified when they enter the JobFetchable state. 需要针对每个打印机队列创建可作业通知。A JobFetchable notification needs to be created for each printer queue. 创建订阅时:While creating the subscription:

  • " resource "字段需要设置为"print/printer/{printer id}/jobs"。The resource field needs to be set as 'print/printers/{printer id}/jobs'.
  • changeType 字段需要设置为 updatedThe changeType field needs to be set as updated.
  • notificationQueryOptions 字段需要设置为 $filter = isFetchable eq trueThe notificationQueryOptions field needs to be set as $filter = isFetchable eq true.
  • " expirationDateTime "字段需要小于 最大到期日期The expirationDateTime field needs to be less than the maximum expiration time.

如需了解更多详情,请参阅 openTypeExtension 资源类型For more details, see Subscription resource type properties.

下面展示了示例请求。The following is an example of the request.

POST https://graph.microsoft.com/beta/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"
} 

响应Response

以下示例显示了相应的响应。The following example shows the response.

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "@odata.context": "https://graph.microsoft.com/beta/$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
}

续订通知订阅Renewing a notification subscription

Microsoft Graph 对到期时间有限制。Microsoft Graph has a limit on the expiration time. 有关详细信息,请参阅 的到期日期For details, see maximum expiration time. 若要继续接收通知,需使用更新订阅 API 更新 定期续订To continue receiving notifications, the subscription needs to be renewed periodically by using the Update subscription API.

通知订阅的其他操作Other operations on notification subscriptions

应用程序 获取 的详细信息,或者 删除 订阅。Applications can get details of the subscription or can delete a subscription when required. 有关详细信息,请参阅 Microsoft Graph API 通过更改通知For details, see Use the Microsoft Graph API to get change notifications.

常见问题FAQs

Microsoft Graph 如何验证通知 URL?How does Microsoft Graph validate notification URLs?

Microsoft Graph 将验证创建订阅前订阅请求的 notificationurl 属性中提供的通知终结点。Microsoft Graph validates the notification endpoint provided in the notificationUrl property of the subscription request before creating the subscription. 有关详细信息,请参阅 终结点验证For details, see Notification endpoint validation.

收到更改通知后,应用程序应执行哪些操作?What are applications expected to do after receiving a change notification?

应用程序应处理和确认他们收到的每个更改通知。Applications should process and acknowledge every change notification they receive. 有关详细信息,请参阅 更改通知For details, see Processing the change notification.

如何获取活动订阅列表?How can I get a list of active subscriptions?

若要详细了解如何检索 Web 网站订阅列表,请参阅 订阅For details about how to retrieve a list of webhook subscriptions, see List subscriptions.

另请参阅See also