Bagikan melalui

Menyambungkan aplikasi ke Fabric API untuk GraphQL

Menghubungkan aplikasi ke API Fabric untuk GraphQL memungkinkan aplikasi web, seluler, dan backend Anda untuk mengkueri sumber data Fabric menggunakan API modern dan efisien. Integrasi ini memerlukan autentikasi yang tepat melalui ID Microsoft Entra dan konfigurasi aplikasi Anda untuk memanggil titik akhir GraphQL dengan aman.

Artikel ini memandu Anda menyambungkan aplikasi React ke Fabric GraphQL API dengan:

  1. Membuat dan mengonfigurasi aplikasi Microsoft Entra untuk autentikasi
  2. Menyiapkan sampel GraphQL API di Fabric dengan data untuk dikueri
  3. Mengkloning dan mengonfigurasi aplikasi React lengkap dari GitHub
  4. Menguji koneksi yang diautentikasi

Tutorial ini menggunakan React, tetapi konsep autentikasi berlaku untuk bahasa apa pun. Untuk sampel dalam C#, Python, atau bahasa lain, lihat repositori GitHub Sampel Microsoft Fabric.

Siapa yang perlu menghubungkan aplikasi

Penyiapan koneksi aplikasi sangat penting untuk:

  • Pengembang web dan seluler membangun aplikasi yang mengonsumsi data dari fabric lakehouse dan gudang data.
  • Pengembang integrasi yang menghubungkan data Fabric ke aplikasi kustom dan alur kerja otomatis
  • Pengembang backend membuat layanan yang terintegrasi dengan platform analitik terpadu Fabric
  • Teknisi data menyiapkan alur kerja pemrosesan data otomatis yang menggunakan data Fabric melalui API

Gunakan panduan ini saat Anda perlu mengautentikasi dan mengotorisasi aplikasi untuk mengakses FABRIC GraphQL API Anda.

Prasyarat

  • Alat pengembangan: Anda memerlukan Node.js (versi LTS) dan Visual Studio Code yang terinstal di komputer Anda.

  • Sebelum menyambungkan aplikasi, pastikan Anda memiliki API untuk GraphQL di Fabric. Untuk informasi selengkapnya, lihat Membuat API untuk GraphQL di Fabric dan menambahkan data.

  • API untuk GraphQL mengharuskan aplikasi menggunakan Microsoft Entra untuk autentikasi. Daftarkan dan konfigurasikan aplikasi Anda untuk melakukan panggilan API terhadap Fabric. Untuk informasi selengkapnya, lihat Membuat aplikasi Microsoft Entra di Azure.

  • Kredensial terautentikasi (prinsipal pengguna, perwakilan layanan, atau identitas terkelola) yang memanggil API memerlukan izin Eksekusi untuk API GraphQL (opsi Menjalankan Kueri dan Mutasi saat menambahkan izin akses langsung). Jika menggunakan single sign-on (SSO) sebagai opsi konektivitas di API, pastikan kredensial memiliki izin baca atau tulis di sumber data yang dipilih. Untuk informasi selengkapnya, lihat Menyambungkan ke sumber data dan membangun skema Anda.

Ringkasan autentikasi dan izin

Akses ke API GraphQL memerlukan autentikasi dan otorisasi yang tepat di tingkat API dan tingkat sumber data yang mendasar. Anda dapat mengautentikasi menggunakan perwakilan pengguna (mewakili pengguna individual) atau perwakilan layanan (mewakili aplikasi atau layanan). Untuk konektivitas sumber data, Anda dapat menggunakan akses menyeluruh (SSO) tempat identitas penelepon diteruskan ke sumber data, atau kredensial tersimpan tempat koneksi yang telah dikonfigurasi sebelumnya digunakan.

Tabel berikut ini meringkas berbagai skenario autentikasi yang didukung dan izin minimum yang diperlukan untuk klien yang mengakses API GraphQL:

Pemanggil API Konektivitas sumber data Izin API GraphQL yang diperlukan Izin Sumber Data yang Diperlukan Cakupan aplikasi Microsoft Entra
Prinsipal Pengguna (UPN) Sistem masuk tunggal (SSO) Menjalankan Kueri dan Mutasi di tingkat API Izin Baca/Tulis yang sesuai yang diberikan kepada UPN di sumber data GraphQLApi.Execute.All
Perwakilan Layanan (SPN) Sistem masuk tunggal (SSO) Menjalankan Kueri dan Mutasi di tingkat API Izin Baca/Tulis yang sesuai yang diberikan kepada SPN di sumber data Tidak Berlaku
Prinsipal Pengguna (UPN) Kredensial tersimpan Menjalankan Kueri dan Mutasi di tingkat API Izin Baca/Tulis yang sesuai yang diberikan ke kredensial tersimpan (koneksi) di sumber data GraphQLApi.Execute.All
Perwakilan Layanan (SPN) Kredensial tersimpan Menjalankan Kueri dan Mutasi di tingkat API Izin Baca/Tulis yang sesuai yang diberikan kepada SPN di sumber data Tidak Berlaku

