更新及修補 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 位數的十六進位識別碼指定標記。請注意，所有代碼路徑都必須加上 / 前置字串。add 或 replace 標記時，您必須指定標記的 VR 和值，以及標記 ID。remove 代碼時，只需要指定代碼 ID。

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

[
  {
    "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)。
    • 如需變更序列中的個別項目，請將整個父項序列替換為已套用變更的副本

使用 DICOM Studio 更新

您可以使用 DICOM Studio 更新研究、系列或例項的 DICOM 中繼資料。

如要使用 DICOM Studio 更新 DICOM 中繼資料，請按照下列步驟操作：

  1. 搜尋要更新的研究、系列項目或執行個體。
  2. 在搜尋結果中按一下項目，即可前往詳細資料頁面。
  3. 按一下「中繼資料」分頁標籤。
  4. 選取一或多個要編輯的代碼，然後按一下「編輯」。
  5. 在編輯面板中，展開要修改的代碼。
  6. 編輯代碼的關鍵字、VR 或值。
  7. 按一下 [儲存]。

使用者介面仍會套用所有限制。此外，使用者介面有下列限制：

  1. 標記編輯介面不支援編輯 VM 大於 1 的標記。
  2. 標記編輯介面不會提供任何有關預期 VR 或值類型的指引或驗證。