Gambaran umum pencarian FHIR
Spesifikasi Fast Healthcare Interoperability Resources (FHIR®) menentukan API untuk mengkueri sumber daya dalam database server FHIR. Artikel ini memandu Anda melalui beberapa aspek utama kueri data di FHIR. Untuk detail lengkap tentang API pencarian FHIR, lihat dokumentasi Pencarian HL7 FHIR.
Sepanjang artikel ini, kita akan menunjukkan sintaks pencarian FHIR dalam contoh panggilan API dengan {{FHIR_URL}} tempat penampung untuk mewakili URL server FHIR. Dalam kasus layanan FHIR di Azure Health Data Services, URL ini adalah https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.
Pencarian FHIR dapat bertentangan dengan jenis sumber daya tertentu, kompartemen tertentu, atau semua sumber daya dalam database server FHIR. Cara paling sederhana untuk menjalankan pencarian di FHIR adalah dengan menggunakan GET permintaan. Misalnya, jika Anda ingin menarik semua Patient sumber daya dalam database, Anda dapat menggunakan permintaan berikut:
GET {{FHIR_URL}}/Patient
Anda juga dapat mencari menggunakan POST. Untuk mencari menggunakan POST, parameter pencarian dikirimkan dalam isi permintaan. Hal ini memudahkan pengiriman kueri dengan rangkaian parameter yang lebih panjang dan lebih kompleks.
Dengan atau POST GET, jika permintaan pencarian berhasil, Anda akan menerima bundel FHIR searchset yang berisi instans sumber daya yang dikembalikan dari pencarian. Jika pencarian gagal, Anda akan menemukan detail kesalahan dalam respons OperationOutcome .
Di bagian berikut, kita akan membahas berbagai aspek kueri sumber daya di FHIR. Setelah Anda meninjau topik-topik ini, lihat halaman sampel pencarian FHIR, yang menampilkan contoh metode pencarian FHIR yang berbeda.
Parameter pencarian
Saat Anda melakukan pencarian di FHIR, Anda mencari database untuk sumber daya yang cocok dengan kriteria pencarian tertentu. API FHIR menentukan serangkaian parameter pencarian yang kaya untuk menyempurnakan kriteria pencarian. Setiap sumber daya di FHIR membawa informasi sebagai sekumpulan elemen, dan parameter pencarian berfungsi untuk mengkueri informasi dalam elemen-elemen ini. Dalam panggilan API pencarian FHIR, jika kecocokan positif ditemukan antara parameter pencarian permintaan dan nilai elemen terkait yang disimpan dalam instans sumber daya, maka server FHIR mengembalikan bundel yang berisi instans sumber daya yang elemennya memenuhi kriteria pencarian.
Untuk setiap parameter pencarian, spesifikasi FHIR menentukan jenis data yang dapat digunakan. Dukungan dalam layanan FHIR untuk berbagai jenis data diuraikan di bawah ini.
| Jenis parameter pencarian | Layanan FHIR di Azure Health Data Services | Azure API untuk FHIR | Komentar |
|---|---|---|---|
| number | Ya | Ya | |
| date | Ya | Ya | |
| string | Ya | Ya | |
| token | Ya | Ya | |
| referensi | Ya | Ya | |
| komposit | Sebagian | Sebagian | Daftar jenis komposit yang didukung diberikan nanti dalam artikel ini. |
| kuantitas | Ya | Ya | |
| uri | Ya | Ya | |
| khusus | Tidak | Tidak |
Parameter pencarian umum
Ada parameter pencarian umum yang berlaku untuk semua sumber daya di FHIR. Ini tercantum di bawah ini, bersama dengan dukungan mereka dalam layanan FHIR:
| Parameter pencarian umum | Layanan FHIR di Azure Health Data Services | Azure API untuk FHIR | Komentar |
|---|---|---|---|
_id |
Ya | Ya | |
_lastUpdated |
Ya | Ya | |
_tag |
Ya | Ya | |
_type |
Ya | Ya | |
_security |
Ya | Ya | |
_profile |
Ya | Ya | |
_has |
Ya | Ya | |
_query |
No | No | |
_filter |
No | No | |
_list |
No | No | |
_text |
No | No | |
_content |
No | Tidak |
Parameter khusus sumber daya
Layanan FHIR di Azure Health Data Services mendukung hampir semua parameter pencarian khusus sumber daya yang ditentukan dalam spesifikasi FHIR. Parameter pencarian yang tidak didukung tercantum dalam tautan di bawah ini:
Anda juga dapat melihat dukungan saat ini untuk parameter pencarian di Pernyataan Kemampuan FHIR dengan permintaan berikut:
GET {{FHIR_URL}}/metadata
Untuk melihat parameter pencarian yang didukung dalam pernyataan kemampuan, navigasikan ke CapabilityStatement.rest.resource.searchParam untuk parameter pencarian khusus sumber daya dan CapabilityStatement.rest.searchParam untuk parameter pencarian yang berlaku untuk semua sumber daya.
Catatan
Layanan FHIR di Azure Health Data Services tidak secara otomatis mengindeks parameter pencarian yang tidak ditentukan dalam spesifikasi FHIR dasar. Namun, layanan FHIR memang mendukung parameter pencarian kustom.
Parameter pencarian komposit
Pencarian komposit di FHIR memungkinkan Anda mencari terhadap pasangan elemen sebagai unit yang terhubung secara logis. Misalnya, jika Anda mencari pengamatan di mana tinggi pasien lebih dari 60 inci, Anda ingin memastikan bahwa satu properti pengamatan berisi kode tinggi dan nilai yang lebih besar dari 60 inci (nilai seharusnya hanya berkaitan dengan tinggi). Anda tidak ingin mengembalikan kecocokan positif pada pengamatan dengan kode tinggi dan lengan untuk lengan panjang lebih dari 60 inci, misalnya. Parameter pencarian komposit mencegah masalah ini dengan mencari pasangan elemen yang telah ditentukan sebelumnya yang nilainya harus memenuhi kriteria pencarian agar kecocokan positif terjadi.
Layanan FHIR di Azure Health Data Services mendukung pasangan jenis parameter pencarian berikut untuk pencarian komposit:
- Referensi, Token
- Token, Tanggal
- Token, Angka, Angka
- Token, Kuantitas
- Token, String
- Token, Token
Untuk informasi selengkapnya, lihat dokumentasi Parameter Pencarian Komposit HL7.
Catatan
Parameter pencarian komposit tidak mendukung pengubah, sesuai spesifikasi FHIR.
Pengubah & awalan
Pengubah memungkinkan Anda untuk memenuhi syarat parameter pencarian dengan kondisi tambahan. Di bawah ini adalah daftar pengubah FHIR dan dukungan mereka dalam layanan FHIR:
| Pengubah | Layanan FHIR di Azure Health Data Services | Azure API untuk FHIR | Komentar |
|---|---|---|---|
:missing |
Ya | Ya | |
:exact |
Ya | Ya | |
:contains |
Ya | Ya | |
:text |
Ya | Ya | |
:type (referensi) |
Ya | Ya | |
:not |
Ya | Ya | |
:below (uri) |
Ya | Ya | |
:above (uri) |
Ya | Ya | |
:in (token) |
Tidak | Tidak | |
:below (token) |
Tidak | Tidak | |
:above (token) |
Tidak | Tidak | |
:not-in (token) |
Tidak | No | |
:identifier |
No | Tidak |
Untuk parameter pencarian yang memiliki urutan tertentu (angka, tanggal, dan jumlah), Anda dapat menggunakan awalan sebelum nilai parameter untuk memperbaiki kriteria pencarian (misalnya, Patient?_lastUpdated=gt2022-08-01 di mana awalan gt berarti "lebih besar dari"). Layanan FHIR di Azure Health Data Services mendukung semua awalan yang ditentukan dalam standar FHIR.
Parameter hasil pencarian
FHIR menentukan sekumpulan parameter hasil pencarian untuk membantu mengelola informasi yang dikembalikan dari pencarian. Untuk informasi terperinci tentang cara menggunakan parameter hasil pencarian di FHIR, lihat situs web HL7 . Di bawah ini adalah daftar parameter hasil pencarian FHIR dan dukungannya dalam layanan FHIR.
| Parameter hasil pencarian | Layanan FHIR di Azure Health Data Services | Azure API untuk FHIR | Komentar |
|---|---|---|---|
_elements |
Ya | Ya | |
_count |
Ya | Ya | _count dibatasi hingga 1000 sumber daya. Jika diatur lebih tinggi dari 1000, hanya 1000 yang dikembalikan dan peringatan akan disertakan dalam bundel. |
_include |
Ya | Ya | Item yang diambil dengan _include dibatasi hingga 100. _include di PaaS dan OSS di Azure Cosmos DB tidak mendukung :iterate (#2137). |
_revinclude |
Ya | Ya | Item yang diambil dengan _revinclude dibatasi hingga 100. _revinclude di PaaS dan OSS di Azure Cosmos DB tidak mendukung :iterate (#2137). Ada juga kode status yang salah untuk permintaan buruk #1319. |
_summary |
Ya | Ya | |
_total |
Sebagian | Sebagian | _total=none dan _total=accurate |
_sort |
Sebagian | Sebagian | sort=_lastUpdated didukung pada layanan FHIR. Untuk layanan FHIR dan server OSS SQL DB FHIR, pengurutan menurut string dan bidang dateTime didukung. Untuk Azure API untuk database FHIR dan OSS Azure Cosmos DB yang dibuat setelah 20 April 2021, pengurutan didukung pada nama depan, nama belakang, tanggal lahir, dan tanggal klinis. |
_contained |
Tidak | No | |
_containedType |
No | No | |
_score |
No | Tidak |
Catatan:
- Secara default,
_sortmengatur rekaman dalam urutan naik. Anda juga dapat menggunakan awalan-untuk mengurutkan dalam urutan turun. Layanan FHIR hanya memungkinkan Anda mengurutkan satu bidang pada satu waktu. - Layanan FHIR mendukung pencarian wild card dengan revinclude. Menambahkan parameter kueri "." dalam kueri revinclude, ini mengarahkan layanan FHIR untuk mereferensikan semua sumber daya yang dipetakan ke sumber daya sumber.
Secara default, layanan FHIR di Azure Health Data Services diatur ke penanganan yang mudah. Ini berarti bahwa server mengabaikan parameter yang tidak diketahui atau tidak didukung. Jika Anda ingin menggunakan penanganan yang ketat, Anda dapat menyertakan Prefer header dan mengatur handling=strict.
Pencarian berantai & berantai terbalik
Pencarian berantai memungkinkan Anda melakukan kueri yang ditargetkan dengan baik untuk sumber daya yang memiliki referensi ke sumber daya lain. Misalnya, jika Anda ingin menemukan di mana nama pasien adalah Jane, gunakan:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
Dalam . permintaan di atas mengarahkan jalur pencarian berantai ke parameter target (name dalam hal ini).
Demikian pula, Anda dapat melakukan pencarian berantai terbalik dengan _has parameter . Ini memungkinkan Anda untuk mengambil instans sumber daya dengan menentukan kriteria pada sumber daya lain yang mereferensikan sumber daya yang diminati. Untuk contoh pencarian berantai dan berantai terbalik, lihat halaman contoh pencarian FHIR.
Penentuan halaman
Seperti disebutkan di atas, hasil dari pencarian FHIR tersedia dalam formulir paginated pada tautan yang disediakan dalam searchset bundel. Secara default, layanan FHIR menampilkan 10 hasil pencarian per halaman, tetapi ini dapat ditingkatkan (atau dikurangi) dengan mengatur _count parameter. Jika ada lebih banyak kecocokan daripada yang pas di satu halaman, bundel menyertakan next tautan. Berulang kali mengambil dari next tautan menghasilkan halaman hasil berikutnya. Perhatikan bahwa _count nilai parameter tidak boleh melebihi 1000.
Saat ini, layanan FHIR di Azure Health Data Services hanya mendukung next tautan dan tidak mendukung first, , lastatau previous tautan dalam bundel yang dikembalikan dari pencarian.
Langkah berikutnya
Sekarang setelah Anda mempelajari dasar-dasar pencarian FHIR, lihat halaman sampel pencarian untuk detail tentang cara mencari menggunakan parameter pencarian, pengubah, dan metode pencarian FHIR lainnya.
FHIR® adalah merek dagang terdaftar HL7 dan digunakan dengan izin HL7.
Saran dan Komentar
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: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk