将 DICOM 元数据流式传输到 BigQuery

本页面介绍如何配置 DICOM 存储区，以便在出现以下任一情况时将 DICOM 实例元数据导出到 BigQuery 表：

如需存储 DICOM 实例，您可以使用存储事务或从 Cloud Storage 存储桶导入 DICOM 对象。
您可以使用删除请求删除 DICOM 实例。

将 DICOM 元数据流式传输到 BigQuery 表会使该表与您的 DICOM 数据同步，以便您可以在最新版本的 DICOM 存储区上运行复杂的查询。

须知事项

设置 BigQuery 权限

在将 DICOM 元数据流式传输到 BigQuery 之前，您必须向 Cloud Healthcare Service Agent 服务帐号授予所需的权限。如需了解详情，请参阅 DICOM 存储区 BigQuery 权限。

了解如何将 DICOM 元数据导出到 BigQuery

在配置流式传输之前，请了解如何将 DICOM 元数据导出到 BigQuery。

配置 DICOM 存储区

如需启用将数据流式传输到 BigQuery 的功能，请在 DICOM 存储区中配置 StreamConfig 对象。在 StreamConfig 对象中，将 BigQueryDestination 对象设置为完全限定的 BigQuery 表 URI 作为 DICOM 实例元数据目标位置。

您最多可以将五个 BigQuery 目标位置指定为逗号分隔 JSON 对象。

删除 DICOM 存储区中的 DICOM 实例不会删除包含这些实例的元数据的 BigQuery 行。

控制台

如需更新 DICOM 存储区以启用 BigQuery 流式传输，请完成以下步骤：

在 Google Cloud 控制台中，进入数据集页面。
进入“数据集”
选择包含您要修改的 DICOM 存储区的数据集。
选择要添加流处理配置的 DICOM 存储区。
在 Datastore 详情页面上，点击添加新的流式传输配置。
在新建流式传输配置字段中，点击浏览。
1. 在选择表窗格中，选择一个 BigQuery 表。
2. 点击选择。
点击完成。

REST

以下示例展示了如何更新 DICOM 存储区以启用 BigQuery 流式传输。在这些示例中，DICOM 存储区和 BigQuery 表位于同一项目中。要将 DICOM 元数据导出到其他项目，请参阅将 DICOM 元数据导出到其他项目。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目的 ID
LOCATION：数据集位置
DATASET_ID： DICOM 存储区的父数据集
DICOM_STORE_ID：DICOM 存储区 ID
BIGQUERY_DATASET_ID：现有 BigQuery 数据集的名称
BIGQUERY_TABLE_ID：BigQuery 数据集中表的唯一名称。如需了解命名要求，请参阅表命名。BigQuery 数据集必须存在，但 Cloud Healthcare API 可以更新现有表或创建新表。

请求 JSON 正文：

{
  'streamConfigs': [{
     'bigqueryDestination': {
      'tableUri': 'bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID'
     }
  }]
}

如需发送请求，请选择以下方式之一：

curl

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

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

cat > request.json << 'EOF'
{
  'streamConfigs': [{
     'bigqueryDestination': {
      'tableUri': 'bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID'
     }
  }]
}
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=streamConfigs"

PowerShell

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
  'streamConfigs': [{
     'bigqueryDestination': {
      'tableUri': 'bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID'
     }
  }]
}
'@  | 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=streamConfigs" | Select-Object -Expand Content

API Explorer

复制请求正文并打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

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

响应

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "tableUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID"
      }
    }
  ]
}

删除元数据

在以前的 Cloud Healthcare API 版本中，仅当 DICOM 实例插入 DICOM 存储区时， DICOM 实例元数据才会导出到 BigQuery。在写入要删除的元数据时，向包含 DICOM 元数据的生成的表中添加了两个名为 Type 和 LastUpdated 的新列。

对于在引入删除元数据之前存在的表中的所有元数据，这些列都具有 NULL 值。NULL 是最低值，按降序排序时显示在最后。

生成的 BigQuery 视图

在 DICOM 存储区中插入或删除 DICOM 实例时，配置的 BigQuery 表会更新。

如果表的某个视图不存在，则系统会创建该视图。否则，视图会更新。

限制和其他行为

导出的元数据中可能缺少某些 DICOM 标记。如果是这样，缺失的标记位于目标 BigQuery 表中名为 DroppedTags.TagName 的单独列中，或者完全移除。

由于以下某个原因，标记缺失：

DICOM 标记是排除的 VR 中列出的不受支持的 VR。
DICOM 标记约为 1 MB，这会导致标记被添加到 DroppedTags.Name 列。大小超过约 1 MB 的序列 (SQ) 标记将被完全排除。
目标 BigQuery 表中的列数超出了列数上限。将 DICOM 元数据导出到 BigQuery 表时超出列限制时，与现有列不匹配的 DICOM 标记会添加到 DroppedTags.Name 列中。如果无法添加 DroppedTags 列，则 DICOM 标记将被丢弃，并且不会发出通知，并且会生成警告日志。如需了解详情，请参阅排查用于查看日志的 DICOM 流式传输请求。

将删除元数据合并到现有表中

生成的视图的行为取决于其基表是否包含在引入删除元数据功能之前添加的元数据。

假设 BigQuery 表包含支持删除元数据之前的 DICOM 元数据，然后发生了以下情况：

您可以将 DICOM 实例插入 DICOM 存储区。
您可以从 DICOM 存储区中删除 DICOM 实例。
您可以修改原始 DICOM 实例的标记，并将修改后的 DICOM 实例插入 DICOM 存储区。

由于 BigQuery 表包含支持删除元数据之前的原始元数据，因此原始 DICOM 实例及其修改后的版本具有相同的研究、系列和实例唯一标识符 (UID)。生成的视图可能包含原始 DICOM 实例或最新的 DICOM 实例。如果没有 LastUpdated 列，视图将无法识别哪个 DICOM 实例较新。

如需确保查询的是最新的 DICOM 实例元数据，请执行以下操作之一：

查询基表而不是视图。确保查询在修改后的 DICOM 实例中搜索更新后的标记。
删除包含 DICOM 元数据的现有表，然后手动将 DICOM 元数据导出到 BigQuery 以重新创建该表。重新创建的表包含 LastUpdated 列。

此选项会移除历史流式元数据，但需确保该表包含具有有效值的 LastUpdated 列。

排查 DICOM 流式传输请求问题

如果在 BigQuery 请求中执行 DICOM 导出元数据期间发生错误，则错误将记入 Cloud Logging 中。如需了解详情，请参阅在 Cloud Logging 中查看错误日志。

如需在 Google Cloud 控制台中过滤流式传输 DICOM 元数据错误日志，请完成以下步骤：

前往日志浏览器页面。

转到日志浏览器

在查询字段中，输入以下查询：

logName="healthcare.googleapis.com%2Fdicom_stream"

点击运行查询。

所有错误日志都会显示在查询结果部分中。