Abonnieren von Änderungsbenachrichtigungen von Clouddruck-APIs mit Microsoft Graph

  • Artikel

Universelles Drucken unterstützt Kunden beim Verlegen ihrer Druckinfrastruktur in die Cloud und ist Teil eines stabilen Systems aus Partnerlösungen, die erweiterte Druckfunktionen bieten. Die Leistungsfähigkeit dieser Lösungen kann zusätzlich gesteigert werden, wenn Sie die Clouddruck-APIs in Microsoft Graph für die Integration in Universelles Drucken verwenden.

Viele Partnerlösungen müssen von den Benutzergeräten an die Drucker gesendete Druckaufträge in Echtzeit verarbeiten. Dies bedeutet, dass sie benachrichtigt werden müssen, wenn Druckaufträge zur Verarbeitung verfügbar sind. Universelles Drucken bietet Hooks für Druckanbieterlösungen, die über Aufträge in der Cloud benachrichtigt werden, und APIs, die die Verwaltung von Druckern und Druckaufträgen ermöglichen.

In diesem Artikel wird erläutert, wie Sie Benachrichtigungen für verschiedene Druckauftragsereignisse abonnieren können.

Erste Schritte mit Änderungsbenachrichtigungen

Bevor Sie änderungsbenachrichtigungen über Microsoft Graph nutzen können, müssen Sie Ihre Anwendung in Azure registrieren und Ihre Anwendung im Kunden Microsoft Entra Mandanten bereitstellen. Stellen Sie sicher, dass für die Anwendung die erforderlichen Berechtigungsbereiche aktiviert sind, wie weiter unten in diesem Artikel beschrieben.

Benachrichtigungen und Abonnements

Universelles Drucken unterstützt derzeit Benachrichtigungen für zwei Szenarien im Zusammenhang mit Druckaufträgen:

  • "PrintTask is triggered (JobStarted)": Eine Anwendung kann Benachrichtigungen zum Auslösen ihres PrintTask(Hook) abonnieren. Details zum Auslösen einer Aufgabe finden Sie unter Aktivieren des Pull-Drucks. Aktuell kann ein Druckauftrag nur für ein "JobStarted"-Ereignis ausgelöst werden. Ein "JobStarted"-Ereignis wird ausgelöst, wenn ein Druckauftrag erfolgreich erstellt wurde, die Nutzdaten hochgeladen und die Auftragsverarbeitung gestartet wurde.

  • "JobFetchable": Nach dem Starten des Auftrags kann eine Verarbeitung durch Druckanwendungen von Drittanbietern oder Universelles Drucken erfolgen (z. B. Konvertieren von XPS-Nutzdaten in PDF bei einem PDF-Drucker). Nach Abschluss der Verarbeitung und wenn die Nutzdaten bereit zum Herunterladen durch einen Drucker sind, wird für den entsprechenden Druckauftrag ein "JobFetchable"-Ereignis ausgelöst.

Hinweis

Für die Überwachung auf Änderungsbenachrichtigungen zu JobFetchable-Ereignissen ist keine printTaskDefinition-Ressource erforderlich.

Die Anwendung sollte doppelte Benachrichtigungen verarbeiten.

Erstellen einer Anwendung zum Überwachen auf Benachrichtigungen

Informationen zum Lauschen auf Microsoft Graph-Benachrichtigungen finden Sie unter Einrichten von Benachrichtigungen für Änderungen an Benutzerdaten – Codebeispiele.

Berechtigungsbereiche

Um Benachrichtigungen für Druckaufträge zu abonnieren, müssen für Anwendungen die folgenden Berechtigungsbereiche im Microsoft Entra Mandanten des Kunden genehmigt sein:

  • Für "printTask triggered (JobStarted)"-Ereignisse: die in Get taskDefinition aufgeführten Berechtigungen.

  • Für "JobFetchable"-Ereignisse: die in Abonnement erstellen aufgeführten Berechtigungen.

Anwendungen müssen das Microsoft Entra Sicherheitstoken im Microsoft Graph-API-Anforderungsheader generieren und verwenden. Das Sicherheitstoken enthält die Ansprüche gemäß den Bereichen, die vom Administrator für den Microsoft Entra Mandanten des Kunden genehmigt wurden.

Erstellen eines Abonnements: "PrintTask triggered (JobStarted)"-Ereignis

Einige Anwendungen überwachen Druckwarteschlangen auf eingehende Aufträge und sollten benachrichtigt werden, sobald sich ein gültiger Auftrag in der Warteschlange befindet. Nachdem sie benachrichtigt wurden, können sie die relevanten Auftragsmetadaten erfassen oder sogar Änderungen am Druckauftrag vornehmen – z. B. den Auftrag abbrechen oder ihn von der aktuellen in eine andere Druckwarteschlange umleiten, nachdem die Jobattribute entsprechend geändert wurden.

Stellen Sie vor dem Erstellen einer Benachrichtigung zu einem "printTasktriggered"-Ereignis sicher, dass die Anwendung Folgendes erstellt hat:

  • Eine printTaskDefinition für den Microsoft Entra Mandanten des Kunden. Eine einzelne Aufgabendefinition kann einem oder mehreren Druckern innerhalb desselben Microsoft Entra Mandanten zugeordnet werden.

  • Ein printTaskTrigger für jede der Druckerwarteschlangen, für die der Partner eine Benachrichtigung erhalten möchte, wenn ein neuer Druckauftrag gestartet wird. Das printTaskTrigger muss an das printTaskDefinition gebunden werden.

Hinweis

Einem einzelnen Drucker kann nur ein printTaskTrigger und einem einzelnen printTaskTrigger kann nur ein printTaskDefinitionzugeordnet werden. Einem printTaskDefinition können hingegen ein oder mehrere printTaskTriggers zugeordnet werden.

Mit der printTaskDefinition, die für den Microsoft Entra Mandanten des Kunden vorhanden ist, kann die Anwendung mithilfe von printTaskDefinition ein Abonnement für ein printTask-ausgelöstes (JobStarted)-Ereignis erstellen. Zu beachten beim Erstellen des Abonnements:

  • Das resource-Feld muss auf print/taskDefinitions/{printTaskDefinition ID}/tasks festgelegt werden.
  • Das changeType-Feld muss auf created festgelegt werden.
  • Das expirationDateTime-Feld muss einen kleineren Wert als die maximale Ablaufzeit aufweisen.

Weitere Informationen finden Sie unter Eigenschaften des subscription-Ressourcentyps.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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 
}

Erstellen eines Abonnements: JobFetchable-Ereignis

Einige Cloudanwendungen müssen Druckaufträge von Universelles Drucken herunterladen, wenn sie bereit sind. Da sich diese in der Cloud ausgeführten Anwendungen nicht hinter der Firewall des Kunden befinden, können sie Microsoft Graph-Änderungsbenachrichtigungen verwenden, um benachrichtigt zu werden, wenn ein Druckauftrag heruntergeladen werden kann.

Hinweis

Druckaufträge können nicht mehr geändert werden, wenn sie in den Status "JobFetchable" übergehen. Für jede Druckerwarteschlange muss eine JobFetchable-Benachrichtigung erstellt werden. Zu beachten beim Erstellen des Abonnements:

  • Das resource-Feld muss als 'print/printers/{printer id}/jobs' (drucken/Drucker/{Drucker-ID}/Aufträge) festgelegt werden.
  • Das changeType-Feld muss auf updated festgelegt werden.
  • Das notificationQueryOptions-Feld muss auf $filter = isFetchable eq true festgelegt werden.
  • Das expirationDateTime-Feld muss einen kleineren Wert als die maximale Ablaufzeit aufweisen.

Weitere Informationen finden Sie unter Eigenschaften des subscription-Ressourcentyps.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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
}

Erneuerung eines Abonnements für Benachrichtigungen

In Microsoft Graph besteht ein Limit für Ablaufzeiten. Einzelheiten hierzu finden Sie unter maximale Ablaufzeit. Damit weiterhin Benachrichtigungen erhalten werden, muss das Abonnement in regelmäßigen Abständen mithilfe der Abonnementerneuerungs-API verlängert werden.

Abonnements für Benachrichtigungen abrufen oder löschen

Anwendungen können bei Bedarf Details zum Abonnement abrufen oder ein Abonnement löschen. Einzelheiten finden Sie unter Verwenden der Microsoft Graph-API, um Änderungsbenachrichtigungen zu erhalten.

Häufig gestellte Fragen

Wie überprüft Microsoft Graph Benachrichtigungs-URLs?

Microsoft Graph überprüft den Benachrichtigungsendpunkt, der in der Eigenschaft notificationUrl der Abonnementanfrage angegeben ist, bevor das Abonnement erstellt wird. Einzelheiten hierzu finden Sie unter Überprüfung von Benachrichtigungsendpunkten.

Was sollten Anwendungen nach dem Empfang einer Änderungsbenachrichtigung tun?

Anwendungen sollten jede empfangene Änderungsbenachrichtigung verarbeiten und bestätigen. Weitere Informationen finden Sie unter Verarbeitung von Änderungsbenachrichtigungen.

Wie kann ich die Authentizität von Benachrichtigungen überprüfen?

Die Authentizität von Benachrichtigungen kann mit dem clientState-Wert überprüft werden, wie in Verarbeiten der Änderungsbenachrichtigung beschrieben, oder durch Validieren von Token in der Änderungsbenachrichtigung.

Wie kann ich eine Liste der aktiven Abonnements erhalten?

Details zum Abrufen einer Liste von Webhook-Abonnements finden Sie unter Abonnements auflisten.

Verwandte Inhalte