Suscribirse para cambiar las notificaciones de las API de impresión en la nube con 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. 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.

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. 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.

En este artículo se describe cómo suscribirse para recibir las notificaciones de distintos eventos de trabajo de impresión.

Introducción a las notificaciones de cambio

Para poder aprovechar las notificaciones de cambios a través de Microsoft Graph, debe registrar la aplicación en Azure y aprovisionar la aplicación en los clientes Microsoft Entra inquilino. 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.

Notificaciones y suscripciones

La Impresión universal actualmente admite notificaciones para dos situaciones relacionadas con los trabajos de impresión:

  • Se activa printTask (JobStarted): Una aplicación puede suscribirse para recibir notificaciones cuando se activa su printTask (enlace). Para obtener más información sobre cómo desencadenar una tarea, consulte Habilitar la impresión de extracción. Actualmente, una printTask solo se puede desencadenar para un evento JobStarted. 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.

  • 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). 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.

Nota:

Para escuchar las notificaciones de cambio del evento JobFetchable, no es necesario usar ningún recurso de printTaskDefinition.

La aplicación debe controlar las notificaciones duplicadas.

Crear una aplicación para escuchar las notificaciones

Para obtener información sobre cómo escuchar notificaciones de Microsoft Graph, consulte Configuración de notificaciones para cambios en los datos de usuario: ejemplos de código.

Ámbitos de permiso

Para suscribirse a notificaciones para trabajos de impresión, las aplicaciones deben tener los siguientes ámbitos de permisos aprobados en el inquilino de Microsoft Entra del cliente:

Las aplicaciones deben generar y usar el token de seguridad de Microsoft Entra en el encabezado de solicitud de Microsoft Graph API. El token de seguridad contiene las notificaciones según los ámbitos aprobados para el inquilino Microsoft Entra del cliente por su administrador.

Crear una suscripción: Evento printTask (JobStarted) desencadenado

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. 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).

Antes de crear una notificación para un evento desencadenado por printTask, asegúrese de que la aplicación haya creado lo siguiente:

  • PrintTaskDefinition para el inquilino Microsoft Entra del cliente. Una única definición de tarea se puede asociar a una o varias impresoras dentro del mismo inquilino Microsoft Entra.

  • 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. El printTaskTrigger debe estar enlazado al printTaskDefinition.

Nota:

Se puede asociar una impresora con un único printTaskTrigger y un printTaskTrigger puede asociarse únicamente a una printTaskDefinition. Sin embargo, una printTaskDefinition puede tener más de un printTaskTriggers asociado.

Con el printTaskDefinition que existe para el inquilino de Microsoft Entra del cliente, la aplicación puede crear una suscripción para un evento printTask desencadenado (JobStarted) mediante printTaskDefinition. Mientras crea la suscripción:

  • El campo resource debe establecerse como print/taskDefinitions/{printTaskDefinition ID}/tasks.
  • El campo changeType debe establecerse como created.
  • El campo expirationDateTime debe ser menor que la fecha máxima de expiración.

Para obtener más información, consulte Propiedades del tipo de recurso de la suscripción.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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" 
} 

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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 
}

Crear suscripción: evento JobFetchable

Algunas aplicaciones en la nube necesitan descargar trabajos de impresión desde Impresión universal cuando estén listas. 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.

Nota:

Los trabajos de impresión no se pueden modificar cuando pasan al estado JobFetchable. Es necesario crear una notificación JobFetchable para cada cola de la impresora. Mientras crea la suscripción:

  • El campo resource debe establecerse como "trabajos de impresión/de la impresora/{printer id}/trabajos".
  • El campo changeType debe establecerse como updated.
  • El campo notificationQueryOptions debe establecerse como $filter = isFetchable eq true.
  • El campo expirationDateTime debe ser menor que la fecha máxima de expiración.

Para obtener más información, consulte Propiedades del tipo de recurso de la suscripción.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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"
} 

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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
}

Renovar una suscripción de notificación

Microsoft Graph tiene un límite para la fecha de expiración. Para obtener más información, consulte la fecha máxima de expiración. Para seguir recibiendo notificaciones, la suscripción debe renovarse periódicamente mediante el uso de la API de actualización de la suscripción.

Obtener o eliminar suscripciones de notificación

Las aplicaciones pueden obtener detalles de la suscripción o eliminar una suscripción, según sea necesario. Para obtener más detalles, consulte Usar la API de Microsoft Graph para obtener las notificaciones de cambio.

Preguntas frecuentes

¿Cómo valida Microsoft Graph las direcciones URL de notificación?

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. Para obtener más información, consulte Validación de la notificación del punto de conexión.

¿Qué se espera que hagan las aplicaciones después de recibir una notificación de cambio?

Las aplicaciones deben procesar y confirmar cada notificación de cambio que reciben. Para obtener más información, consulte Procesamiento de la notificación de cambios.

¿Cómo puedo validar la autenticidad de las notificaciones?

La autenticidad de las notificaciones se puede validar mediante el valor clientState como se describe en Procesar la notificación de cambio o Validar tokens en la notificación de cambio.

¿Cómo puedo obtener una lista de las suscripciones activas?

Para obtener más información sobre cómo recuperar una lista de suscripciones de webhook, consulte Suscripciones a la lista.