Pernyataan kesesuaian DICOM

DICOM yang disimpan dalam Cloud Healthcare API mendukung subset layanan web RESTful yang ditentukan dalam standar DICOM PS3.18 - Layanan Web (umumnya disebut sebagai DICOMweb). Secara khusus, tabel tersebut mendukung Layanan dan Resource 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 Kerja, Layanan Instance Non-Pasien, atau Transaksi Kemampuan apa pun.

Catatan: Tertarik dengan protokol DICOM DIMSE? Kami telah membuat beberapa adaptor menjadi open source untuk memungkinkan penyerapan dan pengambilan data DICOM menggunakan protokol seperti C-Store di GitHub.

Ambil transaksi

Mengambil Transaksi adalah layanan web RESTful untuk mengambil data pencitraan DICOM.

Retrieve Transaction mendukung pengambilan resource berikut:

• Referensi DICOM:
  • Studi
  • Series
  • Instance
  • Frame
  • Data massal
• Resource Metadata
  • Studi
  • Series
  • Instance
• Resource yang Dirender
  • Instance
  • Frame

Rekomendasi tidak mendukung resource Thumbnail.

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

Studi/seri/instance DICOM

Terima Header 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=*

Peringatan: Sintaksis transfer default responsnya adalah Little Endian Eksplisit. Akibatnya, jika file diupload menggunakan sintaksis transfer terkompresi, objek yang ditampilkan akan didekompresi. Hal ini dapat berdampak negatif pada performa dan menyebabkan error untuk sintaksis transfer yang tidak didukung Cloud Healthcare API. Untuk menghindari masalah ini, dan jika sintaksis transfer objek yang ditampilkan tidak penting bagi aplikasi Anda, gunakan multipart/related; type="application/dicom"; transfer-syntax=* Accept Header.

Instance DICOM

Selain Terima Header di atas, RetrieveInstance mendukung jenis konten satu bagian untuk kemudahan:

• 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

Terima Header 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 untuk tidak meminta transcoding 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.

Peringatan: Sintaksis transfer default untuk image/jpeg (JPEG Lossless, 1.2.840.10008.1.2.4.70) tidak didukung, sehingga jika image/jpeg diminta tanpa menentukan sintaksis transfer, error akan ditampilkan.

Resource yang dirender

Terima Header berikut didukung:

• image/jpeg (default)
• image/png

Hanya pengambilan resource Instance atau Frame yang didukung.

Tidak ada parameter URL yang didukung.

Resource metadata

Terima Header berikut didukung:

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

Secara default, RetrieveMetadata tidak menampilkan atribut apa pun yang memiliki Representasi Nilai DICOM dari OB, OD, OF, OL, OW, atau UN. Agar dapat menampilkan BulkDataURIs 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 data massal (Pratinjau)

Pratinjau

Bagian ini menjelaskan fitur Pratinjau yang dapat berubah dan mungkin memiliki dukungan terbatas. Perubahan pada produk dan fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Untuk mengetahui informasi selengkapnya, lihat Persyaratan Penawaran Pra-GA untuk Cloud Healthcare API dan deskripsi tahap peluncuran.

Terima Header 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 dapat dilakukan, 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 Endian Kecil)
• 1.2.840.10008.1.2.1 (Little Endian Eksplisit)
• 1.2.840.10008.1.2.2 (Big Endian VR Eksplisit)
• 1.2.840.10008.1.2.4.50 (Proses Dasar JPEG 1)
• 1.2.840.10008.1.2.4.57 (JPEG Lossless)
• 1.2.840.10008.1.2.4.70 (Nilai Pilihan lossless JPEG 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 (Tanpa Kerugian RLE)

Jika file asli memiliki sintaksis transfer selain yang ada dalam daftar di atas dan Anda meminta transcoding 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.

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

Kode status

Code	Arti
200 (Oke)	Payload respons berisi representasi untuk semua Target Resource.
400 (Permintaan Buruk)	Permintaan tidak valid (misalnya, parameter atau header kueri yang buruk) untuk Target Resource 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 (Tidak Dapat Diterima)	Server tidak mendukung Jenis Media apa pun yang Dapat Diterima.
429 (Terlalu Banyak Permintaan)	Klien melebihi kuota.
503 (Layanan Tidak Tersedia)	Server saat ini tidak tersedia atau permintaan melampaui batas waktunya.

Transaksi toko

Transaksi Toko adalah layanan web RESTful untuk menyimpan data pencitraan DICOM.

Transaksi toko menerima file biner DICOM Bagian 10 secara langsung atau menerima pembagian file DICOM ke dalam metadata (diwakili dalam JSON) dan data massal. Kedua versi ini memiliki semantik 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

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.

Perlu diperhatikan bahwa untuk memudahkan, Transaksi Toko 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 multibagian pertama harus terdiri dari array JSON instance DICOM.

Bagian pertama harus memiliki Jenis Konten 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 di metadata, parameter transfer-syntax dapat dihilangkan.

Elemen DICOM berikut ini wajib ada di setiap instance dalam metadata JSON:

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

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

• 1.2.840.10008.1.2.2 (Big Endian VR Eksplisit)
• 1.2.840.10008.1.2.1.99 (VR Little Endian Eksplisit yang Dikempis)

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 disetel ke BulkDataURI.

Setiap instance dalam metadata JSON dapat memiliki maksimal 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 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 InlineBinary base64. Tindakan ini didukung untuk semua tag kecuali PixelData, yang harus dikirim sebagai bagian data massal. Ketika objek InlineBinary digunakan dalam metadata JSON, sintaksis transfer yang digunakan untuk encoding harus ditentukan dalam Jenis Konten pada bagian metadata JSON.

Server tidak mendapatkan atribut makro deskripsi piksel gambar.

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

Respons

Pada 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 Processing failed akan ditampilkan dengan tag FailureDetail "sudah ada".

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

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

Kode status

Code	Arti
200 (Oke)	Resource berhasil disimpan.
400 (Permintaan Buruk)	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 (Tidak Dapat Diterima)	Server tidak mendukung Jenis Media apa pun yang Dapat Diterima.
409 (Konflik)	Setidaknya satu resource tidak berhasil disimpan (mis. file DICOM tidak valid). Periksa tag FailureDetail dalam isi respons untuk mengetahui informasi selengkapnya.
429 (Terlalu Banyak Permintaan)	Klien melebihi kuota.
503 (Layanan Tidak Tersedia)	Server saat ini tidak tersedia atau permintaan melampaui batas waktunya.

Telusuri transaksi

Transaksi Penelusuran adalah layanan web RESTful untuk mengkueri metadata pencitraan DICOM.

Cloud Healthcare API mendukung penelusuran studi, rangkaian studi, 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/seri 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 pada tag PatientName. Pencocokan fuzzy akan melakukan tokenisasi dan normalisasi nilai PatientName dalam kueri dan nilai yang disimpan. Nilai ini 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 ditetapkan ke daftar atributID yang dipisahkan koma, seperti ID tag atau kata kunci DICOM, atau ditetapkan ke nilai all untuk menampilkan semua tag yang tersedia. Untuk daftar tag yang tersedia, lihat Hasil yang ditampilkan.

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

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

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

Offset Zona Waktu Dari UTC tidak didukung.

Hasil yang ditampilkan

Responsnya 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
• Rangkaian:
  • 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
• Rangkaian:
  • SeriesNumber
  • Lateralitas
  • SeriesDate
  • SeriesTime
• Instance: semua atribut yang ada dalam instance DICOM, kecuali pengecualian berikut.

Secara default, searchForInstances tidak menampilkan atribut apa pun yang memiliki Representasi Nilai DICOM untuk OB, OD, OF, OL, OW, atau UN. Agar dapat menampilkan BulkDataURIs untuk tag yang cocok dengan definisi Bulkdata Pratinjau, gunakan Preview searchForInstances.

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 StudyDates yang berbeda. Dalam hal ini, perilaku penelusuran tidak didefinisikan dengan baik. Menelusuri berdasarkan nilai tersebut mungkin berfungsi dalam beberapa kasus, tetapi tidak pada kasus lainnya dan nilai yang ditampilkan dapat bervariasi di berbagai panggilan.

Kode status

Code	Arti
200 (Oke)	Payload respons berisi representasi untuk semua Target Resource.
400 (Permintaan Buruk)	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 (Tidak Dapat Diterima)	Server tidak mendukung Jenis Media apa pun yang Dapat Diterima.
429 (Terlalu Banyak Permintaan)	Klien melebihi kuota.
503 (Layanan Tidak Tersedia)	Server saat ini tidak tersedia atau permintaan melampaui batas waktunya.

Penghapusan

Cloud Healthcare API mendukung jenis tindakan eksklusif berikut:

• DeleteStudy
• DeleteSeries
• DeleteInstance

Keduanya menggunakan jalur permintaan yang sama dengan pasangan WADO-RS (RetrieveStudy, RetrieveSeries, dan RetrieveInstance). Sebagai ganti permintaan GET HTTP, permintaan DELETE digunakan. Akibatnya, studi, rangkaian, atau instance yang ditentukan akan dihapus bersama dengan semua resource DICOM yang terdapat 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 rangkaian yang sedang dihapus oleh operasi hingga operasi selesai.

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

Permintaan DeleteInstance yang berhasil akan menampilkan respons kosong.

Peringatan: Hasil penelusuran studi dan serial dapat memerlukan waktu beberapa detik untuk diperbarui setelah instance dihapus menggunakan DeleteInstance.

Kode status

Code	Arti
200 (Oke)	Resource permintaan telah dihapus.
400 (Permintaan Buruk)	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 (Terlalu Banyak Permintaan)	Klien melebihi kuota.
503 (Layanan Tidak Tersedia)	Server saat ini tidak tersedia atau permintaan melampaui batas waktunya.

Terima header

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

Jika beberapa header Accept ditentukan dan ada ikatan antara header Accept preferensi tertinggi, server akan memilih header Accept. Dalam skenario ini, klien tidak boleh bergantung pada pilihan header Accept server.

Class SOP yang didukung

Cloud Healthcare API dapat menyerap dan melakukan pengambilan dasar semua class SOP DICOM. Untuk mengetahui informasi tentang cara mengambil transcoding antar-format gambar, lihat sintaksis transfer yang didukung untuk transcoding untuk mengetahui daftar sintaksis transfer yang didukung.

Pembatasan Nilai Tag

Nilai untuk tag BitsAllocated harus kelipatan 8 untuk pengambilan frame.

Definisi Tag Bulkdata (Pratinjau)

Pratinjau

Bagian ini menjelaskan fitur Pratinjau yang dapat berubah dan mungkin memiliki dukungan terbatas. Perubahan pada produk dan fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Untuk mengetahui informasi selengkapnya, lihat Persyaratan Penawaran Pra-GA untuk Cloud Healthcare API dan deskripsi tahap peluncuran.

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

• Tag apa pun dengan VR OB, OW, atau UN.
• Tag dengan VR AT, FD, FL, OD, OF, OL, UL, atau US dan memiliki Multiplisitas Nilai (VM) lebih besar dari 64.

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

• Tag PixelData.
• Tag apa pun dengan VR OD, OF, atau OL.
• Tag dengan VR SQ dan ukuran lebih besar dari sekitar 1 MiB.