Gambaran umum pencarian di Azure API untuk FHIR
Penting
Azure API untuk FHIR akan dihentikan pada 30 September 2026. Ikuti strategi migrasi untuk beralih ke layanan FHIR Azure Health Data Services pada tanggal tersebut. Karena penghentian Azure API untuk FHIR, penyebaran baru tidak akan diizinkan mulai 1 April 2025. Layanan Azure Health Data Services FHIR adalah versi Azure API yang berkembang untuk FHIR yang memungkinkan pelanggan mengelola layanan FHIR, DICOM, dan MedTech dengan integrasi ke layanan Azure lainnya.
Spesifikasi Fast Healthcare Interoperability Resources (FHIR®) mendefinisikan dasar-dasar pencarian sumber daya FHIR. Artikel ini akan memandu Anda melalui beberapa aspek utama untuk mencari sumber daya di FHIR. Untuk detail lengkap tentang mencari sumber daya FHIR, lihat Pencarian di Spesifikasi FHIR HL7. Sepanjang artikel ini, kita akan memberikan contoh sintaks pencarian. Setiap pencarian akan bertentangan dengan server FHIR Anda, yang biasanya memiliki URL https://<FHIRSERVERNAME>.azurewebsites.net. Dalam contoh, kita akan menggunakan tempat penampung {{FHIR_URL}} untuk URL ini.
Pencarian FHIR dapat bertentangan dengan jenis sumber daya tertentu, kompartemen tertentu, atau semua sumber daya. Cara paling sederhana untuk menjalankan pencarian di FHIR adalah dengan menggunakan GET permintaan. Misalnya, jika Anda ingin menarik semua pasien dalam database, Anda dapat menggunakan permintaan berikut:
GET {{FHIR_URL}}/Patient
Anda juga dapat mencari menggunakan POST, yang berguna jika string kueri terlalu panjang. Untuk mencari menggunakan POST, parameter pencarian dapat dikirimkan sebagai isi formulir. Ini memungkinkan serangkaian parameter kueri yang lebih panjang dan lebih kompleks yang mungkin sulit dilihat dan dipahami dalam string kueri.
Jika permintaan pencarian berhasil, Anda akan menerima respons bundel FHIR dengan jenis searchset. Jika pencarian gagal, Anda akan menemukan detail kesalahan di OperationOutcome untuk membantu Anda memahami mengapa pencarian gagal.
Di bagian berikut, kita akan membahas berbagai aspek yang terlibat dalam pencarian. Setelah Anda meninjau detail ini, lihat halaman sampel kami yang memiliki contoh pencarian yang dapat Anda buat di Azure API untuk FHIR.
Parameter pencarian
Saat melakukan pencarian, Anda akan mencari berdasarkan berbagai atribut sumber daya. Atribut ini disebut parameter pencarian. Setiap sumber daya memiliki sekumpulan parameter pencarian yang ditentukan. Parameter pencarian harus ditentukan dan diindeks dalam database agar Anda berhasil mencarinya.
Setiap parameter pencarian memiliki jenis data yang ditentukan. Dukungan untuk berbagai jenis data diuraikan di bawah ini:
Peringatan
Saat ini ada masalah saat menggunakan _sort di Azure API untuk FHIR dengan pencarian berantai. Untuk informasi selengkapnya, lihat masalah sumber terbuka #2344. Ini akan diselesaikan selama rilis pada Desember 2021.
| Jenis parameter pencarian | Azure API untuk FHIR | Layanan FHIR di Azure Health Data Services | Komentar |
|---|---|---|---|
| number | Ya | Ya | |
| date | Ya | Ya | |
| string | Ya | Ya | |
| token | Ya | Ya | |
| referensi | Ya | Ya | |
| komposit | Sebagian | Sebagian | Daftar jenis komposit yang didukung dijelaskan 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. Ini tercantum di bawah ini, bersama dengan dukungan mereka dalam Azure API untuk FHIR:
| Parameter pencarian umum | Azure API untuk FHIR | Layanan FHIR di Azure Health Data Services | Komentar |
|---|---|---|---|
| _id | Ya | Ya | |
| _lastUpdated | Ya | Ya | |
| _tag | Ya | Ya | |
| _type | Ya | Ya | |
| _security | Ya | Ya | |
| _Profil | Ya | Ya | |
| _Hsa | Sebagian | Ya | Dukungan untuk _has ada di MVP di Azure API untuk FHIR dan versi OSS yang didukung oleh Azure Cosmos DB. Detail selengkapnya disertakan di bawah bagian penautan di bawah ini. |
| _Query | Tidak | Tidak | |
| _Filter | Tidak | Tidak | |
| _Daftar | Tidak | Tidak | |
| _Teks | Tidak | Tidak | |
| _Konten | Tidak | Tidak |
Parameter khusus sumber daya
Dengan Azure API untuk FHIR, kami mendukung hampir semua parameter pencarian khusus sumber daya yang ditentukan oleh spesifikasi FHIR. Satu-satunya parameter pencarian yang tidak kami dukung tersedia di 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 dalam pernyataan kemampuan, navigasikan ke CapabilityStatement.rest.resource.searchParam untuk melihat parameter pencarian untuk setiap sumber daya dan CapabilityStatement.rest.searchParam menemukan parameter pencarian untuk semua sumber daya.
Catatan
Azure API untuk FHIR tidak secara otomatis membuat atau mengindeks parameter pencarian apa pun yang tidak ditentukan oleh spesifikasi FHIR. Namun, kami memberikan dukungan bagi Anda untuk menentukan parameter pencarian Anda sendiri.
Parameter pencarian komposit
Pencarian komposit memungkinkan Anda mencari terhadap pasangan nilai. Misalnya, jika Anda mencari pengamatan tinggi di mana orang tersebut 60 inci, Anda ingin memastikan bahwa satu komponen pengamatan berisi kode tinggi dan nilai 60. Anda tidak ingin mendapatkan pengamatan di mana berat 60 dan tinggi 48 disimpan, meskipun pengamatan akan memiliki entri yang memenuhi syarat untuk nilai 60 dan kode tinggi, hanya di bagian komponen yang berbeda.
Dengan Azure API untuk FHIR, kami mendukung pasangan jenis parameter pencarian berikut:
- Referensi, Token
- Token, Tanggal
- Token, Angka, Angka
- Token, Kuantitas
- Token, String
- Token, Token
Untuk informasi selengkapnya, lihat Parameter Pencarian Komposit HL7.
Catatan
Parameter pencarian komposit tidak mendukung pengubah sesuai spesifikasi FHIR.
Pengubah & awalan
Pengubah memungkinkan Anda mengubah parameter pencarian. Di bawah ini adalah gambaran umum semua pengubah FHIR dan dukungan di Azure API untuk FHIR.
| Pengubah | Azure API untuk FHIR | Layanan FHIR di Azure Health Data Services | Komentar |
|---|---|---|---|
| :Hilang | Ya | Ya | |
| :Tepat | Ya | Ya | |
| :Berisi | Ya | Ya | |
| teks: | Ya | Ya | |
| :type (referensi) | Ya | Ya | |
| :Tidak | Ya | Ya | |
| :di bawah (uri) | Ya | Ya | |
| :di atas (uri) | Ya | Ya | |
| :in (token) | Tidak | Tidak | |
| :di bawah (token) | Tidak | Tidak | |
| :above (token) | Tidak | Tidak | |
| :not-in (token) | Tidak | Tidak |
Untuk parameter pencarian yang memiliki urutan tertentu (angka, tanggal, dan jumlah), Anda dapat menggunakan awalan pada parameter untuk membantu menemukan kecocokan. Azure API untuk FHIR mendukung semua awalan.
Parameter hasil pencarian
Untuk membantu mengelola sumber daya yang dikembalikan, ada parameter hasil pencarian yang dapat Anda gunakan dalam pencarian Anda. Untuk detail tentang cara menggunakan setiap parameter hasil pencarian, lihat situs web HL7 .
| Parameter hasil pencarian | Azure API untuk FHIR | Layanan FHIR di Azure Health Data Services | Komentar |
|---|---|---|---|
| _Elemen | Ya | Ya | |
| _Menghitung | Ya | Ya | _count dibatasi hingga 1000 sumber daya. Jika diatur lebih tinggi dari 1000, hanya 1000 yang akan dikembalikan dan peringatan akan dikembalikan dalam bundel. |
| _Termasuk | Ya | Ya | Item yang disertakan dibatasi hingga 100. _include di PaaS dan OSS di Azure Cosmos DB tidak menyertakan :iterate support (#2137). |
| _revinclude | Ya | Ya | Item yang disertakan dibatasi hingga 100. _revinclude di PaaS dan OSS di Azure Cosmos DB tidak menyertakan :iterate support (#2137). Ada juga kode status yang salah untuk permintaan buruk #1319 |
| _Ringkasan | Ya | Ya | |
| _Total | Sebagian | Sebagian | _total=none dan _total=akurat |
| _Semacam | Sebagian | Sebagian | sort=_lastUpdated didukung di Azure API untuk FHIR dan layanan FHIR. 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. |
| _Terkandung | Tidak | Tidak | |
| _containedType | Tidak | Tidak | |
| _Skor | Tidak | No |
Catatan
Secara default _sort mengurutkan rekaman dalam urutan naik. Anda dapat menggunakan prefiks '-' untuk mengurutkan dalam urutan menurung. Selain itu, layanan FHIR dan Azure API untuk FHIR hanya memungkinkan Anda mengurutkan satu bidang pada satu waktu.
Secara default, Azure API untuk FHIR diatur ke penanganan lenient. Ini berarti bahwa server akan mengabaikan parameter yang tidak diketahui atau tidak didukung. Jika Anda ingin menggunakan penanganan yang ketat, Anda dapat menggunakan header Prefer dan mengatur handling=strict.
Pencarian berantai & berantai terbalik
Pencarian berantai memungkinkan Anda mencari menggunakan parameter pencarian pada sumber daya yang direferensikan oleh sumber daya lain. Misalnya, jika Anda ingin menemukan di mana nama pasien adalah Jane, gunakan:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
Demikian pula, Anda dapat melakukan pencarian yang dirantai terbalik. Ini memungkinkan Anda mendapatkan sumber daya di mana Anda menentukan kriteria pada sumber daya lain yang merujuk ke sana. Untuk contoh lebih lanjut pencarian berantai dan berantai terbalik, lihat halaman contoh pencarian FHIR.
Catatan
Di Azure API untuk FHIR dan sumber terbuka yang didukung oleh Azure Cosmos DB, ada batasan di mana setiap subkueri yang diperlukan untuk pencarian berantai dan berantai terbalik hanya akan mengembalikan 1000 item. Jika ada lebih dari 1000 item yang ditemukan, Anda akan menerima pesan kesalahan berikut: "Subkueri dalam ekspresi berantai tidak dapat mengembalikan lebih dari 1000 hasil, gunakan kriteria yang lebih selektif." Untuk mendapatkan kueri yang berhasil, Anda harus lebih spesifik dalam apa yang Anda cari.
Paginasi
Seperti disebutkan di atas, hasil dari pencarian akan menjadi bundel halaman. Secara default, pencarian akan mengembalikan 10 hasil per halaman, tetapi ini dapat ditingkatkan (atau dikurangi) dengan menentukan _count. Dalam bundel, akan ada tautan mandiri yang berisi hasil pencarian saat ini. Jika ada kecocokan tambahan, bundel akan berisi tautan berikutnya. Anda dapat terus menggunakan tautan berikutnya untuk mendapatkan halaman hasil berikutnya. _count dibatasi hingga 1000 item atau kurang.
Tautan berikutnya dalam bundel memiliki batas ukuran token kelanjutan 3KB. Anda memiliki fleksibilitas untuk mengubah ukuran token kelanjutan antara 1 hingga 3KB, menggunakan header "x-ms-documentdb-responsecontinuationtokenlimitinkb".
Saat ini, Azure API untuk FHIR hanya mendukung tautan berikutnya dalam bundel, dan tidak mendukung tautan pertama, terakhir, atau sebelumnya.
Langkah berikutnya
Sekarang setelah Anda mempelajari dasar-dasar pencarian, lihat halaman sampel pencarian untuk detail tentang cara mencari menggunakan parameter pencarian, pengubah, dan skenario 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