更新和修补 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）
    • 如果需要更改序列中的单个商品，请将整个父序列替换为应用了更改的副本