更新和修补 DICOM 研究、系列和实例

本页面介绍了如何就地更新和修补 Cloud Healthcare API 中的 DICOM 研究、系列和实例。如需了解如何使用 DICOM 数据填充 Cloud Healthcare API 中的存储区，请参阅使用 DICOMweb 标准。

更新 DICOM 实例

您可以通过上传新版本的 .dcm 文件来替换 DICOM 实例。与 storeInstances 类似，您也可以使用多部分文件一次性更新多个实例（通常用于更新包含多个实例的研究或序列）。更新后，原始实例将被完全替换。

与 storeInstances 不同，更新完整实例无法通过 JSON 元数据完成。如需了解如何使用 JSON 进行部分更新，请参阅修补 DICOM 元数据。

更新实例将被视为“upsert”。如果实例存在，则会更新该实例。如果实例不存在，则会创建该实例并将其插入到存储区中。

插入新实例时，系统会从提供的元数据中收集 SOP_CLASS_UID、SOP_INSTANCE_UID、STUDY_INSTANCE_UID 和 SERIES_INSTANCE_UID 值。UID 必须满足以下要求：

  • 仅包含以句点分隔的数值。
  • 不包含受保护健康信息 (PHI)。

以下示例展示了如何更新 DICOM 存储区中的实例。如需了解详情，请参阅 projects.locations.datasets.dicomStores.updateInstances。

curl

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

  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • LOCATION：数据集位置
  • DATASET_ID：DICOM 存储区的父数据集
  • DICOM_STORE_ID：DICOM 存储区 ID
  • DICOM_INSTANCE_FILE：本地机器上以 .dcm 后缀结尾的 DICOM 实例文件的路径

以下示例展示了使用 curl 的 PUT 请求。

curl -X PUT \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/dicom" \
    --data-binary @DICOM_INSTANCE_FILE \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

输出如下所示（采用 XML 格式）：

一次更新多个实例

以下示例展示了如何使用多部分消息更新包含多个实例的 DICOM 研究或序列。

curl

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

  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • LOCATION：数据集位置
  • DATASET_ID：DICOM 存储区的父数据集
  • DICOM_STORE_ID：DICOM 存储区 ID
  • MULTIPART_FILE：本地机器上多部分文件的路径。该文件包含多个 DICOM 实例，每个实例之间以边界分隔。
  • BOUNDARY：用于分隔多部分文件中的 DICOM 实例的边界

以下示例展示了使用 curl 的 PUT 请求。

curl -X PUT \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: multipart/related; type=application/dicom; boundary=BOUNDARY" \
    --data-binary @MULTIPART_FILE \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies"

输出如下所示（采用 XML 格式）：

修补 DICOM 元数据

您可以在研究、系列或实例级别添加、移除或修改 DICOM 标记。每个级别的行为如下：

对于返回长时间运行的操作的补丁，任何将补丁应用于实例的失败都会记录在 Cloud Logging 中。操作元数据中会返回失败的实例数，以及指向关联日志的链接。

JSON Patch

修改标记的语法遵循 JSON 补丁标准。仅支持 add、replace 和 remove 操作。您可以使用标记的公共关键字（如果是公共标记）或 8 位十六进制标识符来指定标记。请注意，所有标记路径都必须以 / 为前缀。当您 add 或 replace 标记时，必须在指定标记标识符的同时指定 VR 和标记值。remove 标记时，只需指定标记标识符。

支持修改序列中的标记，以及替换序列。 如需了解使用补丁不支持的内容，请参阅补丁限制。如需指定序列中的某个标记，请使用项索引和反斜杠分隔序列和子标记。以下示例将标记 InstanceCreationDate add 到 ReferencedInstanceSequence 的第 2 个项（请注意，序列项的索引从 0 开始）：

[
  {
    "op": "add",
    "path": "/ReferencedInstanceSequence/1/InstanceCreationDate",
    "value": {
      "vr": "DA",
      "Value": [ "20240501" ]
    }
  }
]

对于添加完整序列（或替换完整序列），JSON Patch 条目的 value 字段必须是序列的 DICOM JSON 表示法。以下示例展示了如何向实例添加包含 2 个元素的 OtherPatientIDs 序列：

[
  {
    "op": "add",
    "path": "/OtherPatientIDs",
    "value": {
      "vr": "SQ",
      "Value": [
        {
          "00100020": {
            "vr": "LO",
            "Value": [ "54321" ]
          },
          "00100021": {
            "vr": "LO",
            "Value": [ "Hospital B" ]
          }
        },
        {
          "00100020": {
            "vr": "LO",
            "Value": [ "24680" ]
          },
          "00100021": {
            "vr": "LO",
            "Value": [ "Hospital C" ]
          }
        }
      ]
    }
  }
]

修补单个实例

curl

如需修改单个实例的 DICOM 标记，请发出 PATCH 请求并指定以下信息：

  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • LOCATION：数据集位置
  • DATASET_ID：DICOM 存储区的父数据集
  • DICOM_STORE_ID：DICOM 存储区 ID
  • STUDY_UID：DICOM 实例的研究 UID
  • SERIES_UID：DICOM 实例的序列 UID
  • INSTANCE_UID：DICOM 实例的实例 UID

以下示例展示了使用 curl 的 PATCH 请求。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '[
      {
        "op": "add",
        "path": "/ProductName",
        "value": {
          "vr": "LO",
          "Value": [
            "My Product"
          ]
        }
      },
      {
        "op": "replace",
        "path": "/PatientName",
        "value": {
          "vr": "PN",
          "Value": [
            "New Patient Name"
          ]
        }
      },
      {
        "op": "remove",
        "path": "/Manufacturer"
      }
    ]' \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID/metadata"

如果请求成功，服务器将以 JSON 格式返回响应：

{
  "studyUID": "STUDY_UID",
  "seriesUID": "SERIES_UID",
  "instanceUID": "INSTANCE_UID",
  "createTimestamp": "CREATE_TIMESTAMP",
  "metadata": {
    // Full DICOM JSON metadata for the instance after edits applied
  }
}

修补研究或系列

curl

要修改给定研究中所有实例的 DICOM 标记，请发出 PATCH 请求并指定以下信息：

  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • LOCATION：数据集位置
  • DATASET_ID：DICOM 存储区的父数据集
  • DICOM_STORE_ID：DICOM 存储区 ID
  • STUDY_UID：DICOM 研究的检查 UID

以下示例展示了使用 curl 的 PATCH 请求。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '[
      {
        "op": "add",
        "path": "/ProductName",
        "value": {
          "vr": "LO",
          "Value": [
            "My Product"
          ]
        }
      },
      {
        "op": "replace",
        "path": "/PatientName",
        "value": {
          "vr": "PN",
          "Value": [
            "New Patient Name"
          ]
        }
      },
      {
        "op": "remove",
        "path": "/Manufacturer"
      }
    ]' \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/metadata"

如果请求成功，服务器将以 JSON 格式返回响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

响应包含操作 ID。要跟踪操作状态并查看更多详细信息，请使用操作 get 方法：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

如果请求成功，服务器将以 JSON 格式返回包含操作状态的响应：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.dicom.DicomWebService.UpdateStudyMetadata",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "CLOUD_LOGGING_URL",
    "counter": {
      "success": "1" // Number of instances updated in the study
    }
  },
  "done": true,
  "response": {
    "@type": "..."
  }
}

限制

修改 DICOM 标记时，存在以下限制和其他行为：

  • 您无法修改以下标记：
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • 组号小于“0008”的所有标记
    • 任何被视为 bulkdata 的标记（请参阅 bulkdata 定义）
    • 除了上述定义之外，任何 VR 为 OD、OF、OL、OV、SV 或 UV 的标记都无法使用 patch（无论是 add 还是 replace 操作）添加，无论长度如何
  • 包含被视为 bulkdata 的标记的序列无法进行编辑
    • 这意味着，如果原始序列中包含的任何标记被视为 bulkdata，则对序列标记执行 replace 或 remove 操作将会失败
    • 此外，如果新序列中包含的任何标记被视为 bulkdata，则对序列标记执行的任何 replace 或 add 操作都会失败
  • 如果您尝试 replace 或 remove 不存在的标记，Cloud Healthcare API 会返回错误，并且修改操作会失败
  • 如果您尝试 add 已存在的标记，修改操作的行为将与调用替换操作相同。替换操作会将标记的现有值替换为操作中指定的新值
  • 虽然可以添加/替换/移除序列，也可以修改序列中商品的标记，但无法添加/替换/移除序列中的单个商品
    • 实际上，这意味着任何标记路径以索引结尾的编辑都会被拒绝（例如 /ReferencedSeriesSequence/0）
    • 如果需要更改序列中的单个商品，请将整个父序列替换为应用了更改的副本

使用 DICOM Studio 进行更新

您可以使用 DICOM Studio 更新研究、序列或实例的 DICOM 元数据。

如需使用 DICOM Studio 更新 DICOM 元数据，请执行以下操作：

  1. 搜索要更新的研究、序列或实例。
  2. 在搜索结果中，点击相应商品以导航到其详情页面。
  3. 点击元数据标签页。
  4. 选中要修改的一个或多个标记对应的复选框，然后点击修改。
  5. 在修改面板中，展开要修改的代码。
  6. 修改标记的关键字、VR 或值。
  7. 点击保存。

所有限制仍然适用于界面。此外，用户界面还存在以下限制：

  1. 标记编辑界面不支持编辑值多重性 (VM) 大于 1 的标记。
  2. 标记编辑界面不会针对预期的 VR 或值类型提供任何指导或验证。