Memperbarui dan menerapkan patch pada studi, rangkaian, dan instance DICOM

Halaman ini menjelaskan cara studi, rangkaian, dan instance DICOM di Cloud Healthcare API dapat diperbarui dan di-patch di tempat. Untuk mengetahui informasi tentang cara mengisi penyimpanan di Cloud Healthcare API dengan data DICOM, lihat Menggunakan standar DICOMweb.

Memperbarui instance DICOM

Instance DICOM dapat diganti dengan mengupload file .dcm versi baru. Mirip dengan storeInstances, file multibagian juga dapat digunakan untuk memperbarui beberapa instance sekaligus (sering kali untuk memperbarui studi atau seri dengan beberapa instance). Setelah diperbarui, instance asli akan diganti sepenuhnya.

Tidak seperti storeInstances, memperbarui instance lengkap tidak dapat dilakukan dengan metadata JSON. Untuk update parsial dengan JSON, lihat Membuat patch metadata DICOM.

Memperbarui instance akan diperlakukan sebagai "upsert". Jika instance ada, maka instance tersebut akan diperbarui. Jika instance tidak ada, instance akan dibuat dan dimasukkan ke dalam penyimpanan.

Saat menyisipkan instance baru, nilai SOP_CLASS_UID, SOP_INSTANCE_UID, STUDY_INSTANCE_UID, dan SERIES_INSTANCE_UID dikumpulkan dari metadata yang diberikan. UID harus memenuhi persyaratan berikut:

  • Hanya berisi nilai numerik yang dipisahkan dengan titik.
  • Tidak berisi informasi kesehatan terlindungi (PHI).

Contoh berikut menunjukkan cara mengupdate instance di penyimpanan DICOM. Untuk mengetahui informasi selengkapnya, lihat projects.locations.datasets.dicomStores.updateInstances.

curl

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi set data
  • DATASET_ID: set data induk DICOM store
  • DICOM_STORE_ID: ID penyimpanan DICOM
  • DICOM_INSTANCE_FILE: jalur ke file instance DICOM di komputer lokal Anda yang diakhiri dengan sufiks .dcm

Contoh berikut menunjukkan permintaan PUT menggunakan curl.

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"

Outputnya adalah respons XML berikut:

Memperbarui beberapa instance sekaligus

Contoh berikut menunjukkan cara memperbarui studi atau rangkaian DICOM, yang terdiri dari beberapa instance, menggunakan pesan multipart.

curl

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi set data
  • DATASET_ID: set data induk DICOM store
  • DICOM_STORE_ID: ID penyimpanan DICOM
  • MULTIPART_FILE: jalur ke file multipart di komputer lokal Anda. File berisi beberapa instance DICOM, dengan masing-masing dipisahkan oleh batas.
  • BOUNDARY: batas yang digunakan untuk memisahkan instance DICOM dalam file multipart

Contoh berikut menunjukkan permintaan PUT menggunakan curl.

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"

Outputnya adalah respons XML berikut:

Membuat patch metadata DICOM

Anda dapat menambahkan, menghapus, atau mengedit tag DICOM di tingkat studi, rangkaian, atau instance. Perilaku untuk setiap tingkat adalah sebagai berikut:

Untuk patch yang menampilkan operasi yang berjalan lama, kegagalan penerapan patch ke instance akan dicatat dalam Cloud Logging. Jumlah instance yang gagal ditampilkan dalam metadata operasi, beserta link ke log terkait.

Patch JSON

Sintaks untuk pengeditan tag mengikuti standar Patch JSON. Hanya operasi add, replace, dan remove yang didukung. Anda dapat menentukan tag menggunakan kata kunci publiknya (jika tag bersifat publik), atau dengan ID heksadesimal 8 digit. Perhatikan bahwa semua jalur tag harus diawali dengan /. Saat Anda add atau replace tag, Anda harus menentukan VR dan nilai untuk tag bersama dengan ID tag. Saat remove tag, Anda hanya perlu menentukan ID tag.

Pengeditan tag dalam urutan didukung, begitu juga penggantian urutan. Lihat batasan patch untuk mengetahui hal yang tidak didukung menggunakan patch. Untuk menentukan tag dalam urutan, pisahkan urutan dan tag turunan dengan indeks item dan garis miring terbalik. Berikut adalah contoh yang add tag InstanceCreationDate ke item ke-2 dari ReferencedInstanceSequence (perhatikan bahwa item urutan diindeks 0):

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

Untuk menambahkan urutan lengkap (atau mengganti urutan lengkap), kolom value dari entri Patch JSON harus berupa representasi JSON DICOM dari urutan. Berikut adalah contoh penambahan urutan OtherPatientIDs dengan 2 elemen ke instance:

[
  {
    "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" ]
          }
        }
      ]
    }
  }
]

Menerapkan patch pada satu instance

curl

Untuk mengedit tag DICOM untuk satu instance, buat permintaan PATCH dan tentukan informasi berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi set data
  • DATASET_ID: set data induk DICOM store
  • DICOM_STORE_ID: ID penyimpanan DICOM
  • STUDY_UID: UID studi instance DICOM
  • SERIES_UID: UID seri instance DICOM
  • INSTANCE_UID: UID instance dari instance DICOM

Contoh berikut menunjukkan permintaan PATCH menggunakan curl.

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"

Jika permintaan berhasil, server akan menampilkan respons dalam format JSON:

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

Menambal studi atau seri

curl

Untuk mengedit tag DICOM untuk semua instance dalam studi tertentu, buat permintaan PATCH dan tentukan informasi berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi set data
  • DATASET_ID: set data induk DICOM store
  • DICOM_STORE_ID: ID penyimpanan DICOM
  • STUDY_UID: UID studi DICOM

Contoh berikut menunjukkan permintaan PATCH menggunakan curl.

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"

Jika permintaan berhasil, server akan menampilkan respons dalam format JSON:

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

Respons berisi ID operasi. Untuk melacak status operasi dan melihat detail selengkapnya, gunakan Metode get operasi:

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"

Jika permintaan berhasil, server akan menampilkan respons dengan status operasi dalam format 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": "..."
  }
}

Batasan

Batasan dan perilaku tambahan berikut berlaku saat mengedit tag DICOM:

  • Anda tidak dapat mengedit tag berikut:
    • SOPInstanceUID (0008,0018)
    • SeriesInstanceUID (0020,000E)
    • StudyInstanceUID (0020,000D)
    • Modality (0008,0060)
    • ModalitiesInStudy (0008,0061)
    • SpecificCharacterSet (0008,0005)
    • Tag apa pun dengan Nomor Grup kurang dari "0008"
    • Tag apa pun yang dianggap sebagai bulkdata (lihat definisi bulkdata)
    • Selain definisi di atas, tag apa pun dengan VR OD, OF, OL, OV, SV, atau UV tidak dapat ditambahkan menggunakan patch (baik operasi add maupun replace), terlepas dari panjangnya
  • Urutan yang berisi tag yang dianggap sebagai bulkdata tidak dapat diedit
    • Artinya, operasi replace atau remove pada tag urutan akan gagal jika salah satu tag yang ada dalam urutan asli dianggap sebagai bulkdata
    • Selain itu, setiap operasi replace atau add pada tag urutan akan gagal jika ada tag yang terdapat dalam urutan baru yang dianggap sebagai data massal
  • Jika Anda mencoba replace atau remove tag yang tidak ada, Cloud Healthcare API akan menampilkan error dan pengeditan gagal
  • Jika Anda mencoba add tag yang sudah ada, operasi pengeditan akan berperilaku sama seperti jika Anda memanggil operasi penggantian. Operasi penggantian menggantikan nilai tag yang ada dengan nilai baru yang ditentukan dalam operasi
  • Meskipun urutan dapat ditambahkan/diganti/dihapus (dan tag dalam item dalam urutan juga dapat diedit), item individual dalam urutan tidak dapat ditambahkan/diganti/dihapus
    • Dalam praktiknya, ini berarti setiap pengeditan dengan jalur tag yang diakhiri dengan indeks akan ditolak (misalnya, /ReferencedSeriesSequence/0)
    • Jika perubahan pada item individual dalam urutan diperlukan, ganti seluruh urutan induk dengan salinan yang telah menerapkan perubahan