FHIR Pub/Sub の通知

このページでは、FHIR ストアで臨床イベントが発生したときに Pub/Sub を使用して通知を受け取る方法について説明します。

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

概要

FHIR ストア内で FHIR リソースが作成、更新、パッチ適用、または削除されたときに、Pub/Sub 通知を受け取ることができます。FHIR リソースが Cloud Storage からインポートされたときに、Cloud Healthcare API は通知を送信しません。

通知を受け取るには、Pub/Sub トピックとサブスクリプションを作成してから、トピックに通知を送信するように FHIR ストアを構成する必要があります。

次の図に、fhir.create メソッドを使用して FHIR ストアに FHIR リソースを作成する際の、Pub/Sub 通知を作成、配信する方法を示しています。FHIR リソースが更新、パッチ適用、または削除されても、手順は同じです。

FHIR Pub/Sub の通知。

図 1. FHIR ストア内の変更に対する Pub/Sub 通知の使用。

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

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

通知構成

FHIR ストア上の FhirNotificationConfig オブジェクトで、Pub/Sub 通知とその動作を構成できます。各 FHIR ストアには 1 つの FhirNotificationConfig を構成できます。

次の表に、FhirNotificationConfig オブジェクトのフィールドを示します。

フィールド 説明
pubsubTopic FHIR ストアにアタッチする Pub/Sub トピック。通知は、指定されたトピックに送信されます。 projects/my-project/topics/my-topic
sendFullResource 作成、更新、またはパッチ適用された FHIR リソースのすべての内容を通知に含めるかどうか。このフィールドを指定しても、FHIR リソースが削除されたときに送信される通知には影響がありません。削除したリソースのすべての内容を含めるには、sendPreviousResourceOnDeletetrue に設定します。 true
sendPreviousResourceOnDelete 削除された FHIR リソースのすべての内容を通知に含めるかどうか。このフィールドを指定しても、FHIR リソースが作成、更新、またはパッチ適用されたときに送信される通知には影響がありません。 true

通知の形式と内容

各 Pub/Sub 通知には、臨床イベントに関する情報を保持する message オブジェクトが含まれています。message オブジェクトは次のようになります。

