Operasi Impor
Operasi impor memungkinkan pemuatan data Fast Healthcare Interoperability Resources (FHIR®) ke server FHIR pada throughput tinggi menggunakan operasi $import. Impor mendukung beban data awal dan inkremental ke server FHIR.
Menggunakan operasi $import
Catatan
Anda harus memiliki peran Pengimpor Data FHIR di server FHIR untuk menggunakan $import.
Untuk menggunakan $import, Anda perlu mengonfigurasi server FHIR menggunakan instruksi di artikel Mengonfigurasi pengaturan impor . Data FHIR yang akan diimpor harus disimpan dalam file spesifik sumber daya dalam format FHIR NDJSON di penyimpanan blob Azure.
Untuk operasi impor, pastikan
- Semua sumber daya dalam file harus memiliki jenis yang sama. Anda mungkin memiliki beberapa file per jenis sumber daya.
- Data yang akan diimpor harus berada di Penyewa yang sama dengan layanan FHIR.
- Jumlah maksimum file yang akan diimpor per operasi adalah 10.000.
Catatan:
- Operasi impor tidak mendukung referensi bersyarah dalam sumber daya.
- Selama operasi impor, Jika beberapa sumber daya memiliki ID sumber daya yang sama, maka hanya salah satu sumber daya tersebut yang diimpor secara acak. Ada kesalahan yang dicatat untuk sumber daya yang berbagi ID sumber daya yang sama.
Memanggil $import
Lakukan POST panggilan ke <<FHIR service base URL>>/$import dengan header permintaan dan isi yang ditampilkan:
Header Permintaan
Prefer:respond-async
Content-Type:application/fhir+json
Isi
| Nama Parameter | Deskripsi | Kartu. | Nilai yang diterima |
|---|---|---|---|
| inputFormat | String yang mewakili nama format sumber data. Saat ini hanya file FHIR NDJSON yang didukung. | 1..1 | application/fhir+ndjson |
| mode | Nilai mode impor | 1..1 | Untuk nilai mode penggunaan InitialLoad impor awal. Untuk mode impor inkremental, gunakan IncrementalLoad nilai mode. Jika tidak ada nilai mode yang disediakan, nilai mode IncrementalLoad dipertimbangkan secara default. |
| input | Detail file input. | 1..* | Array JSON dengan tiga bagian yang dijelaskan dalam tabel di bawah ini. |
| Nama bagian input | Deskripsi | Kartu. | Nilai yang diterima |
|---|---|---|---|
| jenis | Jenis sumber daya file input | 1..1 | Jenis sumber daya FHIR yang valid yang cocok dengan file input. |
| URL | Url penyimpanan Azure dari file input | 1..1 | Nilai URL file input yang tidak dapat dimodifikasi. |
| etag | Etag file input pada penyimpanan Azure yang digunakan untuk memverifikasi konten file tidak berubah. | 0..1 | Nilai Etag dari file input yang tidak dapat dimodifikasi. |
Isi sampel untuk Impor beban awal:
{
"resourceType": "Parameters",
"parameter": [
{
"name": "inputFormat",
"valueString": "application/fhir+ndjson"
},
{
"name": "mode",
"valueString": "InitialLoad"
},
{
"name": "input",
"part": [
{
"name": "type",
"valueString": "Patient"
},
{
"name": "url",
"valueUri": "https://example.blob.core.windows.net/resources/Patient.ndjson"
},
{
"name": "etag",
"valueUri": "0x8D92A7342657F4F"
}
]
},
{
"name": "input",
"part": [
{
"name": "type",
"valueString": "CarePlan"
},
{
"name": "url",
"valueUri": "https://example.blob.core.windows.net/resources/CarePlan.ndjson"
}
]
}
]
}
Memeriksa status impor
Setelah $import dimulai, isi respons kosong dengan tautan panggilan balik dikembalikan di Content-location header respons bersama dengan 202-Accepted kode status. Simpan tautan panggilan balik ini untuk memeriksa status impor.
Untuk memeriksa status impor, lakukan panggilan REST dengan GET metode ke tautan panggilan balik yang dikembalikan di langkah sebelumnya.
Anda dapat menginterpretasikan respons menggunakan tabel berikut:
| Kode respons | Isi Respons | Deskripsi |
|---|---|---|
| 202 Diterima | Operasi masih berjalan. | |
| 200 OK | Isi respons tidak berisi entri error.url apa pun | Semua sumber daya berhasil diimpor. |
| 200 OK | Isi respons berisi beberapa entri error.url | Terjadi kesalahan saat mengimpor beberapa sumber daya. Lihat file yang terletak di error.url untuk detailnya. Sisa sumber daya berhasil diimpor. |
| Lainnya | Terjadi kesalahan fatal dan operasi telah berhenti. Sumber daya yang berhasil diimpor belum digulung balik. |
Tabel di bawah ini menyediakan beberapa bidang penting dalam isi respons:
| Bidang | Deskripsi |
|---|---|
| transactionTime | Waktu mulai operasi impor massal. |
| output.count | Jumlah sumber daya yang berhasil diimpor |
| error.count | Jumlah sumber daya yang tidak diimpor karena beberapa kesalahan |
| error.url | URL file yang berisi detail kesalahan. Setiap error.url unik untuk URL input. |
Respons sampel:
{
"transactionTime": "2021-07-16T06:46:52.3873388+00:00",
"request": "https://importperf.azurewebsites.net/$Import",
"output": [
{
"type": "Patient",
"count": 10000,
"inputUrl": "https://example.blob.core.windows.net/resources/Patient.ndjson"
},
{
"type": "CarePlan",
"count": 199949,
"inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.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"
}
]
}
Pemecahan Masalah
Memungkinkan solusi panduan untuk beberapa kode kesalahan yang mungkin Anda temui selama operasi impor.
200 OK, tetapi ada kesalahan dengan URL dalam respons
Perilaku: Operasi impor berhasil dan mengembalikan 200 OK. Namun, error.url hadir dalam isi respons. File yang error.url ada di lokasi berisi fragmen JSON yang mirip dengan contoh di bawah ini:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"details": {
"text": "Given conditional reference '{0}' does'nt resolve to a resource."
},
"diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
}
]
}
Menyebabkan: File NDJSON berisi sumber daya dengan referensi bersyarat, yang saat ini tidak didukung oleh $import.
Solusi: Ganti referensi bersyarat ke referensi normal dalam file NDJSON.
400 Permintaan Buruk
Perilaku: Operasi impor gagal dan 400 Bad Request dikembalikan. Isi respons memiliki konten berikut:
{
"resourceType": "OperationOutcome",
"id": "13876ec9-3170-4525-87ec-9e165052d70d",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: No such host is known. (example.blob.core.windows.net:443)"
}
]
}
Solusi: Verifikasi tautan ke penyimpanan Azure sudah benar. Periksa pengaturan jaringan dan firewall untuk memastikan bahwa server FHIR dapat mengakses penyimpanan. Jika layanan Anda berada di VNet, pastikan penyimpanan berada di VNet yang sama atau di VNet yang memiliki peering dengan layanan FHIR VNet.
403 Terlarang
Perilaku: Operasi impor gagal dan 403 Forbidden dikembalikan. Isi respons memiliki konten berikut:
{
"resourceType": "OperationOutcome",
"id": "bd545acc-af5d-42d5-82c3-280459125033",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature."
}
]
}
Menyebabkan: Kami menggunakan identitas terkelola untuk autentikasi penyimpanan sumber. Kesalahan ini mungkin disebabkan oleh penetapan peran yang hilang atau salah.
Solusi: Tetapkan peran Kontributor Data Blob Penyimpanan ke server FHIR mengikuti panduan RBAC.
500 Kesalahan Server Internal
Perilaku: Operasi impor gagal dan 500 Internal Server Error dikembalikan. Isi respons memiliki konten berikut:
{
"resourceType": "OperationOutcome",
"id": "0d0f007d-9e8e-444e-89ed-7458377d7889",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: The database '****' has reached its size quota. Partition or delete data, drop indexes, or consult the documentation for possible resolutions."
}
]
}
Menyebabkan: Anda telah mencapai batas penyimpanan layanan FHIR.
Solusi: Kurangi ukuran data Anda atau pertimbangkan Azure API untuk FHIR, yang memiliki batas penyimpanan yang lebih tinggi.
Langkah berikutnya
Dalam artikel ini, Anda telah mempelajari tentang bagaimana operasi impor memungkinkan impor data FHIR ke server FHIR pada throughput tinggi. Untuk informasi selengkapnya tentang mengonversi data ke FHIR, mengekspor pengaturan untuk menyiapkan akun penyimpanan, dan memindahkan data ke Azure Synapse, lihat
FHIR® adalah merek dagang terdaftar HL7 dan digunakan dengan izin HL7.