配置 DICOM Pub/Sub 通知

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

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

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

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

图 1 显示了以下步骤：

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

须知事项

1. 创建一个主题。
2. 创建拉取订阅。

添加 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

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

将请求正文保存在名为 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 init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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 init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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 init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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 消息，请完成以下步骤：

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

2. 拉取消息。如果您在单个请求中导入多个 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

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

   执行以下命令：

   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

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

   执行以下命令：

   $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 init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

   Windows (PowerShell)

   注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

   Windows (cmd.exe)

   注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

   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。

后续步骤

• 使用流控制处理瞬时峰值
• 处理消息失败
• 重放和完全清除消息
• Pub/Sub 的架构概览