Membuat aplikasi Microsoft Entra

Sebelum aplikasi Anda dapat memanggil Fabric GraphQL API, Anda harus mendaftarkannya di MICROSOFT Entra ID. Pendaftaran ini membuat identitas untuk aplikasi Anda dan menentukan izin apa yang dibutuhkannya. Proses pendaftaran menghasilkan ID Klien (pengidentifikasi aplikasi) dan menetapkan alur autentikasi yang digunakan aplikasi Anda untuk mendapatkan token akses.

Untuk aplikasi React, Anda mengonfigurasi pengaturan aplikasi halaman tunggal (SPA) yang menggunakan alur PKCE—metode autentikasi aman yang dirancang untuk aplikasi berbasis browser di mana rahasia klien tidak dapat disimpan dengan aman.

  1. Daftarkan aplikasi menggunakan langkah-langkah yang dijelaskan pada Panduan Memulai Cepat : Daftarkan aplikasi dengan platform identitas Microsoft.

  2. Nilai ID Aplikasi Microsoft Entra (klien) dan ID Direktori (penyewa) muncul di kotak Ringkasan. Rekam nilai-nilai ini karena Anda membutuhkannya saat mengonfigurasi aplikasi React.

  3. Konfigurasikan izin API sehingga aplikasi Anda dapat mengakses Fabric GraphQL API. Di bawah daftar Kelola , pilih izin API , lalu Tambahkan izin.

  4. Tambahkan Layanan PowerBI, pilih Izin yang didelegasikan, dan pilih izin GraphQLApi.Execute.All . Izin ini memungkinkan aplikasi Anda untuk menjalankan kueri dan mutasi atas nama pengguna yang masuk. Konfirmasikan bahwa persetujuan admin tidak diperlukan.

  5. Kembali ke daftar Kelola, pilih Autentikasi> Tambahkanaplikasi satu halaman>.

  6. Untuk tujuan pengembangan lokal, tambahkan http://localhost:3000 di bawah URI Pengalihan dan konfirmasikan bahwa aplikasi diaktifkan untuk alur kode otorisasi dengan Proof Key for Code Exchange (PKCE). Pilih tombol Konfigurasi untuk menyimpan perubahan Anda. Jika aplikasi mengalami kesalahan yang terkait dengan permintaan lintas asal, tambahkan platform Aplikasi seluler dan desktop di langkah sebelumnya dengan URI pengalihan yang sama.

  7. Kembali ke Autentikasi, gulir ke bawah ke Pengaturan Tingkat Lanjut dan, di bawah Izinkan alur klien publik, pilih Ya untuk Mengaktifkan alur seluler dan desktop berikut.

Menyiapkan sampel GraphQL API untuk akses aplikasi

Dengan aplikasi Microsoft Entra Anda terdaftar, Anda memerlukan API GraphQL di Fabric untuk melakukan query. Bagian ini menuntun Anda membuat API contoh menggunakan set data hari libur umum Fabric. Ini memberi Anda API yang berfungsi untuk menguji autentikasi dan pengambilan data tanpa perlu mengonfigurasi sumber data Anda sendiri.

API sampel memaparkan data hari libur dari tabel Lakehouse, yang dikueri aplikasi React Anda untuk menampilkan hari libur umum.

  1. Dari beranda portal Fabric, pilih Rekayasa Data dari daftar beban kerja.

  2. Dalam pengalaman Rekayasa Data, pilih Gunakan sampel, dan di bawah Lakehouse, pilih Hari libur umum untuk membuat Lakehouse baru secara otomatis dengan data hari libur umum.

    Cuplikan layar tentang memilih contoh opsi data Lakehouse.

  3. Ikuti langkah-langkah dari Buat API untuk GraphQL untuk membuat API GraphQL baru dan pilih Lakehouse yang Anda buat. Tambahkan tabel hari libur nasional sehingga klien dapat mengakses data ini.

    Cuplikan layar menambahkan sampel Lakehouse sebagai sumber data GraphQL.

  4. Sebelum membuat aplikasi React, verifikasi bahwa API Anda berfungsi dengan benar dengan mengujinya di editor API. Gunakan kueri berikut—ini adalah kueri yang sama yang dijalankan aplikasi React Anda nanti:

     query {
 publicholidays (filter: {countryRegionCode: {eq:"US"}, date: {gte: "2024-01-01T00:00:00.000Z", lte: "2024-12-31T00:00:00.000Z"}}) {
     items {
       countryOrRegion
       holidayName
       date
     }
   }
 }

  5. Pilih Salin titik akhir pada toolbar item API.

    Cuplikan layar opsi toolbar untuk item API.

  6. Di layar Salin tautan, pilih Salin.

    Cuplikan layar dialog Salin tautan, memperlihatkan tempat untuk memilih Salin.

  7. Rekam ID Klien dan ID Penyewa dari aplikasi Microsoft Entra dan URI titik akhir. Anda memerlukan nilai-nilai ini saat mengonfigurasi aplikasi React.

Mengkloning dan mengonfigurasi aplikasi React

Setelah menyiapkan aplikasi Microsoft Entra dan GraphQL API, Anda dapat mengonfigurasi aplikasi React untuk menyambungkannya. Aplikasi ini menggunakan Microsoft Authentication Library (MSAL) untuk menangani autentikasi dan membuat permintaan GraphQL dengan token Pembawa.

  1. Kloning repositori sampel dari GitHub:

    git clone https://github.com/microsoft/fabric-samples.git

  2. Navigasikan ke folder aplikasi React:

    cd fabric-samples/docs-samples/data-engineering/GraphQL/React

    Folder berisi aplikasi React lengkap. Anda hanya perlu mengedit src/authConfig.js untuk mengonfigurasi titik akhir dan kredensial spesifik Anda.

  3. Buka proyek di editor kode Anda:

    code .

  4. Di editor Anda, navigasikan ke src folder dan buka authConfig.js.

  5. Ganti nilai placeholder berikut dengan detail spesifik Anda:

    Penting

    Dalam file yang sama, konstanta loginRequest mencakup cakupan https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Cakupan yang tepat ini diperlukan untuk mengakses FABRIC GraphQL API. Jangan hapus atau ubah cakupan ini; jika tidak, autentikasi gagal.

  6. Simpan file.

  7. Di terminal Anda, navigasikan ke folder akar proyek dan jalankan:

    npm install

    Ini menginstal semua dependensi yang diperlukan.

Uji aplikasi

Dengan aplikasi yang dikonfigurasi, jalankan secara lokal untuk memverifikasi semuanya berfungsi dengan benar:

  1. Di terminal Anda, jalankan:

    npm start

    Perintah ini memulai server pengembangan dan membuka aplikasi di browser Anda.

  2. Selesaikan alur autentikasi saat aplikasi dimuat di http://localhost:3000. Ikuti langkah-langkah masuk yang dijelaskan di bagian tutorial Panggil API dari aplikasi.

  3. Setelah berhasil masuk, pilih tombol Query Fabric API untuk Data GraphQL . Ini memicu alur autentikasi, memperoleh token akses, dan menjalankan kueri GraphQL terhadap FABRIC API Anda.

    Cuplikan layar aplikasi sampel React setelah masuk.

  4. Jika semuanya dikonfigurasi dengan benar, aplikasi akan menampilkan hari libur umum dalam tabel. Ini mengonfirmasi bahwa:

    • Aplikasi Microsoft Entra Anda memiliki izin yang benar
    • Token akses berhasil diperoleh
    • API GraphQL mengautentikasi permintaan
    • Kueri yang dijalankan terhadap data Lakehouse

    Cuplikan layar aplikasi sampel React setelah menerima permintaan GraphQL.

Perintah npm lainnya

Selain npm start dan npm install, Anda dapat menggunakan perintah npm umum ini untuk skenario pengembangan yang berbeda:

  • npm run dev - Cara alternatif untuk memulai server pengembangan
  • npm run build - Membuat build produksi yang dioptimalkan dari aplikasi Anda
  • npm run preview - Uji build produksi secara lokal sebelum menyebarkan
  • npm test - Jalankan pengujian otomatis untuk memverifikasi bahwa kode Anda berfungsi dengan benar

Konten terkait

Sekarang setelah Anda memiliki aplikasi kerja yang terhubung ke Fabric GraphQL API Anda, jelajahi sumber daya ini untuk membangun solusi yang lebih canggih:

  • Last updated on