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

  • Article

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

Avant de pouvoir tirer parti des notifications de modification via Microsoft Graph, vous devez inscrire votre application dans Azure et provisionner votre application dans le client Microsoft Entra client. 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 Activer l’impression par extraction. 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.

Remarque

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

L’application doit gérer les notifications en double.

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

Pour plus d’informations sur l’écoute des notifications Microsoft Graph, consultez Configurer des notifications pour les modifications apportées aux données utilisateur – Exemples de code.

Étendues d’autorisation

Pour s’abonner aux notifications pour les travaux d’impression, les applications doivent avoir les étendues d’autorisation suivantes approuvées dans le locataire Microsoft Entra du client :

  • 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é Microsoft Entra dans l’en-tête de requête Microsoft API Graph. Le jeton de sécurité contient les revendications conformément aux étendues approuvées pour le locataire Microsoft Entra 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 :

  • PrintTaskDefinition pour le locataire Microsoft Entra du client. Une définition de tâche unique peut être associée à une ou plusieurs imprimantes au sein du même Microsoft Entra locataire.

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

Remarque

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.

Avec printTaskDefinition qui existe pour le locataire Microsoft Entra du client, l’application peut créer un abonnement pour un événement printTask déclenché (JobStarted) à l’aide de 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.

Demande

L’exemple suivant illustre une 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é.

Remarque

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.

Demande

L’exemple suivant illustre une 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.

Obtenir ou supprimer des 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 valider l’authenticité des notifications ?

L’authenticité des notifications peut être validée à l’aide de la valeur clientState, comme décrit dans Traitement de la notification de modification ou Validation des jetons dans la notification de modification.

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.

Contenu connexe