このページでは、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 リソースが更新、パッチ適用、または削除されても、手順は同じです。
図 1. FHIR ストア内の変更に対する Pub/Sub 通知の使用。
図 1 に次のステップを示します。
- 呼び出し元が、FHIR リソースを作成する
fhirStores.fhir.create
リクエストを行います。 - FHIR ストアはリクエストを受信し、Pub/Sub メッセージを作成して、FHIR ストアに構成された Pub/Sub トピックに送信します。
- Pub/Sub は、トピックにアタッチされたサブスクリプションにメッセージを転送します。
- サブスクライバーは、サブスクリプションから Pub/Sub メッセージの形式で通知を受け取ります。並列処理を強化するために、各サブスクリプションに 1 つ以上のサブスクライバーを含めることが可能です。
通知構成
FHIR ストア上の FhirNotificationConfig
オブジェクトで、Pub/Sub 通知とその動作を構成できます。各 FHIR ストアには 1 つの FhirNotificationConfig
を構成できます。
次の表に、FhirNotificationConfig
オブジェクトのフィールドを示します。
フィールド | 説明 | 例 |
---|---|---|
pubsubTopic |
FHIR ストアにアタッチする Pub/Sub トピック。通知は、指定されたトピックに送信されます。 | projects/my-project/topics/my-topic |
sendFullResource |
作成、更新、またはパッチ適用された FHIR リソースのすべての内容を通知に含めるかどうか。このフィールドを指定しても、FHIR リソースが削除されたときに送信される通知には影響がありません。削除したリソースのすべての内容を含めるには、sendPreviousResourceOnDelete を true に設定します。 |
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 メッセージに含まれる追加のフィールドについては、ReceivedMessage
と PubsubMessage
をご覧ください。
次の表に、attributes
オブジェクトの各フィールドの説明を示します。
属性 | 説明 | 例 |
---|---|---|
action |
FHIR リソースで発生したアクション。有効な値は次のとおりです。
|
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 リソースの名前を含めるだけにするには、sendFullResource
を false
に設定します。FHIR リソースを削除するときに名前を含めるだけにするには、sendPreviousResourceOnDelete
を false
に設定します。
通知を表示すると、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
に設定され、リクエストに関する次のことを示します。- 作成、更新、パッチ適用のオペレーションの場合、
sendFullResource
がfalse
に設定されます。 - 削除オペレーションでは、
sendPreviousResourceOnDelete
がfalse
に設定されます。
- 作成、更新、パッチ適用のオペレーションの場合、
data
フィールドには FHIR リソース名のみが含まれます。名前は Base64 でエンコードされた文字列としてエンコードされます。
FHIR リソースの内容を作成、更新、パッチ適用する
リソースを作成、更新、またはパッチ適用するときに FHIR リソースのすべての内容を含めるには、sendFullResource
を true
に設定します。
FHIR リソースを削除した場合、この動作は適用されません。FHIR リソースを削除し、sendFullResource
が true
に設定されるが、sendPreviousResourceOnDelete
が false
に設定される場合、通知は 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" } }
通知では、次の点にご注意ください。
sendFullResource
がtrue
に設定されていることを示すように、payloadType
がFullResource
に設定されています。FHIR リソースのすべての内容は、Base 64 でエンコードされた文字列としてdata
フィールドに含まれます。data
フィールドは、FHIR リソース コンテンツを Base 64 でエンコードされた文字列として含みます。
削除された FHIR リソース コンテンツを取得する
FHIR リソースを削除するときに、そのすべてのコンテンツを含めるには、sendPreviousResourceOnDelete
を true
に設定します。
通知を表示すると、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" } }
次のフィールドの値をメモします。
たとえ
sendFullResource
がfalse
に設定されていても、payloadType
はFullResource
に設定されています。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 を有効にします。
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
フィールドに完全なリソースのコンテンツではなくリソース名のみが含まれる場合があります。この挙動は、たとえ sendFullResource
と sendPreviousResourceOnDelete
が true
に設定されている場合でも発生します。
Pub/Sub 通知が完全な FHIR リソースを含んでいるかどうかを確認するには、通知の表示でレスポンスの payloadType
フィールドを確認します。payloadType
が nameOnly
に設定されている場合、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 |
発生したイベントのタイプ。 |
resourceType |
FHIR リソースのタイプ。 | Patient |
変更されたリソースのタイプ。 |