Mengekspor File DICOM

  • Artikel

Layanan DICOM menyediakan kemampuan untuk dengan mudah mengekspor data DICOM dalam format file, menyederhanakan proses penggunaan pencitraan medis dalam alur kerja eksternal, seperti AI dan pembelajaran mesin. Studi, seri, dan instans DICOM dapat diekspor secara massal ke akun Azure Blob Storage menggunakan API ekspor. Data DICOM yang diekspor ke akun penyimpanan akan diekspor sebagai .dcm file dalam struktur folder yang mengatur instans dengan StudyInstanceID dan SeriesInstanceID.

Ada tiga langkah untuk mengekspor data dari layanan DICOM:

  • Aktifkan identitas terkelola yang ditetapkan sistem untuk layanan DICOM.
  • Konfigurasikan akun penyimpanan baru atau yang sudah ada dan berikan izin ke identitas terkelola sistem.
  • Gunakan API ekspor untuk membuat pekerjaan ekspor baru untuk mengekspor data.

Mengaktifkan identitas terkelola untuk layanan DICOM

Langkah pertama untuk mengekspor data dari layanan DICOM adalah mengaktifkan identitas terkelola sistem. Identitas terkelola ini digunakan untuk mengautentikasi layanan DICOM dan memberikan izin ke akun penyimpanan yang digunakan sebagai tujuan ekspor. Untuk informasi selengkapnya tentang identitas terkelola di Azure, lihat Tentang identitas terkelola untuk sumber daya Azure.

  1. Di portal Azure, telusuri ke layanan DICOM yang ingin Anda ekspor dan pilih Identitas.

Cuplikan layar memperlihatkan pilihan tampilan Identitas.

  1. Atur opsi Status ke Aktif, lalu pilih Simpan.

Cuplikan layar tombol identitas yang ditetapkan sistem.

  1. Pilih Ya dalam dialog konfirmasi yang muncul.

Cuplikan layar dialog yang mengonfirmasi pengaktifan identitas sistem.

Dibutuhkan beberapa menit untuk membuat identitas terkelola sistem. Ketika identitas sistem telah diaktifkan, ID Objek (utama) akan ditampilkan.

Memberikan izin akun penyimpanan ke identitas terkelola sistem

Identitas terkelola sistem akan memerlukan izin Kontributor Data Blob Penyimpanan untuk menulis data ke akun penyimpanan tujuan.

  1. Di bawah Izin pilih Penetapan peran Azure.

Cuplikan layar tombol penetapan peran Azure pada tampilan Identitas.

  1. Pilih Tambahkan penetapan peran. Pada panel Tambahkan penetapan peran , buat pilihan berikut:
    • Di bawah Cakupan, pilih Penyimpanan.
    • Di bawah Sumber Daya, pilih akun penyimpanan tujuan untuk operasi ekspor.
    • Di bawah Peran, pilih Kontributor Data Blob Penyimpanan.

Cuplikan layar panel Tambahkan Penetapan Peran.

  1. Pilih Simpan untuk menambahkan izin ke identitas terkelola sistem.

Menggunakan API ekspor

API ekspor mengekspos satu POST titik akhir untuk mengekspor data.

POST <dicom-service-url>/<version>/export

Mengingat sumber, kumpulan data yang akan diekspor, dan tujuan, lokasi tempat data akan diekspor, titik akhir mengembalikan referensi ke operasi ekspor baru yang berjalan lama. Durasi operasi ini tergantung pada volume data yang akan diekspor. Lihat Status Operasi di bawah ini untuk detail selengkapnya tentang memantau kemajuan operasi ekspor.

Setiap kesalahan yang ditemui saat mencoba mengekspor akan dicatat dalam log kesalahan. Lihat Kesalahan di bawah ini untuk detailnya.

Minta

Isi permintaan terdiri dari sumber ekspor dan tujuan.

{
    "source": {
        "type": "identifiers",
        "settings": {
            "values": [
                "..."
            ]
        }
    },
    "destination": {
        "type": "azureblob",
        "settings": {
            "setting": "<value>"
        }
    }
}

Pengaturan sumber

Satu-satunya pengaturan adalah daftar pengidentifikasi yang akan diekspor.

Properti Diperlukan Default Deskripsi
Values Ya Daftar satu atau beberapa pengidentifikasi studi, seri, dan/atau instans SOP DICOM dalam format "<StudyInstanceUID>[/<SeriesInstanceUID>[/<SOPInstanceUID>]]".

Pengaturan tujuan

Koneksi ke akun penyimpanan Azure Blob ditentukan dengan BlobContainerUri.

Properti Diperlukan Default Deskripsi
BlobContainerUri Tidak "" URI lengkap untuk kontainer blob.
UseManagedIdentity Ya false Bendera yang diperlukan yang menunjukkan apakah identitas terkelola harus digunakan untuk mengautentikasi ke kontainer blob.

Contoh

Contoh di bawah ini meminta ekspor sumber daya DICOM berikut ke kontainer blob bernama export di akun penyimpanan bernama dicomexport:

  • Semua instans dalam studi yang StudyInstanceUID adalah 1.2.3.
  • Semua instans dalam seri yang StudyInstanceUID adalah 12.3 dan SeriesInstanceUID adalah 4.5.678.
  • Instans yang StudyInstanceUID , adalah SeriesInstanceUID123.4567.8, dan SOPInstanceUID adalah .9.1011.12
POST /export HTTP/1.1
Accept: */*
Content-Type: application/json
{
    "sources": {
        "type": "identifiers",
        "settings": {
            "values": [
                "1.2.3",
                "12.3/4.5.678",
                "123.456/7.8/9.1011.12"
            ]
        }
    },
    "destination": {
        "type": "azureblob",
        "settings": {
            "blobContainerUri": "https://dicomexport.blob.core.windows.net/export",
            "UseManagedIdentity": true
        }
    }
}

Respons

API ekspor mengembalikan 202 kode status saat operasi ekspor berhasil dimulai. Isi respons berisi referensi ke operasi, sementara nilai Location header adalah URL untuk status operasi ekspor (sama seperti href dalam isi).

Di dalam kontainer tujuan, file DCM dapat ditemukan dengan format jalur berikut: <operation id>/results/<study>/<series>/<sop instance>.dcm

HTTP/1.1 202 Accepted
Content-Type: application/json
{
    "id": "df1ff476b83a4a3eaf11b1eac2e5ac56",
    "href": "https://example-dicom.dicom.azurehealthcareapis.com/v1/operations/df1ff476b83a4a3eaf11b1eac2e5ac56"
}

Status operasi

URL di atas href dapat dijajaki untuk status operasi ekspor saat ini hingga selesai. Setelah pekerjaan mencapai status terminal, API akan mengembalikan kode status 200 alih-alih 202, dan nilai properti statusnya akan diperbarui sesuai dengan itu.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "operationId": "df1ff476b83a4a3eaf11b1eac2e5ac56",
    "type": "export",
    "createdTime": "2022-09-08T16:40:36.2627618Z",
    "lastUpdatedTime": "2022-09-08T16:41:01.2776644Z",
    "status": "completed",
    "results": {
        "errorHref": "https://dicomexport.blob.core.windows.net/export/4853cda8c05c44e497d2bc071f8e92c4/errors.log",
        "exported": 1000,
        "skipped": 3
    }
}

Kesalahan

Jika ada kesalahan pengguna saat mengekspor file DICOM, maka file dilewati dan kesalahan yang sesuai dicatat. Log kesalahan ini juga diekspor bersama file DICOM dan dapat ditinjau oleh pemanggil. Log kesalahan dapat ditemukan di <export blob container uri>/<operation ID>/errors.log.

Format

Setiap baris log kesalahan adalah objek JSON dengan properti berikut. Pengidentifikasi kesalahan tertentu mungkin muncul beberapa kali dalam log karena setiap pembaruan ke log diproses setidaknya sekali.

Properti Deskripsi
Timestamp Tanggal dan waktu ketika kesalahan terjadi.
Identifier Pengidentifikasi untuk studi DICOM, seri, atau instans SOP dalam format "<study instance UID>[/<series instance UID>[/<SOP instance UID>]]".
Error Pesan kesalahan terperinci.

Langkah berikutnya

Gambaran umum layanan DICOM