DICOM Pub/Sub 通知を構成する

このページでは、Pub/Sub を使用して DICOM ストア内の臨床イベントに関する通知を受け取る方法について説明します。新しい DICOM インスタンスが DICOM ストアに保存されたとき、または Cloud Storage からインポートされたときに、Pub/Sub 通知を受け取ることができます。

Pub/Sub 通知は、ダウンストリーム処理のトリガーや新しいデータの分析など、複数の目的のために使用できます。たとえば、機械学習モデルは、トレーニングに新しいデータが利用可能になったときに通知を受け取り、分析情報を生成して患者ケアを改善できます。

次の図は、Pub/Sub 通知が生成されてパブリッシュされる仕組みを示しています。

DICOM Pub/Sub 通知。

図 1. DICOM ストア内の臨床イベントに関する Pub/Sub 通知の受信。

図 1 は、次の手順を示しています。

呼び出し元が DICOM インスタンスの保存またはインポートをリクエストします。
DICOM ストアはリクエストを受け取り、Pub/Sub メッセージを作成して、DICOM ストアで構成された Pub/Sub トピックに送信します。
Pub/Sub は、トピックにアタッチされたサブスクリプションにメッセージを転送します。
サブスクライバーは、サブスクリプションからメッセージを受信します。並列処理を強化するために、各サブスクリプションに 1 つ以上のサブスクライバーを含めることが可能です。

準備

Pub/Sub パブリッシャー権限を追加する

Cloud Healthcare API から Pub/Sub にメッセージをパブリッシュするには、pubsub.publisher ロールをプロジェクトのCloud Healthcare サービスエージェント サービスアカウントに追加する必要があります。詳しくは、DICOM、FHIR、HL7v2 ストアの Pub/Sub 権限をご覧ください。

通知の形式と内容

Pub/Sub 通知には、臨床イベントに関する情報を含む Message オブジェクトが含まれています。DICOM Pub/Sub 通知には attributes フィールドが含まれていません。Message オブジェクトは次のようになります。

{
  "message": {
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

data フィールドの値は、Base64 でエンコードされた文字列として次の識別子です。projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID

各 Pub/Sub メッセージに含まれるフィールドの詳細については、ReceivedMessage と PubsubMessage をご覧ください。

通知を構成して表示する

このセクションでは、DICOM ストアで Pub/Sub 通知を有効にする方法、DICOM インスタンスを保存またはインポートして通知を公開する方法、通知を表示する方法について説明します。

DICOM ストアを構成する

このタスクに必要な権限

このタスクを実行するには、次の権限または Identity and Access Management（IAM）のロールが付与されている必要があります。

権限

healthcare.dicomStores.update

ロール

Healthcare DICOM ストア管理者（roles/healthcare.dicomStoreAdmin）

これらの Identity and Access Management ロールを付与するよう管理者に依頼できます。ロールの付与手順については、アクセスを管理するまたは Cloud Healthcare API リソースへのアクセスを制御するをご覧ください。必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

注: このガイド用に Google Cloud プロジェクトを作成した場合、プロジェクト作成者には権限のあるオーナー（roles/owner）IAM ロールが自動的に付与されます。追加の IAM ロールを付与する必要はありません。

次のサンプルは、新しい DICOM インスタンスが Cloud Storage に保存またはインポートされたときに、DICOM ストアで Pub/Sub 通知を有効にする方法を示しています。

REST

projects.locations.datasets.dicomStores.patch メソッドを使用します。

NotificationConfig.sendForBulkImport の値は true であるため、Cloud Storage からデータをインポートするときに通知が送信されます。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID
LOCATION: データセットの場所
DATASET_ID: DICOM ストアの親データセット
DICOM_STORE_ID: DICOM ストアの ID
PUBSUB_TOPIC: データストアでイベントが発生した場合にメッセージが公開される Pub/Sub トピック

リクエストの本文（JSON）:

{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

cat > request.json << 'EOF'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}
EOF

その後、次のコマンドを実行して REST リクエストを送信します。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID?updateMask=notificationConfig"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

@'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

その後、次のコマンドを実行して REST リクエストを送信します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID?updateMask=notificationConfig" | Select-Object -Expand Content

API Explorer

リクエスト本文をコピーして、メソッドのリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

次のようなレスポンスが返されます。

DicomStore リソースでフィールドを構成した場合は、そのフィールドもレスポンスに表示されます。

レスポンス

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  },
}

gcloud

gcloud healthcare dicom-stores update コマンドを実行します。

後述のコマンドデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud プロジェクトの ID
LOCATION: データセットの場所
DATASET_ID: DICOM ストアの親データセット
DICOM_STORE_ID: DICOM ストアの ID
PUBSUB_TOPIC: データストアでイベントが発生した場合にメッセージが公開される Pub/Sub トピック

次のコマンドを実行します。

Linux、macOS、Cloud Shell

gcloud healthcare dicom-stores update DICOM_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION \
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC \
  --send-for-bulk-import

Windows（PowerShell）

gcloud healthcare dicom-stores update DICOM_STORE_ID `
  --dataset=DATASET_ID `
  --location=LOCATION `
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC `
  --send-for-bulk-import

Windows（cmd.exe）

gcloud healthcare dicom-stores update DICOM_STORE_ID ^
  --dataset=DATASET_ID ^
  --location=LOCATION ^
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC ^
  --send-for-bulk-import

次のようなレスポンスが返されます。

レスポンス

Updated dicomStore [DICOM_STORE_ID].
...
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID
notificationConfig:
  pubsubTopic: projects/PROJECT_ID/topics/PUBSUB_TOPIC
  sendForBulkImport: true

DICOM インスタンスを保存またはインポートして、Pub/Sub 通知を表示する

このタスクに必要な権限

このタスクを実行するには、次の権限または Identity and Access Management（IAM）のロールが付与されている必要があります。

権限

healthcare.dicomStores.dicomWebWrite: リクエストされた DICOM ストアに DICOM インスタンスを保存します。
healthcare.dicomStores.import: リクエストされた DICOM ストアに DICOM インスタンスをインポートします。

ロール

Healthcare DICOM 編集者（roles/healthcare.dicomEditor）

DICOM インスタンスを保存またはインポートし、生成された Pub/Sub メッセージを pull するには、次の操作を行います。

DICOM インスタンスを保存またはimportします。このリクエストにより、Cloud Healthcare API は構成済みの Pub/Sub トピックにメッセージを公開します。
メッセージを取得します。単一のリクエストで複数の DICOM インスタンスをインポートすると、DICOM インスタンスごとにメッセージが生成されます。

Pub/Sub メッセージを pull するために必要な Identity and Access Management 権限については、Pub/Sub のアクセス制御をご覧ください。
REST

projects.subscriptions.pull メソッドを使用します。次のサンプルでは、?maxMessages=10 クエリパラメータを使用して、リクエストで返されるメッセージの最大数を指定しています。この値はユースケースに合わせて調整します。

リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: Google Cloud プロジェクトの ID
- PUBSUB_SUBSCRIPTION_ID: DICOM ストアに構成された Pub/Sub トピックにアタッチされるサブスクリプションの ID
リクエストを送信するには、次のいずれかのオプションを選択します。
curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=10"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=10" | Select-Object -Expand Content

API Explorer

メソッドリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。必須フィールドを入力して、[Execute] をクリックします。
次のような JSON レスポンスが返されます。
レスポンス

{ "receivedMessages": [ { "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR", "ackStatus": "SUCCESS", "message": { "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==", "messageId": "7586159156345265", "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" } } ] }
gcloud

gcloud pubsub subscriptions pullコマンドを実行する

サンプルでは、次の Google Cloud CLI フラグを使用します。
- --limit=10: 最大 10 件のメッセージを返します。この値はユースケースに合わせて調整します。
- --format=json: 出力を JSON としてレンダリングします。
- --auto-ack: pull されたすべてのメッセージに自動的に確認応答を行います。
後述のコマンドデータを使用する前に、次のように置き換えます。
- PROJECT_ID: Google Cloud プロジェクトの ID
- PUBSUB_SUBSCRIPTION_ID: DICOM ストアに構成された Pub/Sub トピックにアタッチされるサブスクリプションの ID
次のコマンドを実行します。
Linux、macOS、Cloud Shell

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud pubsub subscriptions pull \ projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID \ --limit=10 \ --auto-ack \ --format=json
Windows（PowerShell）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud pubsub subscriptions pull ` projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ` --limit=10 ` --auto-ack ` --format=json
Windows（cmd.exe）

注: 認証とプロジェクトを使用して Google Cloud CLI を初期化するには、gcloud init、gcloud auth login、または gcloud config set project のいずれかを実行します。

gcloud pubsub subscriptions pull ^ projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ^ --limit=10 ^ --auto-ack ^ --format=json
次のようなレスポンスが返されます。
[ { "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR", "ackStatus": "SUCCESS", "message": { "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==", "messageId": "7586159156345265", "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ" } } ]

Cloud Healthcare API と Pub/Sub メッセージストレージポリシー

Cloud Healthcare API データと Pub/Sub メッセージ内の関連データが同じリージョンに存在するようにするには、Pub/Sub メッセージストレージポリシーを設定する必要があります。

データが同じリージョンに保持されるようにするには、データストアに構成された Pub/Sub トピックにメッセージストレージポリシーを明示的に設定する必要があります。たとえば、Cloud Healthcare API データセットと FHIR ストアが us-central1 にある場合、メッセージストレージポリシーで us-central1 リージョンのみに許可する必要があります。

メッセージストレージポリシーを構成するには、メッセージストアポリシーの構成をご覧ください。

不明な Pub/Sub メッセージのトラブルシューティング

通知を Pub/Sub に公開できない場合は、Cloud Logging にエラーが記録されます。詳細については、Cloud Logging でのエラーログの表示をご覧ください。

エラー生成率が制限を超えると、この制限を超えたエラーは Cloud Logging に送信されません。

DICOM Pub/Sub 通知を構成する

準備

Pub/Sub パブリッシャー権限を追加する

通知の形式と内容

通知を構成して表示する

DICOM ストアを構成する

このタスクに必要な権限

REST

curl

PowerShell

API Explorer

レスポンス

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

レスポンス

DICOM インスタンスを保存またはインポートして、Pub/Sub 通知を表示する

このタスクに必要な権限

REST

curl

PowerShell

API Explorer

レスポンス

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

Cloud Healthcare API と Pub/Sub メッセージ ストレージ ポリシー

不明な Pub/Sub メッセージのトラブルシューティング

次のステップ

Cloud Healthcare API と Pub/Sub メッセージストレージポリシー