Mengakses layanan FHIR dengan menggunakan Postman

Artikel ini memperlihatkan langkah-langkah untuk mengakses layanan FHIR® di Azure Health Data Services dengan Postman.

Prasyarat

• Layanan FHIR disebarkan di Azure. Untuk informasi selengkapnya, lihat Menyebarkan layanan FHIR.
• Postman diinstal secara lokal. Untuk informasi selengkapnya, lihat Mulai menggunakan Postman.
• Peran Administrator Akses Pengguna untuk penetapan peran pada layanan FHIR.

Langkah-langkah penyiapan

Untuk mengakses layanan FHIR dari aplikasi Postman , tinjau langkah-langkahnya:

1. Daftarkan aplikasi klien (Pendaftaran Aplikasi) di ID Microsoft Entra.

2. Tetapkan peran Kontributor Data FHIR di bawah layanan FHIR.

3. Penyiapan Postman - Membuat Ruang Kerja, koleksi, dan lingkungan

Mendaftarkan aplikasi Klien di Microsoft Entra ID

1. Di portal Azure, pilih petak Microsoft Entra ID.

2. Pilih Pendaftaran aplikasi di bagian Kelola.

3. Pilih + Pendaftaran baru.

4. Masukkan nama untuk pendaftaran aplikasi. Di bawah Jenis akun yang didukung, pilih Akun di direktori organisasi ini saja. pilih Daftar.

ID aplikasi (ID klien)

Setelah mendaftarkan aplikasi baru, Anda dapat menemukan ID Aplikasi (klien) dan ID Direktori (penyewa) di bagian Gambaran Umum. Catat nilai-nilai ini untuk digunakan nanti, karena Anda akan membutuhkannya saat mengonfigurasi lingkungan Postman Anda.

Pengaturan autentikasi: rahasia vs. publik

• Pilih Autentikasi untuk meninjau pengaturan. Nilai default untuk Izinkan alur klien publik adalah "Tidak".

• Jika Anda menyimpan nilai default ini, pendaftaran aplikasi adalah aplikasi klien rahasia dan sertifikat atau rahasia diperlukan.

• Jika Anda mengubah nilai default menjadi "Ya" untuk opsi "Izinkan alur klien publik" di pengaturan lanjutan, pendaftaran aplikasi adalah aplikasi klien publik dan sertifikat atau rahasia tidak diperlukan.
  

• Nilai "Ya" berguna saat Anda ingin menggunakan aplikasi klien di aplikasi seluler atau aplikasi JavaScript tempat Anda tidak ingin menyimpan rahasia apa pun.

• Untuk alat yang memerlukan URL pengalihan, pilih Tambahkan platform untuk mengonfigurasi platform.

• Untuk Postman, pilih Aplikasi seluler dan desktop. Masukkan "https://www.getpostman.com/oauth2/callback" di bagian URI pengalihan kustom. Pilih tombol Konfigurasi untuk menyimpan pengaturan.

Sertifikat & rahasia

1. Klik Sertifikat dan rahasia. Klik +Rahasia klien baru.

2. Di bawah Tambahkan rahasia klien, masukkan nama untuk rahasia di bidang Deskripsi . Panduannya adalah menetapkan 6 bulan untuk kedaluwarsa rahasia. Klik Tambahkan.

3. Penting bagi Anda untuk menyimpan nilai rahasia, bukan ID rahasia.

Catatan

Gunakan grant_type client_credentials saat mencoba mendapatkan token akses untuk layanan FHIR menggunakan alat seperti Postman atau Rest Client.

Menetapkan peran Kontributor Data FHIR dalam layanan FHIR

Bagian ini memperlihatkan langkah-langkah untuk menetapkan peran Kontributor Data FHIR ke aplikasi terdaftar untuk layanan FHIR® di Azure Health Data Services.

1. Di portal Azure, navigasikan ke layanan FHIR Anda.

2. Di menu sebelah kiri, pilih bilah Kontrol Akses (IAM). Klik + Tambahkan lalu pilih Tambahkan penetapan peran. Jika opsi untuk menambahkan penetapan peran tidak tersedia, minta administrator Azure Anda untuk menetapkan izin kepada Anda untuk melakukan langkah ini.

3. Di Tambahkan penetapan peran di bawah tab Peran , gulir ke bawah dalam daftar dan pilih Kontributor Data FHIR. Lalu, klik Berikutnya.

4. Di bawah tab Anggota, klik +Pilih anggota. Ketik nama aplikasi klien layanan Postman Anda di bidang Pilih di sebelah kanan. Pilih aplikasi.

5. Dengan cara yang sama, Ketik nama pengguna Anda di Pilih. Pilih pengguna Anda sehingga ditambahkan ke daftar bersama dengan pendaftaran aplikasi dan klik Pilih. Lalu, klik Berikutnya.

6. Di bawah tab Tinjau + tetapkan , klik Tinjau + tetapkan.

Menyiapkan Postman - Membuat Ruang Kerja, koleksi, dan lingkungan.

Jika Anda baru menggunakan Postman, ikuti langkah-langkah ini untuk membuat ruang kerja, koleksi, dan lingkungan.

Postman memperkenalkan konsep ruang kerja untuk memungkinkan Anda dan tim Anda berbagi API, koleksi, lingkungan, dan komponen lainnya. Anda dapat menggunakan ruang kerja Saya atau ruang kerja Tim default atau membuat ruang kerja baru untuk Anda atau tim Anda.

Selanjutnya, buat koleksi baru tempat Anda dapat mengelompokkan semua permintaan REST API terkait. Di ruang kerja, pilih Buat Koleksi. Anda dapat menyimpan nama default Koleksi baru atau mengganti namanya. Perubahan disimpan secara otomatis.

Anda juga dapat mengimpor dan mengekspor koleksi Postman. Untuk informasi selengkapnya, lihat dokumentasi Postman.

Membuat atau memperbarui variabel lingkungan

Meskipun Anda dapat menggunakan URL lengkap dalam permintaan, kami sarankan Anda menyimpan URL dan data lainnya dalam variabel.

Untuk mengakses layanan FHIR, Anda perlu membuat atau memperbarui variabel ini:

Variabel	Keterangan	Catatan
tenantid	Penyewa Azure tempat layanan FHIR disebarkan	Terletak di ringkasan Pendaftaran aplikasi
subid	Langganan Azure tempat layanan FHIR disebarkan	Terletak di gambaran umum layanan FHIR
clientid	ID pendaftaran klien aplikasi
clientsecret	Rahasia pendaftaran klien aplikasi
fhirurl	URL lengkap layanan FHIR (misalnya, https://xxx.azurehealthcareapis.com)	Terletak di gambaran umum layanan FHIR
bearerToken	Menyimpan token akses Microsoft Entra dalam skrip	Biarkan kosong

Catatan

Pastikan Anda mengonfigurasi URL https://www.getpostman.com/oauth2/callback pengalihan dalam pendaftaran aplikasi klien.

Dapatkan pernyataan kapabilitas

Masukkan {{fhirurl}}/metadata dalam GET permintaan, lalu pilih Send. Anda akan melihat pernyataan kemampuan layanan FHIR.

Mendapatkan token akses Microsoft Entra

Dapatkan token akses Microsoft Entra dengan memilih perwakilan layanan, atau akun pengguna Microsoft Entra.

Menggunakan perwakilan layanan dengan jenis pemberian kredensial klien

Layanan FHIR diamankan oleh ID Microsoft Entra. Autentikasi default tidak dapat dinonaktifkan. Untuk mengakses layanan FHIR, Anda perlu mendapatkan token akses Microsoft Entra terlebih dahulu. Untuk informasi selengkapnya, lihat platform identitas Microsoft token akses.

Buat permintaan baru POST :

1. Masukkan header permintaan: https://login.microsoftonline.com/{{tenantid}}/oauth2/token

2. Pilih tab Isi dan pilih x-www-form-urlencoded. Masukkan nilai berikut di bagian kunci dan nilai:

   • grant_type:Client_Credentials
   • client_id:{{clientid}}
   • client_secret:{{clientsecret}}
   • sumber daya: {{fhirurl}}

Catatan

Dalam skenario di mana parameter audiens layanan FHIR tidak dipetakan ke URL titik akhir layanan FHIR, nilai parameter sumber daya harus dipetakan ke nilai audiens pada panel Autentikasi layanan FHIR.

3. Pilih tab Uji dan masukkan pm.environment.set("bearerToken", pm.response.json().access_token); di bagian teks. Untuk membuat nilai tersedia untuk koleksi, gunakan metode pm.collectionVariables.set. Untuk informasi selengkapnya tentang metode yang ditetapkan dan tingkat cakupannya, lihat Menggunakan variabel dalam skrip.
4. Pilih Simpan untuk menyimpan pengaturan.
5. Pilih Kirim. Anda akan melihat respons dengan token akses Microsoft Entra, yang secara otomatis disimpan ke variabel bearerToken. Anda kemudian dapat menggunakannya di semua permintaan API layanan FHIR.

Anda dapat memeriksa token akses menggunakan alat online seperti https://jwt.ms. Pilih tab Klaim untuk melihat deskripsi terperinci untuk setiap klaim dalam token.

Menggunakan akun pengguna dengan jenis pemberian kode otorisasi

Anda bisa mendapatkan token akses Microsoft Entra dengan menggunakan kredensial akun Microsoft Entra Anda dan mengikuti langkah-langkah yang tercantum.

1. Verifikasi bahwa Anda adalah anggota penyewa Microsoft Entra dengan izin akses yang diperlukan.

2. Pastikan Anda mengonfigurasi URL https://oauth.pstmn.io/v1/callback pengalihan untuk platform web dalam pendaftaran aplikasi klien.

3. Dalam pendaftaran aplikasi klien di bawah Izin API, tambahkan izin yang didelegasikan User_Impersonation untuk API Azure Healthcare dari API yang digunakan organisasi saya.

4. Di Postman, pilih tab Otorisasi dari koleksi atau Panggilan REST tertentu, pilih Ketik sebagai OAuth 2.0 dan di bawah bagian Konfigurasi Token Baru, atur nilai-nilai ini:

   • URL Panggilan Balik: https://oauth.pstmn.io/v1/callback

   • URL Autentikasi: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize

   • URL Token Akses: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token

   • ID Klien: ID pendaftaran klien aplikasi

   • Rahasia Klien: Rahasia pendaftaran klien aplikasi

   • Cakupan: {{fhirurl}}/.default

   • Autentikasi Klien: Mengirim kredensial klien dalam isi

5. Pilih Dapatkan Token Akses Baru di bagian bawah halaman.

6. Berikan kredensial Pengguna untuk masuk.

7. Setelah Anda menerima token, pilih Gunakan Token.

8. Pastikan token berada di Header Otorisasi panggilan REST.

Periksa token akses menggunakan alat online seperti https://jwt.ms. Pilih tab Klaim untuk melihat deskripsi terperinci untuk setiap klaim dalam token.

Menyambungkan ke server FHIR

Buka Postman, pilih ruang kerja, koleksi, dan lingkungan yang ingin Anda gunakan. + Pilih ikon untuk membuat permintaan baru.

Untuk melakukan pemeriksaan kesehatan pada layanan FHIR, masukkan {{fhirurl}}/health/check permintaan GET, lalu pilih Kirim. Anda akan dapat melihat Status of FHIR service - HTTP Status respons kode dengan 200 dan OverallStatus sebagai Sehat sebagai respons, yang berarti pemeriksaan kesehatan Anda berhasil.

Mendapatkan sumber daya FHIR

Setelah mendapatkan token akses Microsoft Entra, Anda dapat mengakses data FHIR. Dalam permintaan baru GET , masukkan {{fhirurl}}/Patient.

Pilih Token Pembawa sebagai jenis otorisasi. Masukkan {{bearerToken}} di bagian Token . Pilih Kirim. Sebagai respons, Anda akan melihat daftar pasien di sumber daya FHIR Anda.

Membuat atau memperbarui sumber daya FHIR

Setelah mendapatkan token akses Microsoft Entra, Anda dapat membuat atau memperbarui data FHIR. Misalnya, Anda dapat membuat pasien baru atau memperbarui pasien yang ada.

Buat permintaan baru, ubah metode menjadi Posting, dan masukkan nilai di bagian permintaan.

{{fhirurl}}/Patient

Pilih Token Pembawa sebagai jenis otorisasi. Masukkan {{bearerToken}} di bagian Token . Pilih tab Isi . Pilih opsi mentah dan JSON sebagai format teks isi. Salin dan tempel teks berikut ke bagian isi.

{
    "resourceType": "Patient",
    "active": true,
    "name": [
        {
            "use": "official",
            "family": "Kirk",
            "given": [
                "James",
                "Tiberious"
            ]
        },
        {
            "use": "usual",
            "given": [
                "Jim"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1960-12-25"
}

Pilih Kirim. Anda akan melihat pasien baru dalam respons JSON.

Mengekspor data FHIR

Setelah mendapatkan token akses Microsoft Entra, Anda dapat mengekspor data FHIR ke akun penyimpanan Azure.

Untuk mengonfigurasi pengaturan ekspor dan membuat akun Data Lake Storage Gen2, lihat Mengonfigurasi pengaturan untuk ekspor.

Buat permintaan baru GET : {{fhirurl}}/$export?_container=export

Pilih Token Pembawa sebagai jenis otorisasi. Masukkan {{bearerToken}} di bagian Token . Pilih Header untuk menambahkan dua header baru:

• Terima: application/fhir+json

• Lebih suka: respond-async

Pilih Kirim. Anda harus melihat 202 Accepted respons. Pilih tab Header respons dan catat nilai di Lokasi Konten. Anda dapat menggunakan nilai ini untuk mengkueri status pekerjaan ekspor.

Langkah berikutnya

Kumpulan kueri sampel Postman pemula

Catatan

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