配置 Pub/Sub 通知

当 Cloud Healthcare API 数据存储区中发生临床事件时,您可以使用 Pub/Sub 接收通知。这些通知会在发生以下情况时通知您:

当发生其中一个事件时,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,请点击以下按钮:

启用该 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 是主题的名称。

如需创建主题,请完成以下步骤:

控制台

  1. 转到控制台中的 Pub/Sub 主题页面。

    转到 Pub/Sub 主题页面

  2. 点击创建主题

  3. 在主题名称中输入 URI:

    projects/PROJECT_ID/topics/TOPIC_NAME

    其中 PROJECT_ID 是您的 Google Cloud 项目 ID。

  4. 点击创建

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 订阅。

订阅将主题与负责接收和处理发布到该主题的消息的订阅者应用关联起来。

订阅可配置为使用推送模型拉取模型

如需创建订阅,请完成以下步骤。

控制台

  1. 转到控制台中的 Pub/Sub 主题页面。

    转到 Pub/Sub 主题页面

  2. 点击项目的主题。

  3. 点击创建订阅

  4. 输入订阅名称:

    projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME

    传送类型设置保留为拉取

  5. 点击创建

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 实例的通知,请完成以下步骤:

  1. 创建修改 DICOM 存储区,然后使用 Pub/Sub 主题进行配置。(可选)指明是否应在批量导入期间发送 Pub/Sub 通知(此功能仅在 v1beta1 API 中可用)。
  2. 将所需的 pubsub.publisher 角色添加到项目的服务帐号中
  3. 在 DICOM 存储区中存储实例。这会触发 Cloud Healthcare API 向配置的 Pub/Sub 主题发布消息。
  4. 运行 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 资源后每个选项的 Pub/Sub 消息中包含的信息:

NotificationConfig(不含 FHIR 资源数据)

{
  "receivedMessages": [
    {
      "ackId": "UAYWLF1GSFE3GQhoUQ5PXiM_NSAoRRICB08CKF15MFQqQV92Dj4NGXJ9YXRtDEVTUUJWd1gIEQ1iXE5EB0nh1PDfV1dKXhACA0FVfFxfHQlrWFtzBXmgo-iEzsKGbQk9Oqme_P1tO-KSgaREZiI9XhJLLD5-PTJFQV5AEkw2B0RJUytDCypYEU4EISE-MD5FU0Q",
      "message": {
        "data": "cHJvamVjdHMvbm9lcm8taGVhbHRoY2FyZS9sb2NhdGlvbnMvdXMtY2VudHJhbDEvZGF0YXNldHMvbXlkYXRhc2V0L2ZoaXJTdG9yZXMvbm90aWZpY2F0aW9uZmhpci9maGlyL1BhdGllbnQvNmU3NDIxNTEtNGNlNi00N2UwLTk2MjUtZGUzODc5M2RkMjQ4",
        "attributes": {
          "action": "CreateResource",
          "payloadType": "NameOnly",
          "resourceType": "Patient"
        },
        "messageId": "4331462346434762",
        "publishTime": "PUBLISH_TIME"
      }
    }
  ]
}
FhirNotificationConfig(包含 FHIR 资源数据)

{
  "receivedMessages": [
    {
      "ackId": "U0RQBhYsXUZIUTcZCGhRDk9eIz81IChFGwIIFAV8fXFBWXVaVBoHUQ0ZcnxmIz9bG1AHQlZ2VVsRDXptXG3z7KW7RF9BcWlaEwELQFB9X10TDWhVWl3Euqi8lfyEQnBmK_W_7fFIf4WI7M9vZiA9XxJLLD5-PTJFQV5AEkw2B0RJUytDCypYEU4EISE-MD5F",
      "message": {
        "data": "ewogICJiaXJ0aERhdGUiOiAiMTk3MC0wMS0wMSIsCiAgImdlbmRlciI6ICJmZW1hbGUiLAogICJpZCI6ICIzZDQzMjMwMi1mZWYyLTRlYTUtYWJlNi0wNDAzYzlhMmY1NGIiLAogICJtZXRhIjogewogICAgImxhc3RVcGRhdGVkIjogIjIwMjItMDMtMzFUMTk6NTM6MzMuNzg3ODE3KzAwOjAwIiwKICAgICJ2ZXJzaW9uSWQiOiAiTVRZME9EYzFOalF4TXpjNE56Z3hOekF3TUEiCiAgfSwKICAibmFtZSI6IFsKICAgIHsKICAgICAgImZhbWlseSI6ICJTbWl0aCIsCiAgICAgICJnaXZlbiI6IFsKICAgICAgICAiRGFyY3kiCiAgICAgIF0sCiAgICAgICJ1c2UiOiAib2ZmaWNpYWwiCiAgICB9CiAgXSwKICAicmVzb3VyY2VUeXBlIjogIlBhdGllbnQiCn0=",
        "attributes": {
          "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
          "lastUpdatedTime": "LAST_UPDATED_TIME",
          "action": "CreateResource",
          "payloadType": "FullResource",
          "resourceType": "Patient"
        },
        "messageId": "4300095330680096",
        "publishTime": "PUBLISH_TIME"
      }
    }
  ]
}

不包含 FHIR 资源数据的 FHIR 通知

FhirStore 资源包含一个 NotificationConfig 对象,您可以在其中指定 Pub/Sub 主题。

在 FHIR 存储区中创建、更新或删除 FHIR 资源时,Cloud Healthcare API 会向 FHIR 存储区的 Pub/Sub 主题发布消息。

要查看已创建的 FHIR 资源的通知,请完成以下步骤:

  1. 创建修改 FHIR 存储区,然后使用 Pub/Sub 主题进行配置。
  2. 将所需的 pubsub.publisher 角色添加到项目的服务帐号中
  3. 在 FHIR 存储区中创建 FHIR 资源。这会触发 Cloud Healthcare API 向配置的 Pub/Sub 主题发布消息。
  4. 运行 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),可以是 nameOnlyfullResource
  • 执行操作的 FHIR 存储区的完整资源名称 (storeName)
  • 使用 RCF1123 格式修改 FHIR 资源的最新时间 (lastUpdatedTime) 的时间戳

如需查看有关已创建 FHIR 资源的通知以及 FHIR 资源的完整内容,请完成以下步骤:

  1. 创建修改 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

    1. 将请求正文保存在名为 request.json 的文件中。复制以下命令,并在终端中运行它以创建此文件。
      cat > request.json << 'EOF'
      {
        "notificationConfigs": [
          {
            "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
            "sendFullResource": true
          }
        ],
        "version": "R4"
      }
      EOF
    2. 在终端运行以下命令。它引用您刚刚创建的 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

    1. 将请求正文保存在名为 request.json 的文件中。复制以下命令,并在终端中运行它以创建此文件。
      @'
      {
        "notificationConfigs": [
          {
            "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID",
            "sendFullResource": true
          }
        ],
        "version": "R4"
      }
      '@  | Out-File -FilePath request.json -Encoding utf8
    2. 在终端运行以下命令。它引用您刚刚创建的 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 响应:

  2. 将所需的 pubsub.publisher 角色添加到项目的服务帐号中

  3. 在 FHIR 存储区中创建 FHIR 资源。这会触发 Cloud Healthcare API 向配置的 Pub/Sub 主题发布消息。

  4. 查看发布到 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 设置为 trueattributes 字段也可能仅包含资源名称(格式为 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 消息的通知,请完成以下步骤:

  1. 创建修改 HL7v2 存储区,然后使用 Pub/Sub 主题进行配置。
  2. 将所需的 pubsub.publisher 角色添加到项目的服务帐号中
  3. 提取 HL7v2 消息到 HL7v2 存储区中。这会触发 Cloud Healthcare API 向配置的 Pub/Sub 主题发布消息。
  4. 如需查看发布到 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 主题,请参阅: