Pernyataan Kesuaian DICOM v1
Catatan
API versi 2 adalah versi API terbaru dan harus digunakan sebagai pengganti v1. Lihat Pernyataan Kesuaian DICOM v2 untuk detailnya.
Server Pencitraan Medis untuk DICOM® mendukung subset Standar DICOMweb. Dukungan meliputi:
Selain itu, API nonstandar berikut didukung:
Layanan ini menggunakan penerapan versi REST API. Versi REST API harus ditentukan secara eksplisit sebagai bagian dari URL dasar, seperti dalam contoh berikut:
https://<service_url>/v<version>/studies
Versi pernyataan kesesuaian v1
ini sesuai dengan versi REST API.
Untuk informasi selengkapnya tentang cara menentukan versi saat membuat permintaan, lihat Dokumentasi Penerapan Versi API.
Anda dapat menemukan contoh permintaan untuk transaksi yang didukung di koleksi Postman.
Sanitasi yang Dapat Dilacak
Layanan mengabaikan File 128-byte Preamble, dan mengganti kontennya dengan karakter null. Perilaku ini memastikan bahwa tidak ada file yang diteruskan melalui layanan yang rentan terhadap kerentanan yang berbahaya. Namun, sanitasi yang dapat dilacak ini juga berarti bahwa pembatalan yang digunakan untuk mengodekan konten format ganda seperti TIFF tidak dapat digunakan dengan layanan.
Layanan Studi
Layanan Studi memungkinkan pengguna untuk menyimpan, mengambil, dan mencari Studi, Seri, dan Instans DICOM. Kami menambahkan transaksi Hapus nonstandar untuk mengaktifkan siklus hidup sumber daya penuh.
Simpan (STOW-RS)
Transaksi ini menggunakan metode POST atau PUT untuk menyimpan representasi studi, seri, dan instans yang terkandung dalam payload permintaan.
Metode | Jalur | Deskripsi |
---|---|---|
POST | .. /Studi | Menyimpan instans. |
POST | .. /studies/{study} | Simpan instans untuk studi tertentu. |
TARUH | .. /Studi | Instans upsert. |
TARUH | .. /studies/{study} | Instans upsert untuk studi tertentu. |
Parameter study
sesuai dengan atribut DICOM StudyInstanceUID. Jika ditentukan, instans apa pun yang bukan milik studi yang disediakan ditolak dengan 43265
kode peringatan.
Header berikut Accept
untuk respons didukung:
application/dicom+json
Header berikut Content-Type
didukung:
multipart/related; type="application/dicom"
application/dicom
Catatan
Server tidak akan memaksa atau mengganti atribut yang bertentangan dengan data yang ada untuk permintaan POST. Semua data disimpan sebagaimana disediakan. Untuk permintaan upsert (PUT), data yang ada digantikan oleh data baru yang diterima.
Menyimpan atribut yang diperlukan
Elemen DICOM berikut harus ada di setiap file DICOM yang mencoba disimpan:
StudyInstanceUID
SeriesInstanceUID
SOPInstanceUID
SOPClassUID
PatientID
Catatan
Semua UID harus panjangnya antara 1 dan 64 karakter, dan hanya berisi karakter numerik alfa atau karakter khusus berikut: .
, -
. PatientID
divalidasi berdasarkan jenisnya LO
VR
.
Setiap file yang disimpan harus memiliki kombinasi unik dari StudyInstanceUID
, , SeriesInstanceUID
dan SopInstanceUID
. Kode 45070
peringatan dikembalikan jika file dengan pengidentifikasi yang sama sudah ada.
Hanya sintaks transfer dengan Representasi Nilai eksplisit yang diterima.
Menyimpan kode status respons
Kode | Deskripsi |
---|---|
200 (OK) |
Semua instans SOP dalam permintaan disimpan. |
202 (Accepted) |
Beberapa instans dalam permintaan disimpan tetapi yang lain gagal. |
204 (No Content) |
Tidak ada konten yang disediakan dalam permintaan transaksi toko. |
400 (Bad Request) |
Permintaan diformat dengan buruk. Misalnya, pengidentifikasi instans studi yang disediakan tidak sesuai dengan format UID yang diharapkan. |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
406 (Not Acceptable) |
Header yang ditentukan Accept tidak didukung. |
409 (Conflict) |
Tidak ada instans dalam permintaan transaksi toko yang disimpan. |
415 (Unsupported Media Type) |
Yang disediakan Content-Type tidak didukung. |
503 (Service Unavailable) |
Layanan tidak tersedia atau sibuk. Coba lagi nanti. |
Menyimpan payload respons
Payload respons mengisi himpunan data DICOM dengan elemen berikut:
Tag | Nama | Deskripsi |
---|---|---|
(0008, 1190) | RetrieveURL |
URL Ambil studi jika StudyInstanceUID disediakan dalam permintaan toko dan setidaknya satu instans berhasil disimpan. |
(0008, 1198) | FailedSOPSequence |
Urutan instans yang gagal disimpan. |
(0008, 1199) | ReferencedSOPSequence |
Urutan instans tersimpan. |
Setiap himpunan FailedSOPSequence
data dalam memiliki elemen berikut (jika file DICOM yang mencoba disimpan dapat dibaca):
Tag | Nama | Deskripsi |
---|---|---|
(0008, 1150) | ReferencedSOPClassUID |
Pengidentifikasi unik kelas SOP dari instans yang gagal disimpan. |
(0008, 1155) | ReferencedSOPInstanceUID |
Pengidentifikasi unik instans SOP dari instans yang gagal disimpan. |
(0008, 1197) | FailureReason |
Kode alasan mengapa instans ini gagal disimpan. |
(0074, 1048) | FailedAttributesSequence |
Urutan ErrorComment yang mencakup alasan untuk setiap atribut yang gagal. |
Setiap himpunan ReferencedSOPSequence
data dalam memiliki elemen berikut:
Tag | Nama | Deskripsi |
---|---|---|
(0008, 1150) | ReferencedSOPClassUID |
Pengidentifikasi unik kelas SOP dari instans yang gagal disimpan. |
(0008, 1155) | ReferencedSOPInstanceUID |
Pengidentifikasi unik instans SOP dari instans yang gagal disimpan. |
(0008, 1190) | RetrieveURL |
URL pengambilan instans ini di server DICOM. |
Contoh respons dengan Accept
header application/dicom+json
:
{
"00081190":
{
"vr":"UR",
"Value":["http://localhost/studies/d09e8215-e1e1-4c7a-8496-b4f6641ed232"]
},
"00081198":
{
"vr":"SQ",
"Value":
[{
"00081150":
{
"vr":"UI","Value":["cd70f89a-05bc-4dab-b6b8-1f3d2fcafeec"]
},
"00081155":
{
"vr":"UI",
"Value":["22c35d16-11ce-43fa-8f86-90ceed6cf4e7"]
},
"00081197":
{
"vr":"US",
"Value":[43265]
}
}]
},
"00081199":
{
"vr":"SQ",
"Value":
[{
"00081150":
{
"vr":"UI",
"Value":["d246deb5-18c8-4336-a591-aeb6f8596664"]
},
"00081155":
{
"vr":"UI",
"Value":["4a858cbb-a71f-4c01-b9b5-85f88b031365"]
},
"00081190":
{
"vr":"UR",
"Value":["http://localhost/studies/d09e8215-e1e1-4c7a-8496-b4f6641ed232/series/8c4915f5-cc54-4e50-aa1f-9b06f6e58485/instances/4a858cbb-a71f-4c01-b9b5-85f88b031365"]
}
}]
}
}
Menyimpan kode alasan kegagalan
Kode | Deskripsi |
---|---|
272 |
Transaksi penyimpanan tidak menyimpan instans karena kegagalan umum dalam memproses operasi. |
43264 |
Instans DICOM gagal dalam validasi. |
43265 |
Instans StudyInstanceUID yang disediakan tidak cocok dengan yang ditentukan StudyInstanceUID dalam permintaan penyimpanan. |
45070 |
Instans DICOM dengan , , SeriesInstanceUID dan SopInstanceUID yang sama StudyInstanceUID sudah disimpan. Jika Anda ingin memperbarui konten, hapus instans ini terlebih dahulu. |
45071 |
Instans DICOM sedang dibuat oleh proses lain, atau upaya sebelumnya untuk membuat gagal dan proses pembersihan tidak selesai. Hapus instans terlebih dahulu sebelum mencoba membuat lagi. |
Menyimpan kode alasan peringatan
Kode | Deskripsi |
---|---|
45063 |
Himpunan Data instans DICOM tidak cocok dengan Kelas SOP. StudiEs Store Transaction (Bagian 10.5) mengamati bahwa Himpunan Data tidak cocok dengan batasan Kelas SOP selama penyimpanan instans. |
Simpan Kode Kesalahan
Kode | Deskripsi |
---|---|
100 |
Atribut instans yang disediakan tidak memenuhi kriteria validasi. |
Ambil (WADO-RS)
Transaksi Ambil ini menawarkan dukungan untuk mengambil studi, seri, instans, dan bingkai tersimpan berdasarkan referensi.
Metode | Jalur | Deskripsi |
---|---|---|
GET | .. /studies/{study} | Mengambil semua instans dalam sebuah studi. |
GET | .. /studies/{study}/metadata | Mengambil metadata untuk semua instans dalam sebuah studi. |
GET | .. /studies/{study}/series/{series} | Mengambil semua instans dalam seri. |
GET | .. /studies/{study}/series/{series}/metadata | Mengambil metadata untuk semua instans dalam seri. |
GET | .. /studies/{study}/series/{series}/instances/{instance} | Mengambil satu instans. |
GET | .. /studies/{study}/series/{series}/instances/{instance}/metadata | Mengambil metadata untuk satu instans. |
GET | .. /studies/{study}/series/{series}/instances/{instance}/rendered | Mengambil instans yang dirender ke dalam format gambar |
GET | .. /studies/{study}/series/{series}/instances/{instance}/frames/{frames} | Mengambil satu atau banyak bingkai dari satu instans. Untuk menentukan lebih dari satu bingkai, gunakan koma untuk memisahkan setiap bingkai yang akan dikembalikan. Contohnya,/studies/1/series/2/instance/3/frames/4,5,6 . |
GET | .. /studies/{study}/series/{series}/instances/{instance}/frames/{frame}/rendered | Mengambil satu bingkai yang dirender ke dalam format gambar. |
Mengambil instans dalam studi atau seri
Header berikut Accept
didukung untuk mengambil instans dalam studi atau seri:
multipart/related; type="application/dicom"; transfer-syntax=*
multipart/related; type="application/dicom";
(ketika sintaks transfer tidak ditentukan, 1.2.840.10008.1.2.1 digunakan sebagai default)multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1
multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
*/*
(ketika sintaks transfer tidak ditentukan,*
digunakan sebagai default dan mediaType default keapplication/dicom
)
Mengambil Instans
Header berikut Accept
didukung untuk mengambil instans tertentu:
application/dicom; transfer-syntax=*
multipart/related; type="application/dicom"; transfer-syntax=*
application/dicom;
(ketika sintaks transfer tidak ditentukan,1.2.840.10008.1.2.1
digunakan sebagai default)multipart/related; type="application/dicom"
(ketika sintaks transfer tidak ditentukan,1.2.840.10008.1.2.1
digunakan sebagai default)application/dicom; transfer-syntax=1.2.840.10008.1.2.1
multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1
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.90
*/*
(ketika sintaks transfer tidak ditentukan,*
digunakan sebagai default dan mediaType default keapplication/dicom
)
Mengambil Bingkai
Header berikut Accept
didukung untuk mengambil bingkai:
multipart/related; type="application/octet-stream"; transfer-syntax=*
multipart/related; type="application/octet-stream";
(ketika sintaks transfer tidak ditentukan,1.2.840.10008.1.2.1
digunakan sebagai default)multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1
multipart/related; type="image/jp2";
(ketika sintaks transfer tidak ditentukan,1.2.840.10008.1.2.4.90
digunakan sebagai default)multipart/related; type="image/jp2";transfer-syntax=1.2.840.10008.1.2.4.90
*/*
(ketika sintaks transfer tidak ditentukan,*
digunakan sebagai default dan mediaType default keapplication/octet-stream
)
Mengambil sintaks transfer
Ketika sintaks transfer yang diminta berbeda dari file asli, file asli ditranskodekan ke sintaks transfer yang diminta. File asli harus menjadi salah satu format berikut agar transcoding berhasil, jika tidak, transcoding mungkin gagal:
- 1.2.840.10008.1.2 (Implisit Little Endian)
- 1.2.840.10008.1.2.1 (Little Endian Explicit)
- 1.2.840.10008.1.2.2 (VR Eksplisit Big Endian)
- 1.2.840.10008.1.2.4.50 (Proses Garis Besar JPEG 1)
- 1.2.840.10008.1.2.4.57 (JPEG Lossless)
- 1.2.840.10008.1.2.4.70 (Nilai Pilihan TANPA Kerugian JPEG 1)
- 1.2.840.10008.1.2.4.90 (JPEG 2000 Lossless Only)
- 1.2.840.10008.1.2.4.91 (JPEG 2000)
- 1.2.840.10008.1.2.5 (RLE Lossless)
Hasil yang tidak didukung transfer-syntax
dalam 406 Not Acceptable
.
Mengambil metadata (untuk studi, seri, atau instans)
Header berikut Accept
didukung untuk mengambil metadata untuk studi, seri, atau instans:
application/dicom+json
Mengambil metadata tidak mengembalikan atribut dengan representasi nilai berikut:
Nama VR | Deskripsi |
---|---|
OB | Byte Lainnya |
OD | Ganda Lainnya |
OF | Float Lainnya |
OL | Panjang Lainnya |
OV | Lainnya 64-Bit Sangat Panjang |
OW | Kata Lain |
UN | Tidak dikenal |
Mengambil validasi cache metadata (untuk studi, seri, atau instans)
Validasi cache didukung menggunakan ETag
mekanisme . Dalam respons terhadap permintaan metadata, ETag dikembalikan sebagai salah satu header. ETag ini dapat di-cache dan ditambahkan sebagai If-None-Match
header di permintaan selanjutnya untuk metadata yang sama. Dua jenis respons dimungkinkan jika data ada:
- Data tidak berubah sejak permintaan terakhir:
HTTP 304 (Not Modified)
respons dikirim tanpa isi respons. - Data berubah sejak permintaan terakhir:
HTTP 200 (OK)
respons dikirim dengan ETag yang diperbarui. Data yang diperlukan juga dikembalikan sebagai bagian dari isi.
Mengambil gambar yang dirender (misalnya atau bingkai)
Header berikut Accept
didukung untuk mengambil gambar yang dirender instans atau bingkai:
image/jpeg
image/png
Jika tidak ada Accept
header yang ditentukan, layanan merender image/jpeg
secara default.
Layanan ini hanya mendukung penyajian satu bingkai. Jika penyajian diminta untuk instans dengan beberapa bingkai, maka hanya bingkai pertama yang dirender sebagai gambar secara default.
Saat menentukan bingkai tertentu yang akan dikembalikan, pengindeksan bingkai dimulai pada 1.
Parameter quality
kueri juga didukung. Nilai bilangan bulat antara 1
dan 100
inklusif (1 menjadi kualitas terburuk, dan 100 menjadi kualitas terbaik) mungkin diteruskan sebagai nilai untuk parameter kueri. Parameter ini digunakan untuk gambar yang dirender sebagai jpeg
, dan diabaikan untuk png
permintaan render. Jika tidak menentukan parameter default ke 100
.
Mengambil kode status respons
Kode | Deskripsi |
---|---|
200 (OK) |
Semua data yang diminta diambil. |
304 (Not Modified) |
Data yang diminta belum dimodifikasi sejak permintaan terakhir. Konten tidak ditambahkan ke isi respons dalam kasus seperti itu. Untuk informasi selengkapnya, lihat bagian di atas Mengambil Validasi Cache Metadata (untuk Studi, Seri, atau Instans). |
400 (Bad Request) |
Permintaan diformat dengan buruk. Misalnya, pengidentifikasi instans studi yang disediakan tidak sesuai dengan format UID yang diharapkan, atau pengodean sintaks transfer yang diminta tidak didukung. |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
404 (Not Found) |
Sumber daya DICOM yang ditentukan tidak dapat ditemukan, atau untuk permintaan yang dirender, instans tidak berisi data piksel. |
406 (Not Acceptable) |
Header yang ditentukan Accept tidak didukung, atau untuk permintaan yang dirender dan transkode file yang diminta terlalu besar. |
503 (Service Unavailable) |
Layanan tidak tersedia atau sibuk. Coba lagi nanti. |
Pencarian (QIDO-RS)
Kueri berdasarkan ID untuk Objek DICOM (QIDO) memungkinkan Anda mencari studi, seri, dan instans berdasarkan atribut.
Metode | Jalur | Deskripsi |
---|---|---|
Cari Studi | ||
GET | .. /Studi?... | Mencari studi |
Cari Seri | ||
GET | .. /seri?... | Cari seri |
GET | .. /studies/{study}/series?... | Mencari seri dalam sebuah studi |
Cari Instans | ||
GET | .. /Contoh?... | Mencari instans |
GET | .. /studies/{study}/instances?... | Mencari instans dalam studi |
GET | .. /studies/{study}/series/{series}/instances?... | Mencari instans dalam seri |
Header berikut Accept
didukung untuk mencari:
application/dicom+json
Parameter pencarian yang didukung
Parameter berikut untuk setiap kueri didukung:
Tombol | Nilai Dukungan | Jumlah yang Diizinkan | Deskripsi |
---|---|---|---|
{attributeID}= |
{value} |
0...N | Cari atribut/pencocokan nilai dalam kueri. |
includefield= |
{attributeID} all |
0...N | Atribut lain yang akan dikembalikan dalam respons. Tag publik dan privat didukung. Saat all disediakan, lihat Respons Pencarian untuk informasi selengkapnya tentang atribut mana yang dikembalikan untuk setiap jenis kueri.Jika campuran {attributeID} dan all disediakan, server default menggunakan all . |
limit= |
{value} |
0..1 | Nilai bilangan bulat untuk membatasi jumlah nilai yang dikembalikan dalam respons. Nilai dapat berada di antara rentang 1 >= x <= 200. Default ke 100. |
offset= |
{value} |
0..1 | Lewati {value} hasil.Jika offset disediakan lebih besar dari jumlah hasil kueri pencarian, respons 204 (tanpa konten) dikembalikan. |
fuzzymatching= |
true / false |
0..1 | Jika pencocokan fuzzy true diterapkan ke atribut PatientName. Ini melakukan kecocokan kata awalan dari bagian nama apa pun di dalam nilai PatientName. Misalnya, jika PatientName adalah "John^Doe", maka "joh", "do", "jo do", "Doe" dan "John Doe" semuanya cocok. Namun, "ohn" tidak cocok. |
Atribut yang dapat dicari
Kami mendukung pencarian atribut dan jenis pencarian berikut.
Kata Kunci Atribut | Semua Studi | Semua Seri | Semua Instans | Seri Studi | Instans Studi | Instans Seri Studi |
---|---|---|---|---|---|---|
StudyInstanceUID |
X | X | X | |||
PatientName |
X | X | X | |||
PatientID |
X | X | X | |||
PatientBirthDate |
X | X | X | |||
AccessionNumber |
X | X | X | |||
ReferringPhysicianName |
X | X | X | |||
StudyDate |
X | X | X | |||
StudyDescription |
X | X | X | |||
ModalitiesInStudy |
X | X | X | |||
SeriesInstanceUID |
X | X | X | X | ||
Modality |
X | X | X | X | ||
PerformedProcedureStepStartDate |
X | X | X | X | ||
ManufacturerModelName |
X | X | X | X | ||
SOPInstanceUID |
X | X | X |
Pencocokan pencarian
Kami mendukung jenis pencocokan berikut.
Jenis Pencarian | Atribut yang Didukung | Contoh |
---|---|---|
Kueri Rentang | StudyDate /PatientBirthDate |
{attributeID}={value1}-{value2} . Untuk nilai tanggal/waktu, kami mendukung rentang inklusif pada tag. Ini dipetakan ke attributeID >= {value1} AND attributeID <= {value2} . Jika {value1} tidak ditentukan, semua kemunculan tanggal/waktu sebelum dan termasuk {value2} dicocokkan. Demikian juga, jika {value2} tidak ditentukan, semua kemunculan {value1} dan tanggal/waktu berikutnya dicocokkan. Namun, salah satu nilai ini harus ada. {attributeID}={value1}- dan {attributeID}=-{value2} valid, bagaimanapun, {attributeID}=- tidak valid. |
Sama Persis | Semua atribut yang didukung | {attributeID}={value1} |
Kecocokan Fuzzy | PatientName , ReferringPhysicianName |
Cocok dengan komponen nama apa pun yang dimulai dengan nilai . |
ID Atribut
Tag dapat dikodekan dalam beberapa cara untuk parameter kueri. Kami telah menerapkan sebagian standar seperti yang didefinisikan dalam PS3.18 6.7.1.1.1. Pengodean berikut untuk tag didukung:
Nilai | Contoh |
---|---|
{group}{element} |
0020000D |
{dicomKeyword} |
StudyInstanceUID |
Contoh pencarian kueri untuk instans:
../instances?Modality=CT&00280011=512&includefield=00280010&limit=5&offset=0
Respons pencarian
Responsnya adalah array himpunan data DICOM. Bergantung pada sumber daya, secara default atribut berikut dikembalikan:
Tag Studi Default
Tag | Nama Atribut |
---|---|
(0008, 0005) | SpecificCharacterSet |
(0008, 0020) | StudyDate |
(0008, 0030) | StudyTime |
(0008, 0050) | AccessionNumber |
(0008, 0056) | InstanceAvailability |
(0008, 0090) | ReferringPhysicianName |
(0008, 0201) | TimezoneOffsetFromUTC |
(0010, 0010) | PatientName |
(0010, 0020) | PatientID |
(0010, 0030) | PatientBirthDate |
(0010, 0040) | PatientSex |
(0020, 0010) | StudyID |
(0020, 000D) | StudyInstanceUID |
Tag Seri Default
Tag | Nama Atribut |
---|---|
(0008, 0005) | SpecificCharacterSet |
(0008, 0060) | Modality |
(0008, 0201) | TimezoneOffsetFromUTC |
(0008, 103E) | SeriesDescription |
(0020, 000E) | SeriesInstanceUID |
(0040, 0244) | PerformedProcedureStepStartDate |
(0040, 0245) | PerformedProcedureStepStartTime |
(0040, 0275) | RequestAttributesSequence |
Tag Instans Default
Tag | Nama Atribut |
---|---|
(0008, 0005) | SpecificCharacterSet |
(0008, 0016) | SOPClassUID |
(0008, 0018) | SOPInstanceUID |
(0008, 0056) | InstanceAvailability |
(0008, 0201) | TimezoneOffsetFromUTC |
(0020, 0013) | InstanceNumber |
(0028, 0010) | Rows |
(0028, 0011) | Columns |
(0028, 0100) | BitsAllocated |
(0028, 0008) | NumberOfFrames |
Jika includefield=all
, atribut berikut disertakan bersama dengan atribut default. Bersama dengan atribut default, ini adalah daftar lengkap atribut yang didukung di setiap tingkat sumber daya.
Tag Studi Ekstra
Tag | Nama Atribut |
---|---|
(0008, 1030) | Study Description |
(0008, 0063) | AnatomicRegionsInStudyCodeSequence |
(0008, 1032) | ProcedureCodeSequence |
(0008, 1060) | NameOfPhysiciansReadingStudy |
(0008, 1080) | AdmittingDiagnosesDescription |
(0008, 1110) | ReferencedStudySequence |
(0010, 1010) | PatientAge |
(0010, 1020) | PatientSize |
(0010, 1030) | PatientWeight |
(0010, 2180) | Occupation |
(0010, 21B0) | AdditionalPatientHistory |
Tag Seri Lainnya
Tag | Nama Atribut |
---|---|
(0020, 0011) | SeriesNumber |
(0020, 0060) | Laterality |
(0008, 0021) | SeriesDate |
(0008, 0031) | SeriesTime |
Atribut berikut dikembalikan:
- Semua parameter kueri dan UID yang cocok di url sumber daya.
IncludeField
atribut yang didukung di tingkat sumber daya tersebut.- Jika sumber daya target adalah
All Series
, makaStudy
atribut tingkat juga dikembalikan. - Jika sumber daya target adalah
All Instances
, makaStudy
atribut tingkat jugaSeries
dikembalikan. - Jika sumber daya target adalah
Study's Instances
, makaSeries
atribut tingkat juga dikembalikan. NumberOfStudyRelatedInstances
atribut agregat didukung dalamStudy
tingkatincludeField
.NumberOfSeriesRelatedInstances
atribut agregat didukung dalamSeries
tingkatincludeField
.
Cari kode respons
API kueri mengembalikan salah satu kode status berikut dalam respons:
Kode | Deskripsi |
---|---|
200 (OK) |
Payload respons berisi semua sumber daya yang cocok. |
204 (No Content) |
Pencarian berhasil diselesaikan tetapi tidak mengembalikan hasil. |
400 (Bad Request) |
Server tidak dapat melakukan kueri karena komponen kueri tidak valid. Isi respons berisi detail kegagalan. |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
503 (Service Unavailable) |
Layanan tidak tersedia atau sibuk. Coba lagi nanti. |
Catatan lain
- Kueri menggunakan
TimezoneOffsetFromUTC (00080201)
tidak didukung. - API kueri tidak mengembalikan
413 (request entity too large)
. Jika batas respons kueri yang diminta berada di luar rentang yang dapat diterima, permintaan buruk akan dikembalikan. Apa pun yang diminta dalam rentang yang dapat diterima diselesaikan. - Ketika sumber daya target adalah Studi/Seri, ada potensi metadata tingkat studi/seri yang tidak konsisten di beberapa instans. Misalnya, dua instans dapat memiliki patientName yang berbeda. Dalam hal ini, yang terbaru menang dan Anda hanya dapat mencari pada data terbaru.
- Hasil halaman dioptimalkan untuk mengembalikan instans terbaru yang cocok terlebih dahulu, ini mungkin mengakibatkan rekaman duplikat di halaman berikutnya jika data yang lebih baru yang cocok dengan kueri ditambahkan.
- Pencocokan peka huruf besar/kecil dan aksen sensitif untuk jenis VR PN.
- Pencocokan peka huruf besar/kecil dan aksen sensitif untuk jenis VR string lainnya.
- Hanya nilai pertama yang diindeks dari satu elemen data bernilai yang salah memiliki beberapa nilai.
Hapus
Transaksi ini bukan bagian dari DICOMwe Standard resmi. Ini menggunakan metode DELETE untuk menghapus representasi Studi, Seri, dan Instans dari penyimpanan.
Metode | Jalur | Deskripsi |
---|---|---|
DELETE | .. /studies/{study} | Hapus semua instans untuk studi tertentu. |
DELETE | .. /studies/{study}/series/{series} | Hapus semua instans untuk seri tertentu dalam sebuah studi. |
DELETE | .. /studies/{study}/series/{series}/instances/{instance} | Menghapus instans tertentu dalam seri. |
study
Parameter , series
, dan instance
sesuai dengan atribut StudyInstanceUID
DICOM , , SeriesInstanceUID
dan SopInstanceUID
masing-masing.
Tidak ada batasan pada header, header, Content-Type
atau konten isi permintaanAccept
.
Catatan
Setelah transaksi Hapus, instans yang dihapus tidak akan dapat dipulihkan.
Kode status respons
Kode | Deskripsi |
---|---|
204 (No Content) |
Ketika semua instans SOP dihapus. |
400 (Bad Request) |
Permintaan diformat dengan buruk. |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
404 (Not Found) |
Ketika seri yang ditentukan tidak ditemukan dalam studi atau instans yang ditentukan tidak ditemukan dalam seri. |
503 (Service Unavailable) |
Layanan tidak tersedia atau sibuk. Coba lagi nanti. |
Menghapus payload respons
Isi respons kosong. Kode status adalah satu-satunya informasi berguna yang dikembalikan.
Layanan Daftar Kerja (UPS-RS)
Layanan DICOM mendukung SOP Push and Pull dari Layanan Daftar Kerja (UPS-RS). Layanan Daftar Kerja menyediakan akses ke satu Daftar Kerja yang berisi Workitems, yang masing-masing mewakili Langkah Prosedur Terpadu (UPS).
Sepanjang, variabel {workitem}
dalam templat URI adalah singkatan dari Workitem UID.
Titik akhir UPS-RS yang tersedia meliputi:
Kata kerja | Jalur | Deskripsi |
---|---|---|
POST | {s}/workitems{? AffectedSOPInstanceUID} | Membuat item kerja |
POST | {s}/workitems/{instance}{?transaction} | Memperbarui item kerja |
GET | {s}/workitems{?query*} | Mencari item kerja |
GET | {s}/workitems/{instance} | Mengambil item kerja |
TARUH | {s}/workitems/{instance}/state | Mengubah status item kerja |
POST | {s}/workitems/{instance}/cancelrequest | Batalkan item kerja |
POST | {s}/workitems/{instance}/subscribers/{AETitle}{?deletionlock} | Buat langganan |
POST | {s}/workitems/1.2.840.10008.5.1.4.34.5/ | Menangguhkan langganan |
DELETE | {s}/workitems/{instance}/subscribers/{AETitle} | Hapus Langganan |
GET | {s}/subscribers/{AETitle} | Buka saluran langganan |
Buat Workitem
Transaksi ini menggunakan metode POST untuk membuat Workitem baru.
Metode | Jalur | Deskripsi |
---|---|---|
POST | .. /workitems | Buat Workitem. |
POST | .. /workitems? {workitem} | Membuat Workitem dengan UID yang ditentukan. |
Jika tidak ditentukan dalam URI, himpunan data payload harus berisi Workitem dalam SOPInstanceUID
atribut .
Header Accept
dan Content-Type
diperlukan dalam permintaan, dan keduanya harus memiliki nilai application/dicom+json
.
Ada beberapa persyaratan yang terkait dengan atribut data DICOM dalam konteks transaksi tertentu. Atribut mungkin diperlukan untuk hadir, diharuskan untuk tidak ada, diharuskan kosong, atau diharuskan untuk tidak kosong. Persyaratan ini dapat ditemukan dalam tabel ini.
Catatan
Meskipun tabel referensi mengatakan bahwa UID Instans SOP tidak boleh ada, panduan ini khusus untuk protokol DIMSE dan ditangani secara berbeda di DICOMWeb. UID Instans SOP harus ada dalam himpunan data jika tidak ada di URI.
Catatan
Semua kode persyaratan bersyarat termasuk 1C dan 2C diperlakukan sebagai opsional.
Membuat kode status respons
Kode | Deskripsi |
---|---|
201 (Created) |
Target Workitem berhasil dibuat. |
400 (Bad Request) |
Ada masalah dengan permintaan tersebut. Misalnya, payload permintaan tidak memenuhi persyaratan. |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
409 (Conflict) |
Workitem sudah ada. |
415 (Unsupported Media Type) |
Yang disediakan Content-Type tidak didukung. |
503 (Service Unavailable) |
Layanan tidak tersedia atau sibuk. Coba lagi nanti. |
Membuat payload respons
Respons keberhasilan tidak memiliki payload. Header Location
respons dan Content-Location
berisi referensi URI ke Workitem yang dibuat.
Payload respons kegagalan berisi pesan yang menjelaskan kegagalan.
Meminta pembatalan
Transaksi ini memungkinkan pengguna untuk meminta pembatalan Workitem yang tidak berwenang.
Ada empat status Workitem yang valid:
SCHEDULED
IN PROGRESS
CANCELED
COMPLETED
Transaksi ini hanya berhasil terhadap Workitems dalam status SCHEDULED
. Setiap pengguna dapat mengklaim kepemilikan Workitem dengan mengatur UID Transaksinya dan mengubah statusnya menjadi IN PROGRESS
. Sejak saat itu, pengguna hanya dapat memodifikasi Workitem dengan menyediakan UID Transaksi yang benar. Meskipun UPS mendefinisikan kelas WATCH dan Event SOP yang memungkinkan permintaan pembatalan dan peristiwa lain diteruskan, layanan DICOM ini tidak menerapkan kelas-kelas ini, sehingga permintaan pembatalan pada workitem yang IN PROGRESS
mengembalikan kegagalan. Workitem yang dimiliki dapat dibatalkan melalui transaksi Ubah Status Workitem.
Metode | Jalur | Deskripsi |
---|---|---|
POST | .. /workitems/{workitem}/cancelrequest | Meminta pembatalan Workitem terjadwal |
Header Content-Type
diperlukan, dan harus memiliki nilai application/dicom+json
.
Payload permintaan mungkin menyertakan Informasi Tindakan seperti yang didefinisikan dalam Standar DICOM.
Meminta kode status respons pembatalan
Kode | Deskripsi |
---|---|
202 (Accepted) |
Permintaan diterima oleh server, tetapi status Target Workitem tidak berubah. |
400 (Bad Request) |
Ada masalah dengan sintaks permintaan. |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
404 (Not Found) |
Target Workitem tidak ditemukan. |
409 (Conflict) |
Permintaan tidak konsisten dengan status Target Workitem saat ini. Misalnya, Target Workitem berada dalam status SCHEDULED atau COMPLETED . |
415 (Unsupported Media Type) |
Yang disediakan Content-Type tidak didukung. |
Meminta payload respons pembatalan
Respons keberhasilan tidak memiliki payload, dan payload respons kegagalan berisi pesan yang menjelaskan kegagalan.
Jika Instans Workitem sudah dalam status dibatalkan, respons menyertakan header Peringatan HTTP berikut: 299: The UPS is already in the requested state of CANCELED.
Ambil Workitem
Transaksi ini mengambil Workitem. Ini sesuai dengan operasi UPS DIMSE N-GET.
Lihat: https://dicom.nema.org/medical/dicom/current/output/html/part18.html#sect_11.5
Jika Workitem ada di server asal, Workitem akan dikembalikan dalam Jenis Media yang Dapat Diterima. Workitem yang dikembalikan tidak boleh berisi Atribut UID Transaksi (0008.1195). Ini diperlukan untuk mempertahankan peran atribut sebagai kunci akses.
Metode | Jalur | Deskripsi |
---|---|---|
GET | .. /workitems/{workitem} | Permintaan untuk mengambil Workitem |
Header Accept
diperlukan dan harus memiliki nilai application/dicom+json
.
Mengambil kode status respons Workitem
Kode | Deskripsi |
---|---|
200 (OK) | Instans Workitem berhasil diambil. |
400 (Permintaan Buruk) | Ada masalah dengan permintaan tersebut. |
401 (TidakDiizinkan) | Klien tidak diautentikasi. |
403 (Terlarang) | Pengguna tidak diotorisasi. |
404 (Tidak Ditemukan) | Target Workitem tidak ditemukan. |
Mengambil payload respons Workitem
- Respons keberhasilan memiliki payload bagian tunggal yang berisi Workitem yang diminta di Jenis Media yang Dipilih.
- Workitem yang dikembalikan tidak boleh berisi atribut UID Transaksi (0008, 1195) dari Workitem, karena itu hanya boleh diketahui oleh Pemilik.
Perbarui Workitem
Transaksi ini memodifikasi atribut Workitem yang ada. Ini sesuai dengan operasi UPS DIMSE N-SET.
Lihat: https://dicom.nema.org/medical/dicom/current/output/html/part18.html#sect_11.6
Untuk memperbarui Workitem yang saat ini dalam SCHEDULED
status, Transaction UID
atribut tidak akan ada. Untuk Workitem dalam IN PROGRESS
status, permintaan harus menyertakan UID Transaksi saat ini sebagai parameter kueri. Jika Workitem sudah berada di COMPLETED
atau CANCELED
menyatakan, responsnya adalah 400 (Bad Request)
.
Metode | Jalur | Deskripsi |
---|---|---|
POST | .. /workitems/{workitem}? {transaction-uid} | Memperbarui Transaksi Workitem |
Header Content-Type
diperlukan, dan harus memiliki nilai application/dicom+json
.
Payload permintaan berisi himpunan data dengan perubahan yang akan diterapkan ke Workitem target. Ketika urutan dimodifikasi, permintaan harus menyertakan semua Item dalam urutan, bukan hanya Item yang akan dimodifikasi. Saat beberapa Atribut perlu diperbarui sebagai grup, lakukan pembaruan sebagai beberapa Atribut dalam satu permintaan, bukan sebagai beberapa permintaan.
Ada banyak persyaratan yang terkait dengan atribut data DICOM dalam konteks transaksi tertentu. Atribut mungkin diperlukan untuk hadir, diharuskan untuk tidak ada, diharuskan kosong, atau diharuskan untuk tidak kosong. Persyaratan ini dapat ditemukan dalam tabel ini.
Catatan
Semua kode persyaratan bersyarat termasuk 1C dan 2C diperlakukan sebagai opsional.
Catatan
Permintaan tidak dapat menetapkan nilai atribut Status Langkah Prosedur (0074.1000). Status Langkah Prosedur dikelola menggunakan transaksi Ubah Status, atau transaksi Pembatalan Permintaan.
Memperbarui kode status respons transaksi Workitem
Kode | Deskripsi |
---|---|
200 (OK) |
Target Workitem diperbarui. |
400 (Bad Request) |
Ada masalah dengan permintaan tersebut. Misalnya: (1) Target Workitem berada dalam status COMPLETED atau CANCELED . (2) UID Transaksi hilang. (3) UID Transaksi salah. (4) himpunan data tidak sesuai dengan persyaratan. |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
404 (Not Found) |
Target Workitem tidak ditemukan. |
409 (Conflict) |
Permintaan tidak konsisten dengan status Target Workitem saat ini. |
415 (Unsupported Media Type) |
Yang disediakan Content-Type tidak didukung. |
Memperbarui payload respons transaksi Workitem
Server asal harus mendukung bidang header seperti yang diperlukan dalam Tabel 11.6.3-2.
Respons keberhasilan tidak boleh memiliki payload atau payload yang berisi dokumen Laporan Status.
Payload respons kegagalan mungkin berisi Laporan Status yang menjelaskan kegagalan, peringatan, atau informasi berguna lainnya.
Ubah status Workitem
Transaksi ini digunakan untuk mengubah status Workitem. Ini sesuai dengan operasi UPS DIMSE N-ACTION "Ubah Status UPS". Perubahan status digunakan untuk mengklaim kepemilikan, menyelesaikan, atau membatalkan Workitem.
Lihat: https://dicom.nema.org/medical/dicom/current/output/html/part18.html#sect_11.7
Jika Workitem ada di server asal, Workitem akan dikembalikan dalam Jenis Media yang Dapat Diterima. Workitem yang dikembalikan tidak boleh berisi atribut UID Transaksi (0008.1195). Ini diperlukan untuk mempertahankan peran Atribut ini sebagai kunci akses seperti yang dijelaskan di sini.
Metode | Jalur | Deskripsi |
---|---|---|
TARUH | .. /workitems/{workitem}/state | Ubah Status Workitem |
Header Accept
diperlukan, dan harus memiliki nilai application/dicom+json
.
Payload permintaan harus berisi Mengubah Elemen Data Status UPS. Elemen data ini adalah:
- UID Transaksi (0008, 1195). Payload permintaan harus mencakup UID Transaksi. Agen pengguna membuat UID Transaksi saat meminta transisi ke
IN PROGRESS
status untuk Workitem tertentu. Agen pengguna menyediakan bahwa UID Transaksi dalam transaksi berikutnya dengan Workitem tersebut. - Status Langkah Prosedur (0074, 1000). Nilai hukum sesuai dengan transisi status yang diminta. Mereka adalah:
IN PROGRESS
, ,COMPLETED
atauCANCELED
.
Mengubah kode status respons status Workitem
Kode | Deskripsi |
---|---|
200 (OK) |
Instans Workitem berhasil diambil. |
400 (Bad Request) |
Permintaan tidak dapat dilakukan karena salah satu alasan berikut: (1) permintaan tidak valid mengingat status Target Workitem saat ini. (2) UID Transaksi hilang. (3) UID Transaksi salah |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
404 (Not Found) |
Target Workitem tidak ditemukan. |
409 (Conflict) |
Permintaan tidak konsisten dengan status Target Workitem saat ini. |
Mengubah payload respons status Workitem
- Respons mencakup bidang header yang ditentukan dalam bagian 11.7.3.2.
- Respons keberhasilan tidak akan memiliki payload.
- Payload respons kegagalan mungkin berisi Laporan Status yang menjelaskan kegagalan, peringatan, atau informasi berguna lainnya.
Cari Workitems
Transaksi ini memungkinkan Anda mencari Workitem berdasarkan atribut.
Metode | Jalur | Deskripsi |
---|---|---|
GET | .. /workitems? | Cari Workitems |
Header berikut Accept
didukung untuk mencari:
application/dicom+json
Parameter Pencarian yang Didukung
Parameter berikut untuk setiap kueri didukung:
Tombol | Nilai Dukungan | Jumlah yang Diizinkan | Deskripsi |
---|---|---|---|
{attributeID}= |
{value} |
0...N | Cari atribut/pencocokan nilai dalam kueri. |
includefield= |
{attributeID} all |
0...N | Atribut lain yang akan dikembalikan dalam respons. Hanya atribut tingkat atas yang dapat disertakan - bukan atribut yang merupakan bagian dari urutan. Tag publik dan privat didukung. Saat all disediakan, lihat Respons Pencarian untuk informasi selengkapnya tentang atribut mana yang dikembalikan untuk setiap jenis kueri. Jika campuran {attributeID} dan all disediakan, server default menggunakan 'semua'. |
limit= |
{value} |
0...1 | Nilai bilangan bulat untuk membatasi jumlah nilai yang dikembalikan dalam respons. Nilai dapat berada di antara rentang 1 >= x <= 200 . Default ke 100 . |
offset= |
{value} |
0...1 | Lewati hasil {value}. Jika offset disediakan lebih besar dari jumlah hasil kueri pencarian, 204 (no content) respons dikembalikan. |
fuzzymatching= |
true | false |
0...1 | Jika pencocokan fuzzy true diterapkan ke atribut apa pun dengan Representasi Nilai Nama Orang (PN) (VR). Ini melakukan kecocokan kata awalan dari bagian nama apa pun di dalam atribut ini. Misalnya, jika PatientName adalah , maka joh , , do jo do , Doe dan John Doe John^Doe semua cocok. Namun ohn tidak cocok. |
Atribut yang Dapat Dicari
Kami mendukung pencarian pada atribut ini:
Kata Kunci Atribut |
---|
PatientName |
PatientID |
ReferencedRequestSequence.AccessionNumber |
ReferencedRequestSequence.RequestedProcedureID |
ScheduledProcedureStepStartDateTime |
ScheduledStationNameCodeSequence.CodeValue |
ScheduledStationClassCodeSequence.CodeValue |
ScheduledStationGeographicLocationCodeSequence.CodeValue |
ProcedureStepState |
StudyInstanceUID |
Pencocokan Pencarian
Kami mendukung jenis pencocokan ini:
Jenis Pencarian | Atribut yang Didukung | Contoh |
---|---|---|
Kueri Rentang | ScheduledProcedureStepStartDateTime |
{attributeID}={value1}-{value2} . Untuk nilai tanggal/waktu, kami mendukung rentang inklusif pada tag. Ini dipetakan ke attributeID >= {value1} AND attributeID <= {value2} . Jika {value1} tidak ditentukan, semua kemunculan tanggal/waktu sebelum dan termasuk {value2} dicocokkan. Demikian juga, jika {value2} tidak ditentukan, semua kemunculan {value1} dan tanggal/waktu berikutnya dicocokkan. Namun, salah satu nilai ini harus ada. {attributeID}={value1}- dan {attributeID}=-{value2} valid, bagaimanapun, {attributeID}=- tidak valid. |
Sama Persis | Semua atribut yang didukung | {attributeID}={value1} |
Kecocokan Fuzzy | PatientName |
Cocok dengan komponen nama apa pun yang dimulai dengan nilai . |
Catatan
Meskipun kami tidak mendukung pencocokan urutan penuh, kami mendukung kecocokan persis pada atribut yang tercantum yang terkandung dalam urutan.
ID Atribut
Tag dapat dikodekan dalam banyak cara untuk parameter kueri. Kami menerapkan sebagian standar seperti yang didefinisikan dalam PS3.18 6.7.1.1.1. Pengodean berikut untuk tag didukung:
Nilai | Contoh |
---|---|
{group}{element} |
00100010 |
{dicomKeyword} |
PatientName |
Kueri contoh:
../workitems?PatientID=K123&0040A370.00080050=1423JS&includefield=00404005&limit=5&offset=0
Respons Pencarian
Respons adalah array himpunan 0...N
data DICOM dengan atribut berikut yang dikembalikan:
- Semua atribut dalam Tabel DICOM PowerShell 3.4 CC.2.5-3 dengan Jenis Kunci Pengembalian 1 atau 2
- Semua atribut dalam Tabel DICOM PowerShell 3.4 CC.2.5-3 dengan Jenis Kunci Pengembalian 1C yang persyaratan bersyarkatnya terpenuhi
- Semua atribut Workitem lainnya diteruskan sebagai parameter kecocokan
- Semua atribut Workitem lainnya diteruskan sebagai
includefield
nilai parameter
Kode Respons Pencarian
API kueri mengembalikan salah satu kode status berikut dalam respons:
Kode | Deskripsi |
---|---|
200 (OK) |
Payload respons berisi semua sumber daya yang cocok. |
206 (Partial Content) |
Payload respons hanya berisi beberapa hasil pencarian, dan sisanya dapat diminta melalui permintaan yang sesuai. |
204 (No Content) |
Pencarian berhasil diselesaikan tetapi tidak mengembalikan hasil. |
400 (Bad Request) |
Ada masalah dengan permintaan tersebut. Misalnya, sintaks Parameter Kueri tidak valid. Isi respons berisi detail kegagalan. |
401 (Unauthorized) |
Klien tidak diautentikasi. |
403 (Forbidden) |
Pengguna tidak diotorisasi. |
503 (Service Unavailable) |
Layanan tidak tersedia atau sibuk. Coba lagi nanti. |
Catatan Lainnya
API kueri tidak 413 (request entity too large)
. Jika batas respons kueri yang diminta berada di luar rentang yang dapat diterima, permintaan buruk akan dikembalikan. Apa pun yang diminta dalam rentang yang dapat diterima diselesaikan.
- Hasil halaman dioptimalkan untuk mengembalikan instans terbaru yang cocok terlebih dahulu, yang dapat mengakibatkan rekaman duplikat di halaman berikutnya jika data yang lebih baru yang cocok dengan kueri ditambahkan.
- Pencocokan tidak peka huruf besar/kecil dan aksen tidak sensitif untuk jenis VR PN.
- Pencocokan tidak peka huruf besar/kecil dan aksen sensitif untuk jenis VR string lainnya.
- Jika ada skenario di mana membatalkan Workitem dan mengkueri hal yang sama terjadi pada saat yang sama, maka kueri kemungkinan mengecualikan Workitem yang diperbarui dan kode responsnya adalah
206 (Partial Content)
.
Catatan
DICOM® adalah merek dagang terdaftar dari Asosiasi Produsen Listrik Nasional untuk publikasi Standar yang berkaitan dengan komunikasi digital informasi medis.
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk