Pernyataan kesesuaian DICOM

Penyimpanan DICOM dalam Cloud Healthcare API mendukung subset layanan web RESTful yang ditentukan dalam standar DICOM PS3.18 - Web Services (biasanya disebut sebagai DICOMweb). Secara khusus, mereka mendukung Studies Service and Resources (sebelumnya disebut sebagai layanan WADO-RS, STOW-RS, dan QIDO-RS).

Selain itu, Cloud Healthcare API mendukung layanan web berpemilik untuk menghapus instance DICOM.

Cloud Healthcare API tidak mendukung URI Service, Worklist Service, Non-Patient Instance Service atau Capabilities Transactions.

Mengambil transaksi

Retrieve Transaction adalah layanan web RESTful untuk mengambil data pencitraan DICOM.

Retrieve Transaction mendukung pengambilan resource berikut:

  • Sumber Daya DICOM:
    • Studi
    • Seri
    • Instance
    • Frame
    • Bulkdata
  • Resource Metadata
    • Studi
    • Seri
    • Instance
  • Resource yang Dirender
    • Instance
    • Frame

API ini tidak mendukung resource Thumbnail.

Lihat Kuota dan batas untuk mengetahui detail kuota dan batas untuk metode ini.

Studi/rangkaian/instance DICOM

Header Penerimaan berikut didukung:

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (default)
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.91
  • multipart/related; type="application/dicom"; transfer-syntax=*

Instance DICOM

Selain Header Penerimaan di atas, RetrieveInstance mendukung jenis konten satu bagian untuk memudahkan:

  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.90
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.91
  • application/dicom; transfer-syntax=*

Ini bukan bagian dari standar DICOMweb resmi.

Frame DICOM

Header Penerimaan berikut didukung:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (default)
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

Sintaksis transfer * memungkinkan pengguna meminta agar tidak ada transcoding yang dilakukan, sehingga sintaksis transfer file yang diupload akan digunakan. Untuk application/octet-stream, data massal akan ditampilkan dalam format apa pun yang muncul dalam file DICOM yang diupload.

Resource yang dirender

Header Penerimaan berikut didukung:

  • image/jpeg (default)
  • image/png

Hanya pengambilan resource Instance atau Frame yang didukung.

Tidak ada parameter URL yang didukung selain Area Pandang.

Resource metadata

Header Penerimaan berikut didukung:

  • application/dicom+json (default)
  • multipart/related; type=application/dicom+xml

Tag yang dienkode sebagai elemen InlineBinary akan dienkode menggunakan pengurutan byte little-endian, karena parameter sintaksis transfer tidak didukung di endpoint yang meminta resource metadata.

RetrieveMetadata akan menyertakan BulkDataURIs untuk tag yang cocok dengan Definisi data massal.

Tag urutan DICOM yang berisi lebih dari sekitar 1 MiB data tidak akan ditampilkan di resource metadata. Batasan ini hanya berlaku untuk resource metadata. Resource DICOM akan tetap berisi tag ini.

Resource bulkdata

Header Penerimaan berikut didukung:

  • multipart/related; type="application/octet-stream"; transfer-syntax=* (default)
  • application/octet-stream; transfer-syntax=*

Sintaksis transfer yang didukung untuk transcoding

Header Accept di atas menjelaskan jenis media & sintaksis transfer yang dapat Anda minta dari API, tetapi hal ini mungkin tidak selalu memungkinkan, bergantung pada sintaksis transfer file asli yang diupload. Secara khusus, transcoding hanya dapat dilakukan dari sintaksis transfer berikut:

  • 1.2.840.10008.1.2 (Implisit Little Endian)
  • 1.2.840.10008.1.2.1 (Little Endian Eksplisit)
  • 1.2.840.10008.1.2.2 (VR Eksplisit Big Endian)
  • 1.2.840.10008.1.2.4.50 (JPEG Baseline Process 1)
  • 1.2.840.10008.1.2.4.57 (JPEG Lossless)
  • 1.2.840.10008.1.2.4.70 (Nilai Seleksi JPEG Lossless 1)
  • 1.2.840.10008.1.2.4.90 (Khusus JPEG 2000 Lossless)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE Lossless)

Jika file asli memiliki sintaksis transfer selain yang ada dalam daftar di atas dan Anda meminta transkode ke format lain, error akan ditampilkan.

Cloud Healthcare API tidak dapat melakukan transcoding gambar non-monokrom dengan kedalaman bit lebih besar dari 8 ke JPEG. Selain itu, gambar dengan nilai Bits Allocated (0028, 0100) sebesar 1 atau yang disimpan dalam tag Float Pixel Data (7FE0,0008), Double Float Pixel Data (7FE0,0009) hanya dapat ditranskode antara format asli.

Untuk menonaktifkan transkode dan mengambil file apa pun dari API, Anda dapat menyetel transfer-syntax=* di header Accept.

Kode status

Kode Arti
200 (OK) Payload respons berisi representasi untuk semua Target Resource.
400 (Bad Request) Permintaan tidak valid (mis. parameter atau header kueri yang salah) untuk Target Resource yang ditentukan (mis. data piksel tidak ada).
401 (Tidak Sah) Permintaan tidak memiliki kredensial autentikasi.
403 (Permission Denied) Pengguna yang diautentikasi tidak memiliki akses ke resource ini (atau resource tidak ada).
406 (Tidak Dapat Diterima) Server tidak mendukung salah satu Jenis Media yang Dapat Diterima.
429 (Too Many Requests) Klien melampaui kuota.
503 (Layanan Tidak Tersedia) Server saat ini tidak tersedia atau permintaan melebihi batas waktunya.

Transaksi toko

Store Transaction adalah layanan web RESTful untuk menyimpan data pencitraan DICOM.

Transaksi penyimpanan menerima file biner DICOM Bagian 10 secara langsung atau menerima pemisahan file DICOM menjadi metadata (direpresentasikan dalam JSON) dan data massal. Kedua versi ini memiliki semantik yang berbeda yang dijelaskan di bagian berikut.

Lihat Kuota dan batas untuk mengetahui detail kuota dan batas untuk metode ini.

File biner DICOM bagian 10

Jenis Content-Type berikut didukung:

  • multipart/related; type=application/dicom
  • application/dicom

Tidak ada pemaksaan atau penggantian atribut yang dilakukan oleh server.

Versi ini menerima semua sintaksis transfer dan class SOP. Hanya validasi minimal file DICOM yang dilakukan untuk mengekstrak beberapa atribut metadata utama.

Perhatikan bahwa untuk mempermudah, Transaksi Penyimpanan juga menerima permintaan HTTP satu bagian dengan satu instance DICOM dengan jenis konten application/dicom. Ini bukan bagian dari standar DICOMweb resmi.

Lihat Menyimpan instance DICOM untuk panduan cara kerja terkait.

Metadata JSON dan permintaan data massal

Saat menyimpan instance menggunakan metadata JSON dan data massal, bagian multipart pertama harus terdiri dari array JSON instance DICOM.

Bagian pertama harus memiliki Content-Type application/dicom+json; transfer-syntax=TransferSyntaxUID dengan TransferSyntaxUID adalah sintaksis transfer yang digunakan untuk mengenkode data biner dalam objek InlineBinary. Jika tidak ada objek InlineBinary dalam metadata, parameter transfer-syntax dapat dihilangkan.

Elemen DICOM berikut harus ada di setiap instance dalam metadata JSON:

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

Elemen SpecificCharacterSet harus disetel ke ISO_IR 192, dan metadata JSON harus dienkode dalam unicode UTF-8. TransferSyntaxUID dapat disetel ke sintaksis transfer yang valid, kecuali sintaksis transfer yang tidak didukung berikut:

  • 1.2.840.10008.1.2.2 (VR Eksplisit Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

Dalam metadata JSON, pengguna dapat menentukan beberapa BulkDataURI untuk tag DICOM dengan VR OB, OW, atau UN. BulkDataURI ini menunjukkan bahwa data biner untuk tag yang berisi URI akan dikirim di bagian berikutnya yang memiliki header Content-Location yang ditetapkan ke BulkDataURI.

Setiap instance dalam metadata JSON dapat memiliki paling banyak satu BulkDataURI. Tidak boleh ada BulkDataURI duplikat dalam metadata JSON. Data massal gambar terkompresi hanya boleh dikirim untuk tag PixelData, dan saat dikirim, sintaksis transfer yang ditentukan di bagian data massal harus cocok dengan nilai elemen TransferSyntaxUID instance.

Jenis Content-Type berikut didukung untuk bagian data massal:

  • application/octet-stream
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​51
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​57
  • image/x-dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.4.81
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.90
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.91
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.92
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.93

Metode alternatif untuk menentukan data biner adalah dengan mengenkodenya sebagai string berenkode base64 InlineBinary. Hal ini didukung untuk semua tag kecuali PixelData, yang harus dikirim sebagai bagian data massal. Saat objek InlineBinary digunakan dalam metadata JSON, sintaksis transfer yang digunakan untuk encoding harus ditentukan dalam Content-Type bagian metadata JSON.

Server tidak mendapatkan atribut makro deskripsi piksel gambar.

Lihat Membuat instance DICOM dari metadata JSON dan file JPEG untuk panduan cara melakukannya.

Respons

Jika terjadi error, tag FailureDetail (0009, 0097) tambahan (untuk respons XML) atau tag FailureDetailJSON (0009,1097) (untuk respons JSON) akan ditampilkan. Tag FailureDetail memberikan deskripsi error yang dapat dibaca manusia.

Jika instance DICOM memiliki tuple <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> yang sama dengan instance lain yang sudah ada di penyimpanan DICOM, error Kegagalan pemrosesan akan ditampilkan dengan tag FailureDetail "already exists".

Respons dapat berupa format JSON atau XML yang dapat dikontrol melalui nilai header Accept berikut:

  • application/dicom+xml (default)
  • application/dicom+json

Kode status

Kode Arti
200 (OK) Resource berhasil disimpan.
400 (Bad Request) Permintaan tidak valid (misalnya, jenis media atau sintaksis transfer tidak didukung).
401 (Tidak Sah) Permintaan tidak memiliki kredensial autentikasi.
403 (Permission Denied) Pengguna yang diautentikasi tidak memiliki akses ke resource ini (atau resource tidak ada).
406 (Tidak Dapat Diterima) Server tidak mendukung salah satu Jenis Media yang Dapat Diterima.
409 (Conflict) Setidaknya satu resource tidak berhasil disimpan (misalnya, file DICOM tidak valid). Periksa tag FailureDetail di isi respons untuk mengetahui informasi selengkapnya.
429 (Too Many Requests) Klien melampaui kuota.
503 (Layanan Tidak Tersedia) Server saat ini tidak tersedia atau permintaan melebihi batas waktunya.

Menelusuri transaksi

Search Transaction adalah layanan web RESTful untuk membuat kueri metadata pencitraan DICOM.

Cloud Healthcare API mendukung penelusuran studi, seri, dan instance.

Parameter penelusuran

Penelusuran berdasarkan tag berikut didukung:

  • Studi:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • Seri: semua istilah penelusuran tingkat studi dan
    • SeriesInstanceUID
    • Pengandaian
  • Instance: semua istilah penelusuran tingkat studi/seri dan
    • SOPInstanceUID

Hanya pencocokan persis nilai tunggal yang didukung, kecuali untuk StudyDate yang mendukung kueri rentang dan PatientName yang mendukung pencocokan tidak persis.

Parameter URL tambahan berikut didukung:

  • fuzzymatching: Jika disetel ke true, pencocokan fuzzy akan diterapkan ke tag PatientName. Pencocokan fuzzy akan melakukan tokenisasi dan normalisasi baik nilai PatientName dalam kueri maupun nilai yang disimpan. Akan cocok jika ada token penelusuran yang merupakan awalan dari token yang disimpan. Misalnya, jika PatientName adalah "John^Doe", maka "jo", "Do", dan "John Doe" akan cocok. Namun, "ohn" tidak akan cocok.
  • includefield: Dapat disetel ke daftar attributeID yang dipisahkan koma, seperti ID atau kata kunci tag DICOM, atau disetel ke nilai all untuk menampilkan semua tag yang tersedia. Untuk mengetahui daftar tag yang tersedia, lihat Hasil yang ditampilkan.

Penomoran halaman didukung menggunakan parameter kueri limit dan offset. Tidak ada header respons Peringatan jika tidak ada lagi hasil yang tersedia. Anda harus menjalankan kueri tambahan untuk menentukan apakah ada hasil lainnya.

  • limit: Jumlah maksimum hasil yang harus ditampilkan, hingga maksimum 5.000 untuk studi/deret dan 50.000 untuk instance. Jumlah hasil default adalah 100 untuk studi/deret dan 1.000 untuk instance.

  • offset: Jumlah hasil yang akan dilewati di awal hingga maksimum 1.000.000.

Selisih Zona Waktu dari UTC tidak didukung.

Hasil yang ditampilkan

Respons dapat berupa format JSON atau XML yang dapat dikontrol menggunakan nilai header Accept berikut:

  • application/dicom+json (default)
  • multipart/related; type=application/dicom+xml

Secara default, atribut berikut akan ditampilkan:

  • Studi:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • Seri:
    • SpecificCharacterSet
    • Pengandaian
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • Instance:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • Baris
    • Kolom
    • BitsAllocated
    • NumberOfFrames

Untuk includefield=all, atribut default akan ditampilkan bersama dengan atribut berikut:

  • Studi:
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • Seri:
    • SeriesNumber
    • Lateralitas
    • SeriesDate
    • SeriesTime
  • Instance: semua atribut yang ada dalam instance DICOM, kecuali pengecualian berikut.

Tag urutan DICOM yang berisi lebih dari sekitar 1 MiB data tidak akan ditampilkan dalam respons metadata.

Metadata tidak konsisten/tidak valid

Dalam kasus SearchForStudies/SearchForSeries, ada potensi metadata tingkat studi/seri yang tidak konsisten di beberapa instance. Misalnya, dua instance dapat diupload dengan StudyInstanceUID yang sama, tetapi memiliki StudyDate yang berbeda. Dalam hal ini, perilaku penelusuran tidak ditentukan dengan baik. Penelusuran berdasarkan nilai tersebut mungkin berfungsi dalam beberapa kasus, tetapi tidak dalam kasus lain dan nilai yang ditampilkan dapat bervariasi di berbagai panggilan.

Kode status

Kode Arti
200 (OK) Payload respons berisi representasi untuk semua Target Resource.
400 (Bad Request) Permintaan tidak valid (misalnya, parameter kueri tidak valid).
401 (Tidak Sah) Permintaan tidak memiliki kredensial autentikasi.
403 (Permission Denied) Pengguna yang diautentikasi tidak memiliki akses ke resource ini (atau resource tidak ada).
406 (Tidak Dapat Diterima) Server tidak mendukung salah satu Jenis Media yang Dapat Diterima.
429 (Too Many Requests) Klien melampaui kuota.
503 (Layanan Tidak Tersedia) Server saat ini tidak tersedia atau permintaan melebihi batas waktunya.

Penghapusan

Cloud Healthcare API mendukung jenis tindakan eksklusif berikut:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

Keduanya menggunakan jalur permintaan yang sama dengan rekan WADO-RS-nya (RetrieveStudy, RetrieveSeries, dan RetrieveInstance). Permintaan DELETE digunakan, bukan permintaan HTTP GET. Efeknya adalah studi, rangkaian, atau instance yang ditentukan akan dihapus bersama dengan semua resource DICOM yang ada di dalamnya.

Metode DeleteStudy dan DeleteSeries menampilkan operasi yang berjalan lama yang menghapus semua instance dalam studi atau rangkaian. Perhatikan bahwa instance tidak dapat dimasukkan ke dalam studi atau seri yang sedang dihapus oleh operasi hingga operasi selesai.

Lihat Mengelola operasi yang berjalan lama untuk panduan cara kerja operasi.

Permintaan DeleteInstance yang berhasil akan menampilkan respons kosong.

Kode status

Kode Arti
200 (OK) Resource permintaan telah dihapus.
400 (Bad Request) Permintaan tidak valid.
401 (Tidak Sah) Permintaan tidak memiliki kredensial autentikasi.
403 (Permission Denied) Pengguna yang diautentikasi tidak memiliki akses ke resource ini (atau resource tidak ada).
429 (Too Many Requests) Klien melampaui kuota.
503 (Layanan Tidak Tersedia) Server saat ini tidak tersedia atau permintaan melebihi batas waktunya.

Header yang diterima

Beberapa metode di atas memberikan kemampuan untuk mengontrol format respons menggunakan header HTTP Accept. Pencocokan karakter pengganti didukung di tingkat teratas (misalnya, */*) dan subjenis (misalnya, image/*). Menentukan nilai q juga didukung untuk menunjukkan preferensi relatif. Jika nilai q tidak ditentukan untuk header Accept, nilai tersebut akan ditetapkan ke nilai default 1.0.

Jika beberapa header Accept ditentukan dan ada kesamaan antara header Accept dengan preferensi tertinggi, server akan memilih header Accept. Klien tidak boleh bergantung pada pilihan header Accept server dalam skenario ini.

Class SOP yang didukung

Cloud Healthcare API dapat menyerap dan melakukan pengambilan dasar semua class SOP DICOM. Untuk pengambilan yang memerlukan transkode antara format gambar, lihat sintaksis transfer yang didukung untuk transkode untuk mengetahui daftar sintaksis transfer yang didukung.

Versi Kamus DICOM

Cloud Healthcare API menggunakan kamus DICOM 2025b untuk mengurai tag instance yang di-ingest dan untuk membuat nama kolom saat mengekspor ke BigQuery.

Definisi Bulkdata

Saat mengambil metadata, Cloud Healthcare API akan mengecualikan tag tertentu yang ditetapkan sebagai bulkdata. Sebagai gantinya, tag ini akan ditampilkan bersama metadata dengan BulkDataURI yang memungkinkan pengguna mengambil konten tag ini (lihat RetrieveBulkdata). Berikut adalah definisi yang digunakan oleh Cloud Healthcare API:

  • Tag Data Pixel: (7FE0,0008), (7FE0,0009) (7FE0,0010).
  • Tag apa pun dengan VR OB, OW, atau UN.
  • Tag dengan VR OD, OF, OL, atau OV yang lebih besar dari 2 KiB.
    • Karena alasan lama, tag instance yang sudah di-ingest ke Cloud Healthcare API dapat dianggap sebagai bulkdata jika tag lebih besar dari 256 B (OF dan OL) atau 512 B (OD).
  • Tag dengan VR AT, FD, FL, UL, US, SV, atau UV dan memiliki Multiplisitas Nilai (VM) lebih besar dari 512.
    • Karena alasan lama, tag instance yang sudah diserap ke dalam Cloud Healthcare API dapat dianggap sebagai bulkdata jika VM lebih besar dari 64.

Selain itu, tag berikut dianggap sebagai bulkdata, tetapi tidak memiliki BulkDataURIs saat ditampilkan dari metode metadata, dan konten tidak dapat diambil menggunakan RetrieveBulkdata:

  • Tag dengan VR SQ dan ukuran lebih besar dari sekitar 1 MiB.