DICOM 연구, 시리즈, 인스턴스 업데이트 및 패치

이 페이지에서는 Cloud Healthcare API의 DICOM 연구, 시리즈, 인스턴스를 현재 위치에서 업데이트하고 패치하는 방법을 설명합니다. Cloud Healthcare API에서 DICOM 데이터로 저장소를 채우는 방법에 대한 자세한 내용은 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: 로컬 머신에 있는 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 패치

태그 수정 구문은 JSON 패치 표준을 따릅니다. add, replace, remove 작업만 지원됩니다. 공개 키워드 (공개 태그인 경우) 또는 8자리 16진수 식별자를 사용하여 태그를 지정할 수 있습니다. 모든 태그 경로는 /으로 시작해야 합니다. 태그를 add하거나 replace할 때 태그 식별자와 함께 VR 및 태그 값을 지정해야 합니다. 태그를 remove할 때는 태그 식별자만 지정하면 됩니다.

시퀀스 내 태그 수정과 시퀀스 교체가 지원됩니다. 패치를 사용하여 지원되지 않는 항목은 패치 제한사항을 참고하세요. 시퀀스 내에서 태그를 지정하려면 시퀀스와 하위 태그를 항목 색인과 백슬래시로 구분합니다. 다음은 InstanceCreationDate 태그를 ReferencedInstanceSequence의 두 번째 항목에 add하는 예입니다 (시퀀스 항목은 0부터 시작함).

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

전체 시퀀스를 추가하거나 대체하는 경우 JSON 패치 항목의 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 작업)를 사용하여 추가할 수 없습니다.
  • bulkdata로 간주되는 태그가 포함된 시퀀스는 수정할 수 없습니다.
    • 즉, 원래 시퀀스에 포함된 태그 중 하나라도 bulkdata로 간주되면 시퀀스 태그에 대한 replace 또는 remove 작업이 실패합니다.
    • 또한 새 시퀀스에 포함된 태그 중 하나라도 bulkdata로 간주되면 시퀀스 태그에 대한 replace 또는 add 작업이 실패합니다.
  • 존재하지 않는 태그를 replace하거나 remove하려고 하면 Cloud Healthcare API가 오류를 반환하고 수정이 실패합니다.
  • 이미 존재하는 태그를 add하려고 하면 바꾸기 작업을 호출한 경우와 동일한 방식으로 수정 작업이 작동합니다. 바꾸기 작업은 태그의 기존 값을 작업에 지정된 새 값으로 바꿉니다.
  • 시퀀스는 추가/바꾸기/삭제할 수 있으며 시퀀스 내 항목의 태그도 수정할 수 있지만 시퀀스의 개별 항목은 추가/바꾸기/삭제할 수 없습니다.
    • 실제로 이는 색인으로 끝나는 태그 경로가 있는 수정사항은 거부됨을 의미합니다 (예: /ReferencedSeriesSequence/0).
    • 시퀀스의 개별 항목을 변경해야 하는 경우 변경사항이 적용된 사본으로 전체 상위 시퀀스를 대체합니다.