{
  "message": {
    "attributes": {
      "action": "ACTION",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "PAYLOAD_TYPE",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

各 Pub/Sub メッセージに含まれる追加のフィールドについては、ReceivedMessagePubsubMessage をご覧ください。

次の表に、attributes オブジェクトの各フィールドの説明を示します。

属性 説明
action FHIR リソースで発生したアクション。有効な値は次のとおりです。
  • CreateResource
  • PatchResource
  • UpdateResource
  • DeleteResource
CreateResource
resourceType 変更された FHIR リソースのタイプ。有効な値は、Cloud Healthcare API でサポートされているあらゆる FHIR リソースタイプです。 Patient
payloadType メッセージのペイロード タイプで、NameOnly または FullResource のいずれか。 FullResource
storeName アクションが発生した FHIR ストアの完全なリソース名。 projects/my-project/locations/us/datasets/my-dataset/fhirStores/my-fhir-store
lastUpdatedTime FHIR リソースが変更された直近の時刻のタイムスタンプ。タイムスタンプには RFC 1123 の形式を使用します。 Mon, 01 Jan 2020 00:00:00 UTC
versionId アクションが行われた FHIR リソースの最新バージョンの ID。バージョン ID の詳細については、FHIR リソース バージョンの一覧表示をご覧ください。 MTY4MzA2MDQzOTI5NjIxMDAwMA

次の表に、message オブジェクトの残りのフィールドを示します。

フィールド 説明
data FhirNotificationConfig で指定された値による、FHIR リソース名と FHIR リソース コンテンツのいずれかの Base 64 エンコード文字列。
messageId Pub/Sub メッセージの識別子。
publishTime Pub/Sub サーバーがメッセージを公開した時刻。

通知に含める情報を指定する

通知形式とコンテンツで説明されているとおりの Pub/Sub 通知で、フィールドの標準セットが含まれています。各通知には、FHIR リソース全体と名前のみのいずれかを含めることができます。リソース名には、リソースへのフルパスとリソース ID が次の形式で含まれています。

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID

FHIR リソース情報は、Base 64 エンコード文字列として data フィールドに格納されます。

FHIR リソースのすべての内容を含めることで、リソースの詳細について Pub/Sub と Cloud Healthcare API を個別にクエリする必要がなくなります。

FHIR リソース名を取得する

リソースを作成、更新、またはパッチ適用するときに FHIR リソースの名前を含めるだけにするには、sendFullResourcefalse に設定します。FHIR リソースを削除するときに名前を含めるだけにするには、sendPreviousResourceOnDeletefalse に設定します。

通知を表示すると、message オブジェクトは次のようになります。

{
  "message": {
    "attributes": {
      "action": "{CreateResource|PatchResource|UpdateResource|DeleteResource}",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "NameOnly",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_NAME",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

通知では、次の点にご注意ください。

  • payloadType フィールドは NameOnly に設定され、リクエストに関する次のことを示します。

    • 作成、更新、パッチ適用のオペレーションの場合、sendFullResourcefalse に設定されます。
    • 削除オペレーションでは、sendPreviousResourceOnDeletefalse に設定されます。
  • data フィールドには FHIR リソース名のみが含まれます。名前は Base64 でエンコードされた文字列としてエンコードされます。

FHIR リソースの内容を作成、更新、パッチ適用する

リソースを作成、更新、またはパッチ適用するときに FHIR リソースのすべての内容を含めるには、sendFullResourcetrue に設定します。

FHIR リソースを削除した場合、この動作は適用されません。FHIR リソースを削除し、sendFullResourcetrue に設定されるが、sendPreviousResourceOnDeletefalse に設定される場合、通知は FHIR リソース名を受け取るだけの場合と同じです。FHIR リソースが削除されたときに FHIR リソースの内容を含めるには、削除された FHIR リソースの内容を取得するをご覧ください。

通知を表示すると、message オブジェクトは次のようになります。

{
  "message": {
    "attributes": {
      "action": "{CreateResource|PatchResource|UpdateResource}",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "FullResource",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_CONTENTS",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

通知では、次の点にご注意ください。

  • sendFullResourcetrue に設定されていることを示すように、payloadTypeFullResource に設定されています。FHIR リソースのすべての内容は、Base 64 でエンコードされた文字列として data フィールドに含まれます。
  • data フィールドは、FHIR リソース コンテンツを Base 64 でエンコードされた文字列として含みます。

削除された FHIR リソース コンテンツを取得する

FHIR リソースを削除するときに、そのすべてのコンテンツを含めるには、sendPreviousResourceOnDeletetrue に設定します。

通知を表示すると、message オブジェクトは次のようになります。

{
  "message": {
    "attributes": {
      "action": "DeleteResource",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "payloadType": "FullResource",
      "resourceType": "FHIR_RESOURCE_TYPE",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "versionId": "VERSION_ID"
    },
    "data": "BASE64_ENCODED_FHIR_RESOURCE_CONTENTS",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

次のフィールドの値をメモします。

  • たとえ sendFullResourcefalse に設定されていても、payloadTypeFullResource に設定されています。

    FHIR リソースのすべての内容は、Base 64 でエンコードされた文字列として data フィールドに含まれます。

  • data フィールドは、リソースが削除される前に、FHIR リソースの内容を Base64 でエンコードされた文字列として含みます。

FHIR 通知を構成して表示する

次の例は、FHIR ストアに FHIR リソースが作成されたときに生成された Pub/Sub 通知を表示する方法を示しています。

準備

Pub/Sub 通知を構成して使用する前に、次のセクションを完了してください。

Pub/Sub 割り当ての確認

Pub/Sub の割り当てと上限について把握してください。割り当ての確認方法、割り当ての増加をリクエストする方法、割り当てがなくなったらどうなるかについては、割り当ての操作をご覧ください。

Pub/Sub API を有効にする

Google Cloud コンソールで、Pub/Sub API を有効にします。

API の有効化

Pub/Sub 権限の構成

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

Pub/Sub トピックの作成

トピックを作成するには、トピックを作成するをご覧ください。

個々のデータストアに独自の Pub/Sub トピックを含めるか、複数のデータストアで同じトピックを共有できます。

Pub/Sub トピックを指定する際は、次の形式を使用します。

projects/PROJECT_ID/topics/TOPIC_NAME

PROJECT_ID は Google Cloud プロジェクト ID、TOPIC_NAME は Pub/Sub トピックの名前です。

Pub/Sub サブスクリプションの作成

トピックにパブリッシュされたメッセージを受信するには、Pub/Sub サブスクリプションを作成する必要があります。Pub/Sub サブスクリプションは、各 Pub/Sub トピックに少なくとも 1 つ必要です。サブスクリプションにより、トピックとサブスクライバー アプリケーションが関連付けられます。このアプリケーションがそのトピックに公開されたメッセージを受信して処理します。

サブスクリプションを作成して Pub/Sub トピックにアタッチするには、サブスクリプションを作成するをご覧ください。

FHIR ストアを作成または編集する

構成された FhirNotificationConfig オブジェクトで FHIR ストアを作成または編集します。

以下のサンプルは、既存の FHIR ストアを編集する方法を示しています。sendFullResource フィールドと sendPreviousResourceOnDelete フィールドは true に設定されています。つまり、リソースが作成、更新、パッチ適用、または削除されたときに、完全な FHIR リソース コンテンツが通知に含まれます。

REST

FHIR ストアを編集するには、projects.locations.datasets.fhirStores.patch メソッドを使用します。

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

  • PROJECT_ID: Google Cloud プロジェクトの ID
  • LOCATION: データセットの場所
  • DATASET_ID: FHIR ストアの親データセット
  • FHIR_STORE_ID: FHIR ストア ID
  • PUBSUB_TOPIC_ID: Pub/Sub トピック ID

JSON 本文のリクエスト:

{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": true
    }
  ]
}

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

curl

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

cat > request.json << 'EOF'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": 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/fhirStores/FHIR_STORE_ID?updateMask=notificationConfigs"

PowerShell

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

@'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
      "sendFullResource": true,
      "sendPreviousResourceOnDelete": 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/fhirStores/FHIR_STORE_ID?updateMask=notificationConfigs" | Select-Object -Expand Content

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

FHIR リソースの作成

FHIR ストアに FHIR リソースを作成します。このリクエストにより、Cloud Healthcare API で構成済みの Pub/Sub トピックにメッセージが公開されます。

Pub/Sub 通知を表示する

Pub/Sub トピックに公開されたメッセージを表示します。FHIR ストアに患者リソースが作成された際に、次のメッセージが生成されました。

サンプル出力では、FHIR リソースのコンテンツは data フィールドの Base64 でエンコードされた文字列の中にあります。コンテンツを取得するには、base64 エンコード値をデコードする必要があります。ほとんどのプラットフォームとオペレーティング システムには、Base64 テキストをデコードするツールがあります。

REST

Pub/Sub トピックにパブリッシュされたメッセージを表示するには、projects.subscriptions.pull メソッドを使用します。次のサンプルでは、?maxMessages=10 クエリ パラメータを使用して、リクエストで返されるメッセージの最大数を指定します。値は必要に応じて調整できます。

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

  • PROJECT_ID: Google Cloud プロジェクトの ID
  • PUBSUB_SUBSCRIPTION_ID: FHIR ストアに構成された 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

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

gcloud

Pub/Sub トピックにパブリッシュされたメッセージを表示するには、gcloud pubsub subscriptions pull コマンドを実行します。

サンプルでは、次の Google Cloud CLI フラグを使用します。

  • --format=json: 出力を JSON としてレンダリングします。
  • --auto-ack: pull されたすべてのメッセージに自動的に確認応答を行います。

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

  • PROJECT_ID: Google Cloud プロジェクトの ID
  • PUBSUB_SUBSCRIPTION_ID: FHIR ストアに構成された Pub/Sub トピックにアタッチされたサブスクリプションの ID

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

Linux、macOS、Cloud Shell

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

Windows(PowerShell)

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

Windows(cmd.exe)

gcloud pubsub subscriptions pull ^
    projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ^
    --auto-ack ^
    --format=json

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

[
  {
    "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
    "ackStatus": "SUCCESS",
    "message": {
      "attributes": {
        "action": "CreateResource",
        "lastUpdatedTime": "Mon, 01 Jan 2020 00:00:00 UTC",
        "payloadType": "FullResource",
        "resourceType": "Patient",
        "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
        "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA"
      },
      "data": "wogICJiaXJ0aERhdGUiOiAiMTk3MC0wMS0wMSIsCiAgImdlbmRlciI6ICJmZW1hbGUiLAogICJpZCI6ICIyYmMwODg4Yi00MGRmLTQwYzctOWRhYi0wMzc4YTFiZWE0MGIiLAogICJtZXRhIjogewogICAgImxhc3RVcGRhdGVkIjogIjIwMjMtMDUtMDJUMjA6NDc6MTkuMjk2MjEwKzAwOjAwIiwKICAgICJ2ZXJzaW9uSWQiOiAiTVRZNE16QTJNRFF6T1RJNU5qSXhNREF3TUEiCiAgfSwKICAibmFtZSI6IFsKICAgIHsKICAgICAgImZhbWlseSI6ICJTbWl0aCIsCiAgICAgICJnaXZlbiI6IFsKICAgICAgICAiRGFyY3kiCiAgICAgIF0sCiAgICAgICJ1c2UiOiAib2ZmaWNpYWwiCiAgICB9CiAgXSwKICAicmVzb3VyY2VUeXBlIjogIlBhdGllbnQiCn0=",
      "messageId": "7586159156345265",
      "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
    }
  }
]

FHIR リソースが大きすぎるか、トラフィックが多い場合の動作

FHIR リソースのサイズが大きすぎる、または Cloud Healthcare API サーバーでトラフィックが多い場合は、attributes フィールドに完全なリソースのコンテンツではなくリソース名のみが含まれる場合があります。この挙動は、たとえ sendFullResourcesendPreviousResourceOnDeletetrue に設定されている場合でも発生します。

Pub/Sub 通知が完全な FHIR リソースを含んでいるかどうかを確認するには、通知の表示でレスポンスの payloadType フィールドを確認します。payloadTypenameOnly に設定されている場合、attributes フィールドには FHIR リソースデータが完全には入力されていません。次に、FHIR リソースのコンテンツは、Pub/Sub メッセージではなく FHIR ストアから手動で取得する必要があります。

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

NotificationConfig 構成を使用して FHIR 通知を表示する(非推奨)

FhirStore リソースには、Pub/Sub トピックを指定できる NotificationConfig オブジェクトが含まれています。 FHIR リソースへの変更は、常に Pub/Sub メッセージの data フィールドに次の ID を含みます。

projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/RESOURCE_ID

次の Key-Value ペアのセットは、常にメッセージの attributes フィールドに含まれます。

属性名 指定できる値 説明
action
  • CreateResource
  • PatchResource
  • UpdateResource
  • DeleteResource
CreateResource 発生したイベントのタイプ。
resourceType FHIR リソースのタイプ Patient 変更されたリソースのタイプ。

次のステップ