当 Cloud Healthcare API 数据存储区中发生临床事件时,您可以使用 Pub/Sub 接收通知。这些通知会在发生以下情况时通知您:
- DICOM 实例使用
dicomStores.dicomWeb.studies.storeInstances
存储在 DICOM 存储区中时。但是,当从 Cloud Storage 导入 DICOM 资源时,系统不会发送通知。 - 在 FHIR 存储区中创建、更新或删除 FHIR 资源时。但是,当从 Cloud Storage 导入 FHIR 资源时,系统不会发送通知。
- 首次提取或在 HL7v2 存储区中创建 HL7v2 消息。重复消息不会触发通知。
当发生其中一个事件时,Cloud Healthcare API 会向名为“主题”的指定 Pub/Sub 资源发布消息。然后,订阅了该主题的应用可能收到该消息。
对于 DICOM 和 HL7v2,这些消息不包含任何个人信息。仅包含以下内容:
- 生成了消息的项目
- 消息 ID
- HL7v2 消息中的 HL7v2 消息类型
FHIR Pub/Sub 消息可以包含个人信息。如需了解详情,请参阅包含 FHIR 资源数据的 FHIR 通知。
如需大致了解如何将 Pub/Sub 通知与 Cloud Healthcare API 配合使用,请参阅 Pub/Sub 通知。
前提条件
要使用此功能,请先完成以下部分:
查看 Pub/Sub 配额
在配置 Pub/Sub 通知之前,请先熟悉 Pub/Sub 配额和限制。如需了解如何查看配额、申请更多配额以及配额用完后会出现什么情况,请参阅使用配额。
启用 Pub/Sub API
如需启用 Pub/Sub API,请点击以下按钮:
配置 Pub/Sub 权限
要允许将消息从 Cloud Healthcare API 发布到 Pub/Sub,您必须将 pubsub.publisher
角色添加到项目的 Cloud Healthcare Service Agent 服务帐号。如需查看添加所需角色的步骤,请参阅 DICOM、FHIR 和 HL7v2 存储区 Pub/Sub 权限。
创建 Pub/Sub 主题
对于要接收通知的每个数据存储区,您必须配置 Pub/Sub 主题。单个数据存储区可以有自己的 Pub/Sub 主题,或者多个数据存储区可以共享同一主题。您可以使用 Google Cloud Console 或 Google Cloud CLI 创建主题。
在创建主题或参照数据存储区配置中的主题时,您需要使用以下格式的限定 URI:
projects/PROJECT_ID/topics/TOPIC_NAME
其中 PROJECT_ID 是您的 Google Cloud 项目 ID,TOPIC_NAME 是主题的名称。
如需创建主题,请完成以下步骤:
控制台
转到控制台中的 Pub/Sub 主题页面。
点击创建主题。
在主题名称中输入 URI:
projects/PROJECT_ID/topics/TOPIC_NAME
其中 PROJECT_ID 是您的 Google Cloud 项目 ID。
点击创建。
gcloud
要创建主题,请运行 gcloud pubsub topics create
命令:
gcloud pubsub topics create projects/PROJECT_ID/topics/TOPIC_NAME
如果请求成功,命令将返回以下输出:
Created topic [projects/PROJECT_ID/topics/TOPIC_NAME].
创建 Pub/Sub 订阅
如需接收发布到主题的消息,您需要创建 Pub/Sub 订阅。每个 Pub/Sub 主题至少应有一个 Pub/Sub 订阅。
订阅将主题与负责接收和处理发布到该主题的消息的订阅者应用关联起来。
如需创建订阅,请完成以下步骤。
控制台
转到控制台中的 Pub/Sub 主题页面。
点击项目的主题。
点击创建订阅。
输入订阅名称:
projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME
将传送类型设置保留为拉取。
点击创建。
gcloud
要创建主题,请运行 gcloud pubsub subscriptions create
命令:
gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME
如果请求成功,命令将返回以下输出:
Created subscription [projects/PROJECT_ID/subscriptions/TOPIC_NAME].
查看 DICOM 通知
DicomStore
资源包含一个 notificationConfig
对象,您可以在其中指定 Pub/Sub 主题。(可选)notificationConfig
对象还可让您指定是否应在批量导入期间发送 Pub/Sub 通知。此字段仅在 v1beta1 版本中可用。
当您将新的 DICOM 实例存储到 DICOM 存储区中时,Cloud Healthcare API 会向 DICOM 存储区的 Pub/Sub 主题发布消息。
要查看存储的 DICOM 实例的通知,请完成以下步骤:
- 创建或修改 DICOM 存储区,然后使用 Pub/Sub 主题进行配置。(可选)指明是否应在批量导入期间发送 Pub/Sub 通知(此功能仅在 v1beta1 API 中可用)。
- 将所需的
pubsub.publisher
角色添加到项目的服务帐号中。 - 在 DICOM 存储区中存储实例。这会触发 Cloud Healthcare API 向配置的 Pub/Sub 主题发布消息。
运行
gcloud pubsub subscriptions pull
命令以查看发布到 Pub/Sub 主题的消息:gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
该命令返回关于存储的 DICOM 实例的以下输出:
┌----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------┐ | DATA | MESSAGE_ID | ATTRIBUTES | ├---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|------------| | projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID | 123456789012345 | | └----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------┘
查看 FHIR 通知
配置 FHIR Pub/Sub 通知时,可以使用以下选项:
不含 FHIR 资源数据的 FHIR 通知(所有 API 版本)
Pub/Sub 通知包含发生操作的 FHIR 资源类型和一些其他信息。在
NotificationConfig
对象中配置。包含 FHIR 资源数据的 FHIR 通知(仅限 v1alpha2 和 v1beta1)
Pub/Sub 通知包含操作发生的 FHIR 资源的类型、操作是什么以及操作发生的时间等信息。您还可以在 Pub/Sub 通知中指定是否显示 FHIR 资源的内容。在
FhirNotificationConfig
对象中配置。
下表显示了创建患者 FHIR 资源后每个选项的 Pub/Sub 消息中包含的信息:
NotificationConfig (不含 FHIR 资源数据) |
---|
|
FhirNotificationConfig (包含 FHIR 资源数据) |
|
不包含 FHIR 资源数据的 FHIR 通知
FhirStore
资源包含一个 NotificationConfig
对象,您可以在其中指定 Pub/Sub 主题。
在 FHIR 存储区中创建、更新或删除 FHIR 资源时,Cloud Healthcare API 会向 FHIR 存储区的 Pub/Sub 主题发布消息。
要查看已创建的 FHIR 资源的通知,请完成以下步骤:
- 创建或修改 FHIR 存储区,然后使用 Pub/Sub 主题进行配置。
- 将所需的
pubsub.publisher
角色添加到项目的服务帐号中。 - 在 FHIR 存储区中创建 FHIR 资源。这会触发 Cloud Healthcare API 向配置的 Pub/Sub 主题发布消息。
运行
gcloud pubsub subscriptions pull
命令以查看发布到 Pub/Sub 主题的消息:gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
该命令返回有关已创建的 FHIR 资源的以下输出:
┌----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------┐ | DATA | MESSAGE_ID | ATTRIBUTES | ├----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------| | projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/resources/Patient/PATIENT_ID | 123456789012345 | action=CreateResource | | | | resourceType=Patient | └----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------┘
包含 FHIR 资源数据的 FHIR 通知
在 v1beta1 版本的 Cloud Healthcare API 中,FhirStore
资源包含一个 FhirNotificationConfig
对象,您可以在该对象中指定以下信息:
- 要附加到 FHIR 存储区的 Pub/Sub 主题
- 是否将已更改的 FHIR 资源的全部内容发送到 Pub/Sub 主题
通过发送 FHIR 资源的完整内容,您可以直接从 Pub/Sub 消息中检索有关 FHIR 资源的所有信息。这样就不必查询 Pub/Sub 消息,然后单独查询 Cloud Healthcare API 以获取 FHIR 资源的详细信息。
FHIR Pub/Sub 消息的 attributes
字段中包含以下信息:
- FHIR 资源类型 (
resourceType
) - 引发消息的操作(
action
) - 消息的载荷类型 (
payloadType
),可以是nameOnly
或fullResource
- 执行操作的 FHIR 存储区的完整资源名称 (
storeName
) - 使用 RCF1123 格式修改 FHIR 资源的最新时间 (
lastUpdatedTime
) 的时间戳
如需查看有关已创建 FHIR 资源的通知以及 FHIR 资源的完整内容,请完成以下步骤:
创建或修改 FHIR 存储区,并使用
notificationConfigs
对象对其进行配置。在以下示例中,您将创建一个 FHIR 存储区。在使用任何请求数据之前,请先进行以下替换:
- 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 } ], "version": "R4" }
如需发送请求,请选择以下方式之一:
curl
- 将请求正文保存在名为
request.json
的文件中。复制以下命令,并在终端中运行它以创建此文件。cat > request.json << 'EOF' { "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true } ], "version": "R4" } EOF
- 在终端运行以下命令。它引用您刚刚创建的
request.json
文件。curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/fhir+json" \
-d @request.json \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/?fhirStoreId=FHIR_STORE_ID"
PowerShell
- 将请求正文保存在名为
request.json
的文件中。复制以下命令,并在终端中运行它以创建此文件。@' { "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true } ], "version": "R4" } '@ | Out-File -FilePath request.json -Encoding utf8
- 在终端运行以下命令。它引用您刚刚创建的
request.json
文件。$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/fhir+json" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/?fhirStoreId=FHIR_STORE_ID" | Select-Object -Expand Content
您应该会收到类似以下内容的 JSON 响应:
在 FHIR 存储区中创建 FHIR 资源。这会触发 Cloud Healthcare API 向配置的 Pub/Sub 主题发布消息。
查看发布到 Pub/Sub 主题的消息。在 FHIR 存储区中创建患者资源时会生成以下消息:
REST 和命令行
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID
- PUBSUB_SUBSCRIPTION_ID:附加到 FHIR 存储区中配置的 Pub/Sub 主题的订阅的 ID
如需发送请求,请选择以下方式之一:
curl
执行以下命令:
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://pubsub.googleapis.com/v1beta1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=1"PowerShell
执行以下命令:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://pubsub.googleapis.com/v1beta1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=1" | Select-Object -Expand Content您应该会收到类似以下内容的 JSON 响应:
gcloud
在使用下面的命令数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID
- PUBSUB_SUBSCRIPTION_ID:附加到 FHIR 存储区中配置的 Pub/Sub 主题的订阅的 ID
执行以下命令:
Linux、macOS 或 Cloud Shell
gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
Windows (PowerShell)
gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
Windows (cmd.exe)
gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
您应该会收到类似如下所示的响应:
┌────────────────────────────────────────────────────────┬──────────────────┬──────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────┬──────────────────┐ │ DATA │ MESSAGE_ID │ ORDERING_KEY │ ATTRIBUTES │ DELIVERY_ATTEMPT │ ├────────────────────────────────────────────────────────┼──────────────────┼──────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┤ │ { │ 4300088465623331 │ │ action=CreateResource │ │ │ "birthDate": "1970-01-01", │ │ │ lastUpdatedTime=LAST_UPDATED_TIME │ │ │ "gender": "female", │ │ │ payloadType=FullResource │ │ │ "id": "3fbfac80-6357-44ad-b886-80f92a64bf7b", │ │ │ resourceType=Patient │ │ │ "meta": { │ │ │ storeName=projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID │ │ │ "lastUpdated": "LAST_UPDATED", │ │ │ │ │ │ "versionId": "MTY0ODc1NTk3MDMzODU3MzAwMA" │ │ │ │ │ │ }, │ │ │ │ │ │ "name": [ │ │ │ │ │ │ { │ │ │ │ │ │ "family": "Smith", │ │ │ │ │ │ "given": [ │ │ │ │ │ │ "Darcy" │ │ │ │ │ │ ], │ │ │ │ │ │ "use": "official" │ │ │ │ │ │ } │ │ │ │ │ │ ], │ │ │ │ │ │ "resourceType": "Patient" │ │ │ │ │ │ } │ │ │ │ │ └────────────────────────────────────────────────────────┴──────────────────┴──────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────────┘
FHIR 资源过大或流量较高的行为
在以下情况下,即使 sendFullResource
设置为 true
,attributes
字段也可能仅包含资源名称(格式为 projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE/FHIR_RESOURCE_ID
):
- FHIR 资源过大
- Cloud Healthcare API 服务器流量过高
请务必查看查看 Pub/Sub 通知的响应中的 payloadType
字段。如果 payloadType
设置为 nameOnly
,则 attributes
字段未完全填充 FHIR 资源数据,您必须从 FHIR 存储区(而非 Pub/Sub 消息)手动获取 FHIR 资源的内容。
查看 HL7v2 通知
Hl7V2Store
资源包含一个数组 notificationConfigs
,您可以在其中指定 Pub/Sub 主题和过滤条件。
在 HL7v2 存储区中提取或创建 HL7v2 消息时,Cloud Healthcare API 会向其中的过滤条件与 HL7v2 消息匹配的 Pub/Sub 主题发布一条消息。
如需查看提取的 HL7v2 消息的通知,请完成以下步骤:
- 创建或修改 HL7v2 存储区,然后使用 Pub/Sub 主题进行配置。
- 将所需的
pubsub.publisher
角色添加到项目的服务帐号中。 - 提取 HL7v2 消息到 HL7v2 存储区中。这会触发 Cloud Healthcare API 向配置的 Pub/Sub 主题发布消息。
如需查看发布到 Pub/Sub 主题的消息,请运行
gcloud pubsub subscriptions pull
命令:gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
该命令返回有关提取的 HL7v2 消息的以下输出:
┌--------------------------------------------------------------------------------------------------------------------|-----------------|---------------┐ | DATA | MESSAGE_ID | ATTRIBUTES | ├--------------------------------------------------------------------------------------------------------------------|-----------------|---------------| | projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages/HL7V2_MESSAGE_ID | 123456789012345 | msgType=TYPE | └--------------------------------------------------------------------------------------------------------------------|-----------------|---------------┘
Cloud Healthcare API 和 Pub/Sub 消息存储政策
为确保您的 Cloud Healthcare API 数据和 Pub/Sub 消息中的关联数据位于同一区域,您必须设置 Pub/Sub 消息存储政策。
您必须为 FHIR 存储区中配置的 Pub/Sub 主题明确设置消息存储政策,以确保数据位于同一区域。例如,如果您的 Cloud Healthcare API 数据集和 FHIR 存储区位于 us-central1
中,则消息存储政策必须仅允许 us-central1
区域。
要配置消息存储政策,请参阅配置消息存储政策。
排查遗漏的 Pub/Sub 消息问题
如果无法将通知发布到 Pub/Sub,则 Cloud Logging 会记录错误。如需了解详情,请参阅在 Cloud Logging 中查看错误日志。
如果错误生成率超过限制,则超出此限制的错误不会提交到 Cloud Logging。
后续步骤
如需了解如何配置 Pub/Sub 主题,请参阅: