DICOM Pub/Sub 通知を構成する

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

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

次の図は、Pub/Sub 通知が生成され、公開される方法を示しています。

DICOM Pub/Sub 通知。

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

図 1 に次のステップを示します。

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

準備

  1. トピックを作成します
  2. pull サブスクリプションを作成する

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 メッセージに含まれるフィールドの詳細については、ReceivedMessagePubsubMessage をご覧ください。

通知の構成と表示

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

DICOM ストアの構成

以下のサンプルは、新しい 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

リクエスト本文を 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

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

@'
{
  "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 リソースでフィールドを構成した場合は、そのフィールドもレスポンスに表示されます。

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 通知の表示

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

  1. DICOM インスタンスを保存またはインポートします。このリクエストにより、Cloud Healthcare API で構成済みの Pub/Sub トピックにメッセージが公開されます。

  2. メッセージを 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

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

    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

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

    $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 レスポンスが返されます。

    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

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

    Windows(PowerShell)

    gcloud pubsub subscriptions pull `
        projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID `
        --limit=10 `
        --auto-ack `
        --format=json

    Windows(cmd.exe)

    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 に送信されません。

次のステップ