Suscribirse para cambiar las notificaciones de las API de impresión en la nube con Microsoft GraphSubscribe to change notifications from cloud printing APIs using Microsoft Graph

Impresión universal ayuda a los clientes a mover su infraestructura de impresión a la nube y forma parte de un sólido ecosistema de soluciones para asociados que ofrecen funciones de impresión avanzadas.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. Estas soluciones pueden ser aún más eficaces cuando usa las API de impresión de la nube en Microsoft Graph para integrarlas con Impresión universal.These solutions can become even more powerful when you use the cloud printing APIs in Microsoft Graph to integrate with Universal Print.

Muchas soluciones de asociados necesitan procesar trabajos de impresión en tiempo real a medida que se envían desde los dispositivos de los usuarios a las impresoras, lo cual significa que necesitan recibir una notificación cada vez que haya trabajos de impresión disponibles para su procesamiento.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. La Impresión universal proporciona enlaces para que las soluciones de los proveedores de impresión reciban una notificación a medida que los trabajos se mueven por la nube, así como API que permiten la administración de los trabajos de impresión y las impresoras.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.

En este artículo se describe cómo suscribirse para recibir las notificaciones de distintos eventos de trabajo de impresión.This article describes how to subscribe to notifications for various print job events.

Introducción a las notificaciones de cambioGet started with change notifications

Para poder aprovechar las notificaciones de cambio a través de Microsoft Graph, primero debe registrar su aplicación en Azure y aprovisionar la aplicación en el espacio empresarial de clientes de Azure Active Directory (Azure AD).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. Asegúrese de que la aplicación tenga habilitados los ámbitos de permisos necesarios, según se describe más adelante en este artículo.Make sure that the application has the required permission scopes enabled, as described later in this article.

Notificaciones y suscripcionesNotifications and subscriptions

La Impresión universal actualmente admite notificaciones para dos situaciones relacionadas con los trabajos de impresión:Universal Print currently supports notifications for two scenarios related to print jobs:

  • Se activa printTask (JobStarted): Una aplicación puede suscribirse para recibir notificaciones cuando se activa su printTask (enlace).PrintTask is triggered (JobStarted): An application can subscribe to receive notifications when their printTask(hook) is triggered. Para obtener más detalles acerca de cómo desencadenar una tarea, consulte Extender la Impresión universal para que sea compatible con la extracción de impresiones.For details about how to trigger a task, see Extending Universal Print to support pull printing. Actualmente, una printTask solo se puede desencadenar para un evento JobStarted.Currently, a printTask can be triggered only for a JobStarted event. Un evento JobStarted se genera cuando se ha creado correctamente un trabajo de impresión, se sube su carga y se inicia el procesamiento del trabajo.A JobStarted event is raised when a print job has been successfully created, its payload has been uploaded, and job processing has started.

  • JobFetchable: Después de iniciado el trabajo, las aplicaciones de impresión de terceros o la Impresión universal podrían realizar cierto procesamiento (como convertir una carga XPS en PDF para una impresora 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). Una vez que esté completado el procesamiento y esté lista la carga para ser descargada por una impresora, se genera un evento JobFetchable para el trabajo de impresión correspondiente.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.

Nota

Para escuchar las notificaciones de cambio del evento JobFetchable, no es necesario usar ningún recurso de printTaskDefinition.For listening to the change notifications for JobFetchable event, a printTaskDefinition resource is not required.

Crear una aplicación para escuchar las notificacionesCreate an application to listen to notifications

Para obtener información sobre cómo escuchar las notificaciones de Microsoft Graph, consulte Usar notificaciones de cambio y supervisar los cambios con Microsoft Graph y Configurar las notificaciones de cambio en los datos del usuario: ejemplos de código.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.

ÁmbitosScopes

Para suscribirse a las notificaciones para los trabajos de impresión, las aplicaciones deben tener los siguientes ámbitos de permisos aprobados en el espacio empresarial de Azure AD del cliente:To subscribe to notifications for print jobs, applications must have the following permission scopes approved in the customer’s Azure AD tenant:

Las aplicaciones deben generar y usar el token de seguridad de Azure AD en el encabezado de solicitud de la API de Microsoft Graph.Applications must generate and use the Azure AD security token in the Microsoft Graph API request header. El token de seguridad contiene las notificaciones según los ámbitos aprobados por su administrador para el espacio empresarial de Azure AD del cliente.The security token contains the claims as per the scopes approved for the customer’s Azure AD tenant by its administrator.

Crear una suscripción: Evento printTask (JobStarted) desencadenadoCreate subscription: printTask triggered (JobStarted) event

Algunas aplicaciones supervisan las colas de impresión en busca de trabajos entrantes y quieren recibir la notificación tan pronto llegue un trabajo válido a la cola.Some applications monitor print queues for incoming jobs and want to be notified as soon as there is a valid job in the queue. Cuando se les notifique, podrán recopilar los metadatos de trabajo relevantes o incluso realizar modificaciones en el trabajo de impresión (por ejemplo, anular el trabajo o redirigir el trabajo de la cola de impresión actual a otra cola, después de modificar los atributos de trabajo correspondientes).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.

Antes de crear una notificación para un evento desencadenado por printTask, asegúrese de que la aplicación haya creado lo siguiente:Before creating a notification for a printTask-triggered event, ensure that application has created the following:

  • Una printTaskDefinition para el espacio empresarial de Azure AD del cliente.A printTaskDefinition for the customer’s Azure AD tenant. Se puede asociar una única definición de tarea a más de una impresora dentro de la misma cuenta empresarial de Azure AD.A single task definition can be associated with one or more printers within the same Azure AD tenant.

  • Se crea un printTaskTrigger para cada una de las colas de la impresora de las que su asociado quiera recibir notificación cuando se inicie un nuevo trabajo de impresión.A printTaskTrigger for each of the printer queues for which the partner wants to receive a notification when a new print job starts. El printTaskTrigger debe estar enlazado al printTaskDefinition.The printTaskTrigger needs to be bound to the printTaskDefinition.

Nota

Se puede asociar una impresora con un único printTaskTrigger y un printTaskTrigger puede asociarse únicamente a una printTaskDefinition.One printer can be associated with only one printTaskTrigger and one printTaskTrigger can be associated with only one printTaskDefinition. Sin embargo, una printTaskDefinition puede tener más de un printTaskTriggers asociado.However, one printTaskDefinition can have one or more printTaskTriggers associated with it.

Con la printTaskDefinition que existe para el espacio empresarial de Azure AD del cliente, la aplicación puede crear una suscripción para un evento printTask desencadenado (JobStarted) usando el printTaskDefinition.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. Mientras crea la suscripción:While creating the subscription:

  • El campo resource debe establecerse como print/taskDefinitions/{printTaskDefinition ID}/tasks.The resource field needs to be set as print/taskDefinitions/{printTaskDefinition ID}/tasks.
  • El campo changeType debe establecerse como created.The changeType field needs to be set as created.
  • El campo expirationDateTime debe ser menor que la fecha máxima de expiración.The expirationDateTime field needs to be less than the maximum expiration time.

Para obtener más información, consulte Propiedades del tipo de recurso de la suscripción.For more details, see Subscription resource type properties.

Aquí tiene un ejemplo de la solicitud.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" 
} 

RespuestaResponse

En el ejemplo siguiente se muestra la respuesta.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 
}

Crear suscripción: evento JobFetchableCreate subscription: JobFetchable event

Algunas aplicaciones en la nube necesitan descargar trabajos de impresión desde Impresión universal cuando estén listas.Some cloud applications need to download print jobs from Universal Print when they are ready. Como estas aplicaciones que se ejecutan en la nube no se encuentran detrás del firewall del cliente, pueden usar las notificaciones de cambio de Microsoft Graph para que se les notifique cuando un trabajo de impresión esté listo para su descarga.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.

Nota

Los trabajos de impresión no se pueden modificar cuando pasan al estado JobFetchable.Print jobs can't be modified when they enter the JobFetchable state. Es necesario crear una notificación JobFetchable para cada cola de la impresora.A JobFetchable notification needs to be created for each printer queue. Mientras crea la suscripción:While creating the subscription:

  • El campo resource debe establecerse como "trabajos de impresión/de la impresora/{id. de la impresora}".The resource field needs to be set as 'print/printers/{printer id}/jobs'.
  • El campo changeType debe establecerse como updated.The changeType field needs to be set as updated.
  • El campo notificationQueryOptions debe establecerse como $filter = isFetchable eq true.The notificationQueryOptions field needs to be set as $filter = isFetchable eq true.
  • El campo expirationDateTime debe ser menor que la fecha máxima de expiración.The expirationDateTime field needs to be less than the maximum expiration time.

Para obtener más información, consulte Propiedades del tipo de recurso de la suscripción.For more details, see Subscription resource type properties.

Aquí tiene un ejemplo de la solicitud.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"
} 

RespuestaResponse

En el ejemplo siguiente se muestra la respuesta.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
}

Renovar una suscripción de notificaciónRenewing a notification subscription

Microsoft Graph tiene un límite para la fecha de expiración.Microsoft Graph has a limit on the expiration time. Para obtener más información, consulte la fecha máxima de expiración.For details, see maximum expiration time. Para seguir recibiendo notificaciones, la suscripción debe renovarse periódicamente mediante el uso de la API de actualización de la suscripción.To continue receiving notifications, the subscription needs to be renewed periodically by using the Update subscription API.

Otras operaciones de las suscripciones de notificaciónOther operations on notification subscriptions

Las aplicaciones pueden obtener detalles de la suscripción o eliminar una suscripción, según sea necesario.Applications can get details of the subscription or can delete a subscription when required. Para obtener más detalles, consulte Usar la API de Microsoft Graph para obtener las notificaciones de cambio.For details, see Use the Microsoft Graph API to get change notifications.

Preguntas frecuentesFAQs

¿Cómo valida Microsoft Graph las direcciones URL de notificación?How does Microsoft Graph validate notification URLs?

Microsoft Graph valida el punto de conexión de la notificación indicado en la propiedad notificationUrl de la solicitud de suscripción antes de crear la suscripción.Microsoft Graph validates the notification endpoint provided in the notificationUrl property of the subscription request before creating the subscription. Para obtener más información, consulte Validación de la notificación del punto de conexión.For details, see Notification endpoint validation.

¿Qué se espera que hagan las aplicaciones después de recibir una notificación de cambio?What are applications expected to do after receiving a change notification?

Las aplicaciones deben procesar y confirmar cada notificación de cambio que reciben.Applications should process and acknowledge every change notification they receive. Para obtener más información, consulte Procesamiento de la notificación de cambios.For details, see Processing the change notification.

¿Cómo puedo obtener una lista de las suscripciones activas?How can I get a list of active subscriptions?

Para obtener más información sobre cómo recuperar una lista de suscripciones de webhook, consulte Suscripciones a la lista.For details about how to retrieve a list of webhook subscriptions, see List subscriptions.

Consulte tambiénSee also