Bagikan melalui

Mengimpor data FHIR

Anda dapat menggunakan operasi import untuk memasukkan data FHIR® ke server FHIR dengan throughput tinggi. Operasi impor memungkinkan impor data FHIR dalam format NDJSON ke server FHIR.

Mode operasi impor

Operasi ini import mendukung dua mode: awal dan inkremental. Setiap mode memiliki fitur dan kasus penggunaan yang berbeda.

Mode awal

  • Ditujukan untuk memuat sumber daya FHIR ke server FHIR kosong.

  • Memblokir penulisan API ke server FHIR.

Mode bertahap

  • Dioptimalkan untuk memuat data ke server FHIR secara berkala dan tidak memblokir penulisan melalui API.

  • Memungkinkan Anda memuat nilai lastUpdated dan versionId dari metadata sumber daya jika nilai tersebut ada di JSON sumber daya.

  • Memungkinkan Anda memuat sumber daya dalam urutan versi yang tidak berurutan. Catatan untuk penyerapan sumber daya yang tidak berurutan

    • Jika file impor tidak memiliki nilai bidang version dan lastUpdated yang ditentukan, tidak ada jaminan bahwa semua sumber daya dalam layanan FHIR dapat diimpor.
    • Jika berkas impor memiliki sumber daya dengan nilai duplikat pada bidang version dan lastUpdated, hanya satu sumber daya yang diproses secara acak dalam layanan FHIR.
    • Selama eksekusi paralel, jika beberapa sumber daya memiliki ID sumber daya yang sama, hanya salah satu sumber daya yang diimpor secara acak.

Tabel berikut ini memperlihatkan perbedaan antara mode impor.

Wilayah Mode awal Mode bertahap
Kemampuan Muatan awal data ke dalam layanan FHIR Penyerapan data berkelanjutan ke layanan FHIR (Bertahap atau Hampir Real-Time).
Panggilan API bersamaan Memblokir operasi tulis bersamaan Data dapat diserap secara bersamaan saat menjalankan operasi CRUD API di server FHIR.
Penyerapan sumber daya versi Tidak didukung, hanya versi terbaru yang dipertahankan, dan lastUpdated diatur ke waktu impor Supported. Memungkinkan penyerapan beberapa versi sumber daya FHIR dalam satu batch sambil mempertahankan riwayat sumber daya dan nilai lastUpdated asli.
Catatan: Gunakan mode impor bertahap jika Anda perlu mempertahankan versi historis atau mempertahankan tanda waktu lastUpdated asli
Pertahankan nilai kolom lastUpdated Tidak didukung Pertahankan nilai bidang lastUpdated di sumber daya FHIR selama proses penyerapan.
Penagihan Tidak dikenakan biaya apa pun Dikenakan biaya berdasarkan sumber daya yang berhasil diserap. Biaya dikenakan per harga API.

Pertimbangan performa

Untuk mencapai performa terbaik dengan import operasi, pertimbangkan faktor-faktor berikut.

  • Gunakan file besar untuk diimpor. Ukuran file NDJSON optimal untuk impor adalah >=50 MB (atau >sumber daya =20 K, tanpa batas atas). Pertimbangkan untuk menggabungkan file yang lebih kecil bersama-sama.

  • Impor file sumber daya FHIR sebagai satu kumpulan. Untuk performa optimal, impor semua file sumber daya FHIR yang ingin Anda serap di server FHIR dalam satu import operasi. Mengimpor semua file dalam satu operasi mengurangi overhead pembuatan dan pengelolaan beberapa pekerjaan impor. Secara optimal, ukuran total file dalam satu impor harus besar (>=100 GB atau >sumber daya =100M, tanpa batas atas).

  • Batasi jumlah pekerjaan impor paralel. Anda dapat menjalankan beberapa import pekerjaan secara bersamaan, tetapi ini dapat memengaruhi keseluruhan throughput operasi import.

Untuk mencapai throughput tinggi,import operasi dilakukan menggunakan infrastruktur komputasi terdistribusi. Ini membagi file input dalam unit data dan memproses unit ini secara paralel dan independen satu sama lain.

Melakukan operasi impor

Prasyarat

  • Untuk menggunakan import operasi ini, Anda memerlukan peran Pengimpor Data FHIR di server FHIR.

  • Konfigurasikan server FHIR. Data FHIR harus disimpan dalam file khusus sumber daya dalam format FHIR NDJSON di penyimpanan blob Azure. Untuk informasi selengkapnya, lihat Mengonfigurasi pengaturan impor.

  • Data harus berada di penyewa yang sama dengan layanan FHIR.

  • Untuk mendapatkan token akses, lihat Token Akses

Menghubungi

Lakukan POST panggilan ke <<FHIR service base URL>>/$import dengan header dan isi permintaan berikut.

Tajuk permintaan

Prefer:respond-async
Content-Type:application/fhir+json

Tubuh

Tabel-tabel berikut menjelaskan parameter badan dan input.

Nama Parameter Deskripsi Kardinalitas Nilai yang diterima
inputFormat String yang mewakili nama format sumber data. Hanya file FHIR NDJSON yang didukung. 1..1 application/fhir+ndjson
mode Nilai opsi impor. 1..1 Untuk impor dalam mode awal, gunakan nilai mode InitialLoad. Untuk mode impor inkremental, gunakan nilai untuk mode IncrementalLoad. Jika Anda tidak memberikan nilai mode, IncrementalLoad nilai mode digunakan secara default.
allowNegativeVersions Memungkinkan server FHIR menetapkan versi negatif untuk rekaman sumber daya dengan nilai lastUpdated eksplisit dan tidak ada versi yang ditentukan ketika input tidak cocok dalam ruang yang berdekatan dari versi positif yang ada di penyimpanan. 0..1 Untuk mengaktifkan fitur ini, berikan true. Secara default, ini salah.
errorContainerName String yang mewakili nama kontainer tempat kesalahan ditemui selama proses impor akan dicatat. 0..1 Nama kontainer kustom untuk log kesalahan. Nama harus antara 3-63 karakter dan hanya berisi huruf kecil, angka, dan tanda hubung. Jika tidak ditentukan, kontainer default akan digunakan.
input Rincian dari file-file input. 1..* Array JSON dengan tiga bagian yang dijelaskan dalam tabel berikut.
Nama bagian input Deskripsi Kardinalitas Nilai yang diterima
type Jenis sumber daya file input. 0..1 Jenis sumber daya FHIR yang valid yang cocok dengan file input. Bidang ini bersifat opsional.
url URL penyimpanan Azure dari file input. 1..1 Nilai URL file input. Nilai tidak dapat dimodifikasi.
etag ETag dari berkas masukan di penyimpanan Azure. Digunakan untuk memverifikasi bahwa konten file tidak diubah setelah import pendaftaran. 0..1 Nilai ETag untuk file masukan. 
{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputFormat",
            "valueString": "application/fhir+ndjson"
        },
        {
            "name": "mode",
            "valueString": "<Use "InitialLoad" for initial mode import / Use "IncrementalLoad" for incremental mode import>"
        }, 
        {
            "name": "allowNegativeVersions",
            "valueBoolean": true
        },
        {
            "name": "errorContainerName",
            "valueString": "import-error-logs"
        },
        {
            "name": "input",
            "part": [
                { 
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/filename.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "\"0x8D92A7342657F4F\""
                }
            ]
        }
    ]
}

Memeriksa status impor

Setelah Anda memulai operasi import, isi respons kosong dengan tautan callback dikembalikan pada Content-location header respons, bersama dengan kode status 202 Accepted. callback Simpan tautan untuk memeriksa status impor.

Pendaftaran operasi import diimplementasikan sebagai panggilan idempoten. Payload pendaftaran yang sama menghasilkan pendaftaran yang sama, yang memengaruhi kemampuan untuk memproses ulang file dengan nama yang sama. Hindari memperbarui file secara langsung. Sebagai gantinya, kami sarankan Anda menggunakan nama file yang berbeda untuk data yang diperbarui. Atau, jika pembaruan di tempat dengan nama file yang sama tidak dapat dihindari, tambahkan ETags pada payload pendaftaran.

Untuk memeriksa status impor, lakukan panggilan REST dengan metode GET ke tautan callback yang dikembalikan di langkah sebelumnya.

Menginterpretasikan respons dengan menggunakan tabel ini.

Kode respons Badan respons Deskripsi
202 Accepted Operasi masih berjalan.
200 OK The response body doesn't contain any error.url entry Semua sumber daya berhasil diimpor.
200 OK The response body contains some error.url entry Terjadi kesalahan selama impor beberapa sumber daya. Untuk detailnya, lihat file yang terletak di error.url. Sumber daya yang tersisa berhasil diimpor.
Other Terjadi kesalahan fatal dan operasi berhenti. Sumber daya yang berhasil diimpor tidak digulung balik.

Tabel berikut ini menjelaskan bidang penting dalam isi respons:

Bidang Deskripsi
transactionTime Waktu mulai operasi massal import .
output.count Jumlah sumber daya yang berhasil diimpor.
error.count Jumlah sumber daya yang tidak diimpor karena kesalahan.
error.url URL file yang berisi detail kesalahan. Setiap error.url instans unik untuk URL input. 
{
    "transactionTime": "2021-07-16T06:46:52.3873388+00:00",
    "request": "https://importperf.azurewebsites.net/$Import",
    "output": [
        {
            "type": <null in case type parameter in not populated in request. If provided, resource name will be added>,
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/filename.ndjson"
        }
    ],
    "error": [
        { 
        "type": "OperationOutcome",
        "count": 51,
        "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson",
        "url": "https://example.blob.core.windows.net/fhirlogs/CarePlan06b88c6933a34c7c83cb18b7dd6ae3d8.ndjson"
        }
    ]
}

Menyerap sumber daya yang dihapus sementara

Impor mode inkremental mendukung penyerapan sumber daya yang dihapus sementara. Anda perlu menggunakan ekstensi untuk mengimpor sumber daya yang dihapus secara lembut dalam layanan FHIR.

