Microsoft Graph を使用して、クラウド印刷 API からの変更通知を購読する

Universal Printは、顧客が印刷インフラストラクチャをクラウドに移行するのに役立ち、高度な印刷機能を提供するパートナー ソリューションの堅牢なエコシステムの一部です。 これらのソリューションは、Microsoft Graph のクラウド印刷 APIを 使用して Universal Print と統合すると、さらに強力になる可能性があります。

多くのパートナー ソリューションでは、印刷ジョブがユーザーのデバイスからプリンターに送信されるときにリアルタイムで処理する必要があります。つまり、印刷ジョブが処理可能になったときに通知を受ける必要があります。 Universal Print は、ジョブがクラウドを移動するときに通知される印刷ベンダー ソリューションのフック、およびプリンターと印刷ジョブの管理を可能にする API を提供します。

この記事では、さまざまな印刷ジョブイベントの通知を購読する方法について説明します。

変更通知を開始する

Microsoft Graph を使用して変更通知を利用するには、Azure にアプリケーションを登録し、顧客Microsoft Entraテナントでアプリケーションをプロビジョニングする必要があります。 この記事の後半で説明するように、アプリケーションで必要なアクセス許可スコープが有効になっていることを確認してください。

通知とサブスクリプション

Universal Print は現在、印刷ジョブに関連する 2 つのシナリオの通知をサポートしています。

• PrintTask がトリガーされます (JobStarted)：アプリケーションは、printTask (フック) がトリガーされたときに通知を受信するようにサブスクライブできます。 タスクをトリガーする方法の詳細については、「プル印刷を有効にする」を参照してください。 現在、printTask は JobStarted イベントに対してのみトリガーできます。 JobStarted イベントは、印刷ジョブが正常に作成され、そのペイロードがアップロードされ、ジョブ処理が開始されたときに発生します。

• JobFetchable: ジョブの開始後、サードパーティの印刷アプリケーションまたは Universal Print が何らかの処理 (PDFプリンター用に XPS ペイロードを PDF に変換するなど) を行う場合があります。 処理が完了し、ペイロードをプリンターでダウンロードする準備ができたら、対応する印刷ジョブに対して JobFetchable イベントが発生します。

注:

JobFetchable イベントの変更通知をリッスンするために、printTaskDefinition リソースは必要ありません。

重複する通知はアプリケーションにより処理されます。

通知をリッスンするためのアプリケーションを作成する

Microsoft Graph の通知をリッスンする方法については、「 ユーザー データの変更に関する通知の設定 - コード サンプル」を参照してください。

アクセス許可のスコープ

印刷ジョブの通知をサブスクライブするには、アプリケーションに次のアクセス許可スコープが顧客のMicrosoft Entra テナントで承認されている必要があります。

• printTask トリガー (JobStarted) イベントの場合、Get taskDefinition にリストされているアクセス許可。

• JobFetchable イベントの場合、「サブスクリプションの作成」にリストされているアクセス許可。

アプリケーションは、Microsoft Graph API 要求ヘッダーでMicrosoft Entraセキュリティ トークンを生成して使用する必要があります。 セキュリティ トークンには、管理者によって顧客のMicrosoft Entra テナントに対して承認されたスコープに従って要求が含まれます。

サブスクリプションの作成: printTask トリガー (JobStarted) イベント

一部のアプリケーションは、受信ジョブの印刷キューを監視して、キューに有効なジョブがあるとすぐに通知を受け取ろうとします。 通知を受けた後、関連するジョブ メタデータを収集したり、印刷ジョブの変更を実行したりできます。たとえば、ジョブの属性を適宜変更した後、ジョブを中止したり、現在の印刷キューから別のキューにジョブをリダイレクトしたりできます。

printTask によってトリガーされるイベントの通知を作成する前に、アプリケーションが以下を作成したことを確認してください。

• 顧客のMicrosoft Entra テナントの printTaskDefinition。 1 つのタスク定義を、同じMicrosoft Entra テナント内の 1 つ以上のプリンターに関連付けることができます。

• 新しい印刷ジョブの開始時にパートナーが通知を受信する必要がある各プリンター キューの printTaskTrigger。 printTaskTrigger は printTaskDefinition にバインドする必要があります。

注:

1 つのプリンターは 1 つの printTaskTrigger にのみ関連付けることができ、1 つの printTaskTrigger は 1 つの printTaskDefinition にのみ関連付けることができます。 ただし、1 つの printTaskDefinition には、1 つ以上の printTaskTriggers を関連付けることができます。

お客様のMicrosoft Entra テナントに存在する printTaskDefinition を使用すると、アプリケーションは printTaskDefinition を使用して printTask トリガー (JobStarted) イベントのサブスクリプションを作成できます。 サブスクリプションの作成中:

• resource フィールドは print/taskDefinitions/{printTaskDefinition ID}/tasks として設定する必要があります。
• changeType フィールドは created として設定する必要があります。
• expirationDateTime フィールドは最大有効期限よりも短くする必要があります。

詳細については、「サブスクリプション リソースの種類」を参照してください。

要求

次の例は要求を示しています。

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

応答

次の例は応答を示しています。

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 
}

サブスクリプションの作成: JobFetchable イベント

一部のクラウド アプリケーションは、準備ができたらユニバーサル プリントから印刷ジョブをダウンロードする必要があります。 クラウドで実行されているこれらのアプリケーションは顧客のファイアウォールの背後にないため、Microsoft Graph の変更通知を使用して、印刷ジョブをダウンロードする準備ができたときに通知を受け取ることができます。

注:

印刷ジョブは、JobFetchable 状態に入ったときには変更できません。 JobFetchable 通知は、プリンター キューごとに作成する必要があります。 サブスクリプションの作成中:

• resource フィールドは、'print/printers/{printer id}/jobs' として設定する必要があります。
• changeType フィールドは updated として設定する必要があります。
• notificationQueryOptions フィールドは $filter = isFetchable eq true として設定する必要があります。
• expirationDateTime フィールドは最大有効期限よりも短くする必要があります。

詳細については、「サブスクリプション リソースの種類」を参照してください。

要求

次の例は要求を示しています。

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

応答

次の例は応答を示しています。

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
}

サブスクリプション通知の更新

Microsoft Graph には、有効期限に制限があります。 詳細については、最大有効期限を参照してください。 通知を引き続き受信するには、サブスクリプションの更新 API を使用してサブスクリプションを定期的に更新する必要があります。

通知サブスクリプションを取得または削除する

アプリケーションは、サブスクリプションの詳細を取得したり、必要に応じてサブスクリプションを削除したりできます。 詳細については、「Microsoft Graph API を使用して変更通知を取得する」を参照してください。

よく寄せられる質問

Microsoft Graph は通知 URL をどのように検証しますか?

Microsoft Graph により、サブスクリプション作成の前にサブスクリプション要求の notificationUrl プロパティの中で提供される通知エンドポイントが検証されます。 詳細については、「通知エンドポイントの検証」を参照してください。

変更通知を受け取った後、アプリケーションは何をすることが期待されていますか?

アプリケーションは、受信したすべての変更通知を処理して確認する必要があります。 詳細については、「変更通知の処理」を参照してください。

通知の信頼性を検証するにはどうすればよいですか?

通知の信頼性は、変更通知の処理に記載されている通り clientState の値を使用するか、変更通知の検証トークンで検証できます。

アクティブなサブスクリプションのリストを取得するにはどうすればよいですか?

Webhookサブスクリプションのリストを取得する方法の詳細については、「サブスクリプションを一覧表示する」を参照してください。

関連コンテンツ

• Microsoft Graph のクラウド印刷 API の詳細については、「ユニバーサル印刷のクラウド印刷 API の概要」を参照してください。
• Microsoft Graph のクラウド印刷 API に関する提案やフィードバックについては、UniversalPrint 技術コミュニティ にアクセスしてください。