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 memandu Anda melalui beberapa aspek utama pencarian sumber daya di FHIR. Untuk detail lengkap tentang mencari sumber daya FHIR, lihat Pencarian di Spesifikasi FHIR HL7. Sepanjang artikel ini, kami memberikan contoh sintaks pencarian. Setiap pencarian bertentangan dengan server FHIR Anda, yang biasanya memiliki URL https://<FHIRSERVERNAME>.azurewebsites.net. Dalam contoh, kami 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 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 menerima respons bundel FHIR dengan jenis searchset. Jika pencarian gagal, Anda dapat menemukan detail kesalahan di OperationOutcome untuk membantu Anda memahami mengapa pencarian gagal.
Di bagian berikut, kami 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
Pencarian didasarkan pada 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. Tabel berikut menguraikan dukungan untuk berbagai jenis data.
Peringatan
Saat ini ada masalah saat menggunakan _sort 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 ada dalam daftar berikut, 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 | |
| _Memiliki | Sebagian | Ya | Dukungan untuk _has berada dalam MVP di Azure API untuk FHIR dan versi OSS yang didukung oleh Azure Cosmos DB. Detail selengkapnya disertakan di bawah bagian penautan berikut. |
| _kueri | Tidak | Tidak | |
| _saringan | Tidak | Tidak | |
| _daftar | Tidak | Tidak | |
| _Teks | Tidak | Tidak | |
| _puas | 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 berikut.
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 untuk CapabilityStatement.rest.resource.searchParam melihat parameter pencarian untuk setiap sumber daya, dan CapabilityStatement.rest.searchParam untuk 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. Tabel berikut adalah gambaran umum semua pengubah FHIR dan dukungannya 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. 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 | |
| _hitung | Ya | Ya | _count dibatasi hingga 1000 sumber daya. Jika diatur lebih tinggi dari 1000, hanya 1000 yang dikembalikan dan peringatan akan dikembalikan dalam bundel. |
| _memasukkan | 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 | |
| _seluruh | Sebagian | Sebagian | _total=none dan _total=akurat |
| _jenis | 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 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.
Penentuan halaman
Seperti yang disebutkan sebelumnya, hasil dari pencarian adalah bundel halaman. Secara default, pencarian 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 1.000 item atau kurang.
Tautan berikutnya dalam bundel memiliki batas ukuran token kelanjutan 3 KB. Anda memiliki fleksibilitas untuk mengubah ukuran token kelanjutan antara 1 KB hingga 3 KB, 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.