Tambahkan ekstensi ke sumber daya untuk menginformasikan layanan FHIR bahwa sumber daya dihapus sementara.

{"resourceType": "Patient", "id": "example10", "meta": { "lastUpdated": "2023-10-27T04:00:00.000Z", "versionId": 4, "extension": [ { "url": "http://azurehealthcareapis.com/data-extensions/deleted-state", "valueString": "soft-deleted" } ] } }

import Setelah operasi berhasil diselesaikan, lakukan pencarian riwayat pada sumber daya untuk memvalidasi sumber daya yang dihapus sementara. Jika Anda mengetahui ID sumber daya yang dihapus, gunakan pola URL dalam contoh berikut.

<FHIR_URL>/<resource-type>/<resource-id>/_history

Jika Anda tidak mengetahui ID sumber daya, lakukan pencarian riwayat pada jenis sumber daya.

<FHIR_URL>/<resource-type>/_history

Memecahkan masalah operasi impor

Berikut adalah pesan kesalahan yang terjadi jika import operasi gagal, bersama dengan tindakan yang direkomendasikan untuk menyelesaikan masalah.

200 OK, tetapi ada kesalahan dengan URL dalam respons

import operasi berhasil dan mengembalikan 200 OK. Namun, error.url hadir dalam isi respons. File yang ada di lokasi error.url mengandung fragmen JSON yang mirip dengan contoh berikut.

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "details": {
                "text": "Given conditional reference '{0}' doesn't resolve to a resource."
            },
            "diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
        }
    ]
}

Penyebab: File NDJSON berisi sumber daya dengan referensi bersyarat yang import tidak mendukung.

Solusi: Ganti referensi bersyarat ke referensi normal dalam file NDJSON.

400 Permintaan Tidak Valid

Operasi import gagal dan mengembalikan 400 Bad Request. Isi respons berisi konten diagnostik

operasi impor gagal dengan alasan: Tidak ada host yang dikenal. (example.blob.core.windows.net:443) Solusi: Verifikasi bahwa tautan ke penyimpanan Azure sudah benar. Periksa pengaturan jaringan dan firewall untuk memastikan bahwa server FHIR dapat mengakses penyimpanan. Jika layanan Anda berada dalam jaringan virtual, pastikan penyimpanan berada di jaringan virtual yang sama atau di jaringan virtual yang di-peering dengan jaringan virtual layanan FHIR.

Sumber daya SearchParameter tidak dapat diproses dengan impor Solusi: Operasi impor mengembalikan kesalahan HTTP 400 saat sumber daya parameter pencarian diserap melalui proses impor. Perubahan ini dimaksudkan untuk mencegah parameter pencarian ditempatkan dalam status tidak valid saat diserap dengan operasi impor.

403 Dilarang

Operasi import gagal dan mengembalikan 403 Forbidden. Isi respons berisi konten diagnostik.

operasi impor gagal karena alasan: Server gagal mengautentikasi permintaan. Pastikan nilai header Otorisasi dibentuk dengan benar, termasuk tanda tangannya. Penyebab: Layanan FHIR menggunakan identitas terkelola untuk autentikasi penyimpanan sumber. Kesalahan ini menunjukkan penetapan peran yang hilang atau salah. Solusi: Tetapkan peran Kontributor Data Blob Penyimpanan ke server FHIR. Untuk informasi selengkapnya, lihat Menetapkan peran Azure.

Kesalahan Server Internal 500

Operasi import gagal dan mengembalikan 500 Internal Server Error. Isi respons berisi konten diagnostik

operasi impor gagal karena alasan: Database '****' telah mencapai kuota ukurannya. Partisi atau hapus data, hilangkan indeks, atau lihat dokumentasi untuk kemungkinan resolusi.

Penyebab: Anda mencapai batas penyimpanan layanan FHIR.

Solusi: Kurangi ukuran data Anda atau pertimbangkan Azure API untuk FHIR, yang memiliki batas penyimpanan yang lebih tinggi.

423 Terkunci

Perilaku:import Operasi gagal dan mengembalikan 423 Locked. Isi respons mencakup konten ini:

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Service is locked for initial import mode."
        }
    ]
}

Sebab: Layanan FHIR dikonfigurasi dengan mode Impor awal yang memblokir operasi lain.

Larutan: Matikan mode Impor awal layanan FHIR, atau pilih Mode bertahap.

Keterbatasan

  • Jumlah maksimum file yang diizinkan untuk setiap import operasi adalah 10.000.
  • Jumlah file yang diserap di server FHIR dengan nilai bidang lastUpdated yang sama hingga milidetik tidak boleh melebihi 10.000.
  • Operasi impor tidak didukung untuk jenis sumber daya SearchParameter.
  • Operasi impor tidak mendukung referensi bersyarat dalam sumber daya.

Langkah berikutnya

Mengonversi data Anda ke FHIR

Mengonfigurasi pengaturan ekspor dan menyiapkan akun penyimpanan

Menyalin data ke Azure Synapse Analytics

Nota

FHIR® adalah merek dagang terdaftar HL7 dan digunakan dengan izin HL7.

  • Last updated on