S’abonner aux notifications de modification émises par les API d’impression cloud à l’aide de Microsoft Graph

La fonctionnalité Impression universelle permet aux clients de migrer leur infrastructure d’impression vers le cloud. Elle fait partie d’un écosystème robuste de solutions partenaires qui offrent des fonctionnalités d’impression avancées. L’efficacité de ces solutions peut être renforcée si vous intégrez les API d’impression cloud de Microsoft Graph à la fonctionnalité Impression universelle.

Généralement, les solutions partenaires doivent traiter les tâches d’impression en temps réel lorsqu’elles sont envoyées à partir d’appareils des utilisateurs vers des imprimantes. Cela signifie qu’elles doivent être averties lorsque ces tâches d’impression doivent être traitées. La fonctionnalité Impression universelle fournit des hooks pour indiquer la migration de tâches d’impressions vers le cloud aux solutions des fournisseurs d’impression. Elle fournit également des API qui permettent la gestion des imprimantes et des tâches d’impression.

Cet article décrit comment s’abonner à des notifications relatives à différents événements de tâches d’impression.

Conditions préalables

Pour pouvoir utiliser les notifications de modification via Microsoft Graph, vous devez inscrire votre application dans Azure et la configurer dans le locataire (tenant) Azure Active Directory (Azure AD) des clients. Assurez-vous que l’application dispose des autorisations requises. Cette opération est décrite ultérieurement dans cet article.

Notifications et abonnements

La fonctionnalité Impression universelle prend actuellement en charge les notifications pour deux scénarios liés aux tâches d’impression :

  • Déclenchement d’une ressource printTask (événement « JobStarted ») : une application peut s’abonner à des notifications lorsque le hook de leur ressource printTask (« printTask(hook) ») est déclenché. Pour plus d’informations sur le déclenchement d’une tâche, consultez la section Extension de la fonctionnalité Impression universelle pour prendre en charge le pull printing. Pour l’instant, une ressource printTask peut être déclenchée uniquement pour un événement JobStarted. Un événement JobStarted est déclenché lorsqu’une tâche d’impression est correctement créée, que sa charge utile a été téléchargée et que le traitement de la tâche a commencé.

  • JobFetchable : une fois la tâche commencée, des applications d’impression tierces ou l’impression universelle peuvent s’occuper d’une partie du traitement (par exemple, en convertissant la charge utile XPS en PDF pour une imprimante PDF). Une fois le traitement terminé et la charge utile prête à être téléchargée par une imprimante, un événement JobFetchable peut être déclenché pour la tâche d’impression correspondante.

Notes

Il n’est pas nécessaire d’avoir une ressource printTaskDefinition pour l’écoute des notifications de modification d’un événement JobFetchable.

Créer une application pour l’écoute des notifications

Pour plus d’informations sur l’écoute des notifications Microsoft Graph, suivez le module Utiliser les notifications de modification et le suivi des modifications avec Microsoft Graph et consultez la section Exemples de code de la page Configuration des notifications pour les modifications des données utilisateur.

Étendues

Vos applications doivent bénéficier des autorisations suivantes dans le locataire (tenant) Azure AD de votre client pour pouvoir s’abonner aux notifications relatives aux tâches d’impression :

  • Les autorisations nécessaires au suivi des événements déclenchés (« JobStarted ») pour les ressources printTask sont répertoriées sur la page Obtenir taskDefinition.

  • Les autorisations nécessaires au suivi des événements JobFetchable sont répertoriées sur la page Créer un abonnement.

Les applications doivent générer et utiliser le jeton de sécurité Azure AD dans l’en-tête de demande de l’API Microsoft Graph. Le jeton de sécurité contient les revendications selon les autorisations approuvées pour le locataire (tenant) Azure AD du client par son administrateur.

Créer un abonnement à un événement JobStarted déclenché par une ressource printTask

Certaines applications surveillent les files d’attente d’impression pour les travaux entrants et doivent en être informées dès qu’une tâche valide arrive dans la file d’attente. Une fois ces applications averties, elles peuvent collecter les métadonnées des tâches pertinentes, voire même effectuer des modifications dans la tâche d’impression ( notamment annuler la tâche ou rediriger la tâche depuis la file d’attente d’impression actuelle vers une autre file d’attente après avoir modifié en conséquence les attributs de la tâche).

Avant de créer une notification pour un événement déclenché par une ressource printTask, assurez-vous que l’application a créé les éléments suivants :

  • Une ressource printTaskDefinition pour le locataire (tenant) Azure AD du client. Une définition de tâche peut être associée à une ou plusieurs imprimantes au sein du même client Azure AD.

  • Une ressource printTaskTrigger pour chaque file d’attente d’impression pour laquelle le partenaire souhaite recevoir une notification lors du démarrage d’une nouvelle tâche d’impression. La ressource printTaskTrigger doit être liée à la ressource printTaskDefinition.

Notes

Une imprimante ne peut être associée qu’à une seule ressource printTaskTrigger, et une ressource printTaskTrigger ne peut être associée qu’à une seule ressource printTaskDefinition. Toutefois, une ressource printTaskDefinition peut être associée à plusieurs ressources printTaskTrigger.

L’application peut utiliser la ressource printTaskDefinition du locataire (tenant) Azure AD du client pour créer un abonnement pour un événement JobStarted déclenché par une ressource printTask utilisant la ressource printTaskDefinition. Lors de la création de l’abonnement :

  • La valeur du champ resource doit être print/taskDefinitions/{printTaskDefinition ID}/tasks.
  • La valeur du champ changeType doit être created.
  • La valeur du champ expirationDateTime doit être inférieure au délai d’expiration maximal.

Pour en savoir plus, consultez la section Propriétés de la page Type de ressource Abonnement.

Voici un exemple de demande.

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

Réponse

L’exemple suivant illustre la réponse.

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 
}

Créer un abonnement à un événement JobFetchable

Certaines applications cloud doivent télécharger les tâches d’impression depuis la fonctionnalité Impression universelle une fois qu’elles sont prêtes. Comme ces applications exécutées dans le cloud ne sont pas protégées par le pare-feu du client, elles peuvent utiliser des notifications de modification de Microsoft Graph pour être averties lorsqu’un travail d’impression est prêt à être téléchargé.

Notes

Les tâches d’impression ne peuvent pas être modifiées lorsqu’elles passent à l’état JobFetchable. Une notification JobFetchable doit être créée pour chaque file d’attente d’impression. Lors de la création de l’abonnement :

  • La valeur du champ resource doit être 'print/printers/{printer id}/jobs'.
  • La valeur du champ changeType doit être updated.
  • La valeur du champ notificationQueryOptions doit être $filter = isFetchable eq true.
  • La valeur du champ expirationDateTime doit être inférieure au délai d’expiration maximal.

Pour en savoir plus, consultez la section Propriétés de la page Type de ressource Abonnement.

Voici un exemple de demande.

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

Réponse

L’exemple suivant illustre la réponse.

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
}

Renouvellement d’un abonnement aux notifications

La durée maximale des abonnements Microsoft Graph est limitée. Pour en savoir plus, consultez la section Durée maximale d’abonnement par type de ressource de la page Type de ressource Abonnement. Pour continuer à recevoir des notifications, l’abonnement doit être renouvelé régulièrement à l’aide de l’API de mise à jour d’abonnement.

Autres opérations relatives aux abonnements aux notifications

Les applications peuvent obtenir des détails sur l’abonnement ou supprimer un abonnement si nécessaire. Pour en savoir plus, consultez la page Utiliser l’API Graph de Microsoft pour obtenir les notifications de modification.

Foires aux questions

Comment Microsoft Graph valide-t-il les URL de notification ?

Microsoft Graph valide le point de terminaison de notification fourni dans la propriété notificationUrl de la demande d’abonnement avant de créer l’abonnement. Pour en savoir plus, consultez la section Validation du point de terminaison de notification de la page Configuration des notifications pour les modifications des données utilisateur.

Que sont censées faire les applications après la réception d’une notification de modification ?

Les applications doivent traiter et prendre en compte chaque notification de modification qu’elles reçoivent. Pour en savoir plus, consultez la section Traitement de la notification de modifications.

Comment obtenir la liste des abonnements actifs ?

Pour en savoir plus sur la récupération d’une liste d’abonnements web en ligne, consultez la page Liste des abonnements.

Voir aussi