配置 DICOM Pub/Sub 通知

本页面介绍如何使用 Pub/Sub 获取 DICOM 存储区中临床事件的通知。当新的 DICOM 实例存储在 DICOM 存储区或从 Cloud Storage 导入时，您可以接收 Pub/Sub 通知。

您可以将 Pub/Sub 通知用于多种用途，例如触发下游处理或分析新数据。例如，当有新数据可用于训练时，机器学习模型可以收到通知，并生成数据分析以改善患者护理质量。

下图显示了系统如何生成和发布 Pub/Sub 通知。

DICOM Pub/Sub 通知。

图 1. 在 DICOM 存储区中接收有关临床事件的 Pub/Sub 通知。

图 1 显示了以下步骤：

调用方会发出存储或导入 DICOM 实例的请求。
DICOM 存储区接收请求，创建 Pub/Sub 消息，并将其发送到在 DICOM 存储区上配置的 Pub/Sub 主题。
Pub/Sub 会将消息转发到附加到该主题的订阅。
订阅者通过其订阅收到消息。每个订阅可以有一个或多个订阅者（提高并行性）。

须知事项

创建一个主题。
创建拉取订阅。

添加 Pub/Sub 发布者权限

如需从 Cloud Healthcare API 将消息发布到 Pub/Sub，您必须将 pubsub.publisher 角色添加到项目的 Cloud Healthcare Service Agent 服务帐号。如需了解详情，请参阅 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 字段中的值是以下标识符，以 64 位编码的字符串形式：projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID

如需详细了解每条 Pub/Sub 消息中包含的字段，请参阅 ReceivedMessage 和 PubsubMessage。

配置和查看通知

本部分介绍如何在 DICOM 存储区上启用 Pub/Sub 通知、存储或导入 DICOM 实例以发布通知和查看通知。

配置 DICOM 存储区

执行此任务所需的权限

如需执行此任务，您必须已获得以下权限或 Identity and Access Management (IAM) 角色：

权限

healthcare.dicomStores.update

角色

Healthcare DICOM Store Administrator (roles/healthcare.dicomStoreAdmin)

以下示例展示了如何在 Cloud Storage 存储或导入新的 DICOM 实例时在 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

您应该会收到类似如下所示的响应。

如果您在 DicomStore 资源中配置了任何字段，那么这些字段也会显示在响应中。

响应

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  },
}

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 通知

执行此任务所需的权限

如需执行此任务，您必须已获得以下权限或 Identity and Access Management (IAM) 角色：

权限

healthcare.dicomStores.dicomWebWrite，用于将 DICOM 实例存储在请求的 DICOM 存储区中。
healthcare.dicomStores.import，用于将 DICOM 实例导入请求的 DICOM 存储区。

角色

Healthcare DICOM Editor (roles/healthcare.dicomEditor)

如需存储或导入 DICOM 实例并拉取生成的 Pub/Sub 消息，请完成以下步骤：

存储或导入 DICOM 实例。该请求会导致 Cloud Healthcare API 将消息发布到配置的 Pub/Sub 主题。

拉取消息。如果您在单个请求中导入多个 DICOM 实例，系统会为每个 DICOM 实例生成一条消息。

如需查看拉取 Pub/Sub 消息所需的 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 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行。

您应该收到类似以下内容的 JSON 响应：

响应

{
  "receivedMessages": [
    {
      "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
      "ackStatus": "SUCCESS",
      "message": {
        "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==",
        "messageId": "7586159156345265",
        "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
      }
    }
  ]
}

gcloud

运行 gcloud pubsub subscriptions pull 命令。

该示例使用以下 Google Cloud CLI 标志：

--limit=10：最多返回 10 条消息。请根据您的使用场景调整此值。
--format=json：将输出呈现为 JSON。
--auto-ack：自动确认拉取的每条消息。

在使用下面的命令数据之前，请先进行以下替换：

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。

配置 DICOM Pub/Sub 通知

须知事项

添加 Pub/Sub 发布者权限

通知格式和内容

配置和查看通知

配置 DICOM 存储区

执行此任务所需的权限

REST

curl

PowerShell

API Explorer

响应

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

响应

存储或导入 DICOM 实例并查看 Pub/Sub 通知

执行此任务所需的权限

REST

curl

PowerShell

API Explorer

响应

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Cloud Healthcare API 和 Pub/Sub 消息存储政策

排查 Pub/Sub 消息缺失问题

后续步骤