Pernyataan kesesuaian DICOM

Penyimpanan DICOM dalam Cloud Healthcare API mendukung sebagian layanan web RESTful yang ditentukan dalam standar DICOM PS3.18 - Layanan Web (biasanya disebut sebagai DICOMweb). Secara khusus, layanan ini mendukung Layanan dan Referensi Studi (sebelumnya disebut sebagai layanan WADO-RS, STOW-RS, dan QIDO-RS).

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

Cloud Healthcare API tidak mendukung Layanan URI, Layanan Daftar Tugas, Layanan Instance Non-Pasien, atau Transaksi Kemampuan apa pun.

Mengambil transaksi

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

Retrieve Transaction mendukung pengambilan resource berikut:

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

Fitur ini tidak mendukung resource Thumbnail.

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

Studi/rangkaian/instance DICOM

Header Terima 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 Terima 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 Terima 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 Terima berikut didukung:

  • image/jpeg (default)
  • image/png

Hanya pengambilan resource Instance atau Frame yang didukung.

Tidak ada parameter URL yang didukung.

Resource metadata

Header Terima berikut didukung:

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

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

Secara default, RetrieveMetadata tidak menampilkan atribut apa pun yang memiliki Representasi Nilai DICOM OB, OW, atau UN. Untuk menampilkan BulkDataURI untuk tag yang cocok dengan Definisi bulkdata Pratinjau, gunakan Preview version.

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

Resource bulkdata (Pratinjau)

Header Terima 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 (Little Endian Implisit)
  • 1.2.840.10008.1.2.1 (Little Endian Eksplisit)
  • 1.2.840.10008.1.2.2 (VR Big Endian Eksplisit)
  • 1.2.840.10008.1.2.4.50 (Proses Dasar Pengukuran JPEG 1)
  • 1.2.840.10008.1.2.4.57 (JPEG Lossless)
  • 1.2.840.10008.1.2.4.70 (JPEG Lossless Selection Value 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 tercantum dalam daftar di atas dan Anda meminta transcoding ke format lain, error akan ditampilkan.

Cloud Healthcare API tidak dapat mentranskode 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 Data Piksel Mengambang (7FE0,0008), Data Piksel Mengambang Ganda (7FE0,0009) hanya dapat ditranskode di antara format native.

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

Kode status

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

Menyimpan transaksi

Transaksi Penyimpanan 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 (diwakili dalam JSON) dan data massal. 2 versi ini memiliki semantik yang berbeda yang dijelaskan di bagian berikut.

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

File biner DICOM bagian 10

Jenis Konten berikut didukung:

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

Server tidak melakukan pemaksaan atau penggantian atribut.

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 memudahkan, Transaksi Penyimpanan juga menerima satu bagian permintaan HTTP dengan satu instance DICOM dengan jenis konten application/dicom. Ini bukan bagian dari standar DICOMweb resmi.

Lihat Menyimpan instance DICOM untuk panduan cara terkait.

Permintaan data massal dan metadata JSON

Saat menyimpan instance menggunakan metadata JSON dan data massal, bagian multibagian 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 ditetapkan ke ISO_IR 192, dan metadata JSON harus dienkode dalam UTF-8 unicode. TransferSyntaxUID dapat ditetapkan ke sintaksis transfer yang valid, kecuali untuk sintaksis transfer berikut yang tidak didukung:

  • 1.2.840.10008.1.2.2 (Big Endian VR Eksplisit)
  • 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 berikut yang memiliki header Content-Location yang ditetapkan ke BulkDataURI.

Setiap instance dalam metadata JSON dapat memiliki maksimal satu BulkDataURI. Tidak boleh ada BulkDataURI duplikat dalam metadata JSON. Data massal gambar yang dikompresi 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 Konten 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 memperoleh atribut makro deskripsi piksel gambar.

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

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 "sudah ada".

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 yang tidak didukung).
401 (Tidak Sah) Permintaan tidak memiliki kredensial autentikasi.
403 (Izin Ditolak) Pengguna yang diautentikasi tidak memiliki akses ke resource ini (atau resource tidak ada).
406 (Not Acceptable) Server tidak mendukung Jenis Media yang Dapat Diterima.
409 (Konflik) Setidaknya satu resource tidak berhasil disimpan (misalnya, file DICOM yang tidak valid). Periksa tag FailureDetail di isi respons untuk mengetahui informasi selengkapnya.
429 (Too Many Requests) Klien melampaui kuota-nya.
503 (Layanan Tidak Tersedia) Server saat ini tidak tersedia atau permintaan melebihi batas waktunya.

Menelusuri transaksi

Transaksi Penelusuran 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
    • Modalitas
  • Instance: semua istilah penelusuran tingkat studi/serial dan
    • SOPInstanceUID

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

Parameter URL tambahan berikut didukung:

  • fuzzymatching: Jika ditetapkan ke true, pencocokan fuzzy akan diterapkan ke tag PatientName. Pencocokan fuzzy akan melakukan tokenisasi dan normalisasi nilai PatientName dalam kueri dan nilai yang disimpan. Token ini akan cocok jika token penelusuran adalah 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 ditetapkan ke daftar attributeID yang dipisahkan koma, seperti ID tag atau kata kunci DICOM, atau ditetapkan ke nilai all untuk menampilkan semua tag yang tersedia. Untuk mengetahui daftar tag yang tersedia, lihat Hasil yang ditampilkan.

Pengelompokan 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/serial dan 50.000 untuk instance. Jumlah hasil default adalah 100 untuk studi/serial 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
    • Modalitas
    • 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, tidak termasuk pengecualian berikut.

Secara default, searchForInstances tidak menampilkan atribut apa pun yang memiliki Representasi Nilai DICOM OB, OW, atau UN. Untuk menampilkan BulkDataURI untuk tag yang cocok dengan Definisi bulkdata Pratinjau, gunakan Pratinjau searchForInstances.

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

Metadata yang tidak konsisten/tidak valid

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

Kode status

Kode Arti
200 (OK) Payload respons berisi representasi untuk semua Resource Target.
400 (Bad Request) Permintaan tidak valid (misalnya, parameter kueri tidak valid).
401 (Tidak Sah) Permintaan tidak memiliki kredensial autentikasi.
403 (Izin Ditolak) Pengguna yang diautentikasi tidak memiliki akses ke resource ini (atau resource tidak ada).
406 (Not Acceptable) Server tidak mendukung Jenis Media yang Dapat Diterima.
429 (Too Many Requests) Klien melampaui kuota-nya.
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

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

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

Lihat Mengelola operasi yang berjalan lama untuk panduan cara melakukan 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 (Izin Ditolak) Pengguna yang diautentikasi tidak memiliki akses ke resource ini (atau resource tidak ada).
429 (Too Many Requests) Klien melampaui kuota-nya.
503 (Layanan Tidak Tersedia) Server saat ini tidak tersedia atau permintaan melebihi batas waktunya.

Menerima header

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 dari semua class SOP DICOM. Untuk pengambilan apa pun yang memerlukan transcoding antarformat gambar, lihat sintaksis transfer yang didukung untuk transcoding guna mengetahui daftar sintaksis transfer yang didukung.

Versi Kamus DICOM

Cloud Healthcare API menggunakan kamus DICOM 2022d untuk mengurai tag instance yang diserap.

Untuk ekspor ke BigQuery, Cloud Healthcare API menggunakan kamus DICOM 2024c untuk membuat nama kolom.

Bulkdata Tag Definition (Pratinjau)

Saat mengambil metadata dengan metode Pratinjau, Cloud Healthcare API akan mengecualikan tag tertentu yang ditentukan 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 apa pun: (7FE0,0008), (7FE0,0009) (7FE0,0010).
  • Semua tag dengan VR OB, OW, atau UN.
  • Tag dengan VR OD, OF, atau OL yang lebih besar dari 2 KiB.
    • Karena alasan lama, tag instance yang telah diserap ke dalam 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, atau US dan memiliki Multiplikasi Nilai (VM) lebih besar dari 512.
    • Karena alasan lama, tag instance yang telah 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 BulkDataURI saat ditampilkan dari metode metadata, dan konten tidak dapat diambil menggunakan RetrieveBulkdata:

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