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）

以下のサンプルは、新しい 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 インスタンスを保存またはインポートします。このリクエストにより、Cloud Healthcare API で構成済みの Pub/Sub トピックにメッセージが公開されます。
メッセージを pull します。1 つのリクエストで複数の 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 メッセージストレージポリシー