更新及修補 DICOM 研究、系列和執行個體

本頁說明如何更新及修補 Cloud Healthcare API 中的 DICOM 研究、系列和執行個體。如要瞭解如何使用 DICOM 資料填入 Cloud Healthcare API 中的儲存庫，請參閱「使用 DICOMweb 標準」。

更新 DICOM 執行個體

如要取代 DICOM 執行個體，請上傳新版 .dcm 檔案。與 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：本機上 DICOM 執行個體檔案的路徑，結尾為 .dcm 後置字元

以下範例顯示如何使用 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 Patch 標準。系統僅支援 add、replace 和 remove 運算。您可以透過公開關鍵字 (如果標記為公開) 或 8 位數的十六進位 ID 指定標記。請注意，所有代碼路徑都必須加上 / 前置字串。add 或 replace 標記時，您必須指定標記的 VR 和值，以及標記 ID。remove 代碼時，只需要指定代碼 ID。

系統支援編輯序列中的標記，以及更換序列。 如要瞭解使用修補程式時不支援的項目，請參閱修補程式限制。如要在序列中指定標記，請使用項目索引和反斜線分隔序列和子項標記。以下範例會將標記 add 新增至 ReferencedInstanceSequence 的第 2 個項目 (請注意，序列項目是以 0 為索引)： InstanceCreationDate

[
  {
    "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」的任何標記
    • 任何視為大量資料的標記 (請參閱大量資料定義)
    • 除了上述定義外，凡是 VR 為 OD、OF、OL、OV、SV 或 UV 的標記，一律無法使用 patch (add 或 replace 作業皆不允許) 新增，長度不限
  • 含有視為大量資料的標記的序列無法編輯
    • 也就是說，如果原始序列中包含任何被視為大量資料的代碼，對序列代碼執行的 replace 或 remove 作業就會失敗。
    • 此外，如果新序列中包含的任何代碼被視為大量資料，對序列代碼執行的任何 replace 或 add 作業都會失敗。
  • 如果您嘗試 replace 或 remove 不存在的標記，Cloud Healthcare API 會傳回錯誤，且編輯作業會失敗
  • 如果您嘗試 add 現有標記，編輯作業的行為與呼叫取代作業相同。取代作業會將現有標籤值替換為作業中指定的新值
  • 雖然可以新增/取代/移除序列 (也可以編輯序列中項目的標記)，但無法新增/取代/移除序列中的個別項目。
    • 在實務上，這表示系統會拒絕任何標記路徑結尾為索引的編輯內容 (例如 /ReferencedSeriesSequence/0)。
    • 如需變更序列中的個別項目，請將整個父項序列替換為已套用變更的副本