Kontrol sumber dan alur penyebaran di API untuk GraphQL

Pelajari cara kerja integrasi Git dan alur penyebaran dengan API untuk GraphQL di Microsoft Fabric. Artikel ini membantu Anda memahami cara menyiapkan koneksi ke repositori Anda, mengelola API untuk GraphQL, dan menyebarkannya di berbagai lingkungan.

Siapa yang menggunakan kontrol dan penyebaran sumber

Integrasi Git dan alur penyebaran sangat penting untuk:

  • Teknisi data yang mengelola konfigurasi Fabric GraphQL API melalui kontrol versi dan alur kerja CI/CD
  • Admin ruang kerja Fabric mengoordinasikan penyebaran di seluruh ruang kerja Fabric untuk pengembangan, pengujian, dan produksi.
  • Tim DevOps menerapkan alur penyebaran untuk FABRIC API di beberapa lingkungan dan kapasitas
  • Tim platform yang memerlukan kemampuan tata kelola, pelacakan, dan pemulihan untuk perubahan API Fabric

Gunakan kontrol sumber dan alur penyebaran saat Anda perlu mengelola API GraphQL sebagai bagian dari siklus hidup pengembangan terstruktur dengan beberapa lingkungan.

Prasyarat

Gambaran Umum

Fabric menawarkan alat yang kuat untuk CI/CD (integrasi berkelanjutan dan penyebaran berkelanjutan) dan manajemen siklus hidup pengembangan melalui dua komponen utama: integrasi Git (CI) dan alur penyebaran (CD). Ruang kerja berfungsi sebagai komponen pusat untuk tahap sinkronisasi dan penyebaran Git.

Integrasi Git (CI): Menyinkronkan item ruang kerja (misalnya, kode, konfigurasi, API) dengan repositori kontrol versi, memungkinkan kontrol versi dan pelacakan perubahan melalui Git.

Alur penyebaran (CD): Memungkinkan pembuatan tahapan (misalnya, Pengembangan, Pengujian, Produksi) dengan ruang kerja tertaut. Item yang didukung di setiap tahap secara otomatis direplikasi ke tahap berikutnya, dan perubahan dalam ruang kerja memicu penyebaran dalam alur rilis. Anda dapat mengonfigurasi alur untuk memastikan bahwa perubahan diuji dan disebarkan secara efisien di seluruh lingkungan.

Fabric mendukung berbagai alur kerja CI/CD yang disesuaikan dengan skenario umum. Untuk informasi selengkapnya, lihat Opsi alur kerja CI/CD di Fabric.

Nota

Hanya metadata yang disalin selama penyebaran; dan data tidak disalin.

Item dari ruang kerja disimpan di repositori Git terkait sebagai Infrastruktur sebagai Kode (IaC). Perubahan kode di repositori dapat memicu penyebaran dalam jalur pipa. Metode ini memungkinkan Anda memiliki perubahan kode yang direplikasi secara otomatis di seluruh tahap untuk tujuan pengujian dan rilis produksi.

Metode autentikasi sumber data

Saat membuat API untuk GraphQL, Anda memilih cara klien mengautentikasi dan mengakses sumber data Anda. Pilihan ini memiliki implikasi signifikan untuk alur penyebaran dan perilaku pengikatan otomatis. Memahami metode autentikasi ini sangat penting untuk merencanakan alur kerja CI/CD Anda. Untuk informasi selengkapnya tentang pengikatan otomatis dan proses penyebaran, lihat Memahami proses penyebaran.

Ada dua opsi konektivitas yang tersedia saat menyambungkan sumber data ke API Anda untuk GraphQL: Akses menyeluruh (SSO) dan Kredensial tersimpan.

Cuplikan layar opsi untuk koneksi GraphQL ke sumber data.

Sistem masuk tunggal (SSO)

Dengan SSO, klien API menggunakan kredensial mereka sendiri untuk mengakses sumber data. Pengguna API yang diautentikasi harus memiliki izin ke API dan sumber data yang mendasar.

Gunakan SSO saat:

  • Mengekspos sumber data Fabric (lakehouse, gudang, titik akhir analitik SQL)
  • Anda ingin pengguna mengakses data berdasarkan izin individual mereka
  • Anda memerlukan keamanan tingkat baris atau kebijakan akses data lainnya untuk diterapkan per pengguna

Persyaratan izin:

  • Pengguna API memerlukan izin Jalankan pada GraphQL API (Jalankan Kueri dan Mutasi)
  • Pengguna API memerlukan izin baca atau tulis di sumber data
  • Atau, tambahkan pengguna sebagai anggota ruang kerja dengan peran Kontributor di mana API dan sumber data berada

Perilaku pengikatan otomatis dalam alur penyebaran: Saat Anda menyebarkan API menggunakan SSO dari ruang kerja sumber (misalnya, Dev) ke ruang kerja target (misalnya, Uji):

  • Sumber data dan GraphQL API keduanya disebarkan ke ruang kerja target
  • API di ruang kerja target secara otomatis mengikat salinan sumber data lokal di ruang kerja target
  • Setiap lingkungan (Dev, Test, Production) menggunakan instans sumber datanya sendiri

Nota

Ada batasan khusus saat menggunakan SSO dengan Titik Akhir Analitik SQL. Lihat Batasan saat ini untuk detailnya.

Kredensial tersimpan

Dengan kredensial yang disimpan, satu kredensial bersama mengautentikasi antara API dan sumber data. Pengguna API hanya memerlukan akses ke API itu sendiri, bukan sumber data yang mendasar.

Gunakan kredensial tersimpan saat:

  • Mengekspos sumber data Azure (Azure SQL Database, database eksternal)
  • Anda menginginkan manajemen izin yang disederhanakan (pengguna hanya memerlukan akses API)
  • Semua pengguna API harus mengakses data yang sama dengan izin yang sama
  • Anda memerlukan kredensial yang konsisten di semua permintaan API

Persyaratan izin:

  • Pengguna API hanya memerlukan izin Jalankan pada GraphQL API (Jalankan Kueri dan Mutasi)
  • Kredensial yang disimpan itu sendiri harus memiliki izin yang sesuai pada sumber data
  • Pengembang yang menyebarkan API harus memiliki akses ke kredensial yang disimpan

Perilaku pengikatan otomatis dalam alur penyebaran: Saat Anda menyebarkan API menggunakan kredensial yang disimpan dari ruang kerja sumber (Dev) ke ruang kerja target (Uji):

  • Sumber data disebarkan ke ruang kerja target
  • API di ruang kerja target tetap terhubung ke sumber data di ruang kerja sumber (Dev)
  • Pengikatan otomatis tidak terjadi - API yang disebarkan terus menggunakan kredensial tersimpan yang menunjuk ke sumber data asli
  • Anda harus mengonfigurasi ulang koneksi secara manual atau membuat kredensial baru yang disimpan di setiap lingkungan target

Penting

Setelah Anda memilih metode autentikasi untuk API Anda, metode tersebut berlaku untuk semua sumber data yang ditambahkan ke API tersebut. Anda tidak dapat mencampur SSO dan kredensial yang disimpan di API yang sama.

Koneksi lintas ruang kerja

Jika API Anda di ruang kerja sumber (Dev) terhubung ke sumber data di ruang kerja yang berbeda, API yang disebarkan di ruang kerja target (Pengujian) tetap terhubung ke sumber data eksternal tersebut terlepas dari metode autentikasi. Pengikatan otomatis hanya berfungsi saat API dan sumber data berada di ruang kerja sumber yang sama.

Diagram berikut mengilustrasikan skenario penyebaran ini:

Cuplikan layar alur untuk berbagai koneksi dan skenario sumber data.

Untuk informasi selengkapnya tentang menyiapkan metode autentikasi ini saat membuat API Anda, lihat Menyambungkan ke sumber data.

API untuk integrasi Git dengan GraphQL

Fabric API untuk GraphQL mendukung integrasi Git, memungkinkan Anda mengelola API GraphQL sebagai kode dalam sistem kontrol versi Anda. Integrasi ini menyediakan riwayat versi, kolaborasi melalui cabang dan permintaan pull, kemampuan untuk mengembalikan perubahan, dan jejak audit lengkap modifikasi API. Dengan memperlakukan konfigurasi API GraphQL Anda sebagai Infrastruktur sebagai Kode (IaC), Anda dapat menerapkan praktik terbaik pengembangan perangkat lunak ke lapisan akses data Anda.

Integrasi Git sangat penting untuk:

  • Kontrol versi: Lacak semua perubahan pada skema GraphQL, koneksi sumber data, dan hubungan Anda dari waktu ke waktu
  • Kolaborasi: Bekerja dengan anggota tim menggunakan cabang, pull request, dan peninjauan kode
  • Kemampuan pembatalan: Kembali ke konfigurasi API sebelumnya saat masalah muncul
  • Promosi lingkungan: Gunakan Git sebagai sumber kebenaran untuk menyebarkan API di seluruh lingkungan

Menyambungkan ruang kerja Anda ke Git

Untuk mengaktifkan integrasi Git untuk API GraphQL Anda:

  1. Buka pengaturan Ruang Kerja untuk ruang kerja yang berisi API Anda untuk GraphQL
  2. Mengonfigurasi koneksi Git ke repositori Anda (Azure DevOps, GitHub, atau penyedia Git lainnya)
  3. Setelah tersambung, semua item ruang kerja, termasuk API untuk GraphQL, muncul di panel Kontrol sumber

Untuk instruksi penyiapan terperinci, lihat Mulai menggunakan integrasi Git.

Cuplikan layar ruang kerja dan status kontrol sumber.

Menerapkan dan menyinkronkan API GraphQL Anda

Setelah menyambungkan ke Git, Anda dapat menerapkan API untuk konfigurasi GraphQL ke repositori. Setiap penerapan membuat rekam jepret definisi API Anda, termasuk:

  • Definisi skema GraphQL
  • Koneksi sumber data dan pengaturan autentikasi
  • Konfigurasi hubungan
  • Definisi kueri dan mutasi

Setelah diterapkan, API GraphQL Anda muncul di repositori Git Anda dengan hierarki folder terstruktur. Dari titik ini, Anda dapat memanfaatkan alur kerja Git standar seperti membuat permintaan pull, mengelola cabang, dan berkolaborasi dengan tim Anda melalui ulasan kode. Untuk informasi selengkapnya tentang bekerja dengan cabang, lihat Mengelola cabang.

Representasi API GraphQL di Git

Setiap API untuk item GraphQL disimpan di Git dengan struktur folder yang terdefinisi dengan baik yang mewakili semua aspek konfigurasi API Anda:

Cuplikan layar representasi struktur file di Git untuk GraphQL.

File definisi API berisi semua metadata yang diperlukan untuk membuat ulang API GraphQL Anda di ruang kerja Fabric apa pun. Ini termasuk definisi skema, pemetaan sumber data, dan pengaturan konfigurasi. Saat Anda menyinkronkan dari Git kembali ke ruang kerja Fabric, sistem menggunakan file definisi ini untuk memulihkan API Anda dengan tepat seperti saat diterapkan:

Cuplikan layar API untuk definisi GraphQL yang disimpan di Git.

Bekerja dengan file definisi API:

Format definisi GraphQL API mengikuti standar Infrastruktur sebagai Kode (IaC) Fabric. Anda dapat melihat dan mengedit file-file ini langsung di repositori Git Anda, meskipun sebagian besar modifikasi harus dilakukan melalui portal Fabric untuk memastikan validitas skema. File definisi sangat berguna untuk:

  • Tinjauan kode: Anggota tim dapat meninjau perubahan API dalam permintaan pull
  • Dokumentasi: File berfungsi sebagai dokumentasi struktur API Anda
  • Automasi: Alur CI/CD dapat membaca file-file ini untuk memahami konfigurasi API
  • Pemulihan bencana: Definisi API lengkap dipertahankan dalam kontrol versi

Untuk informasi terperinci tentang format, sintaks, dan contoh definisi API GraphQL, lihat dokumentasi API sarana kontrol Fabric:

API untuk GraphQL dalam jalur penerapan

Alur penyebaran memungkinkan Anda mempromosikan API untuk konfigurasi GraphQL di seluruh lingkungan (biasanya Pengembangan, Pengujian, dan Produksi). Saat Anda menyebarkan API untuk GraphQL melalui alur, hanya metadata API yang disalin—termasuk definisi skema, koneksi sumber data, dan konfigurasi hubungan. Data aktual tetap berada di sumber data yang terhubung dan tidak disalin selama penyebaran.

Pertimbangan penyebaran utama:

Sebelum menyebarkan, pahami bagaimana metode autentikasi dan organisasi ruang kerja memengaruhi penyebaran Anda:

  • API yang menggunakan Single Sign-On (SSO) dapat mengikat otomatis ke sumber data lokal di ruang kerja target (ketika sumber data juga disebarkan dari ruang kerja sumber yang sama)
  • API yang menggunakan Kredensial Tersimpan tidak mengikat otomatis dan tetap tersambung ke sumber data ruang kerja sumber
  • Sumber data lintas ruang kerja tidak pernah mengikat otomatis, terlepas dari metode autentikasi

Untuk pemahaman komprehensif tentang proses penyebaran, lihat Memahami proses penyebaran.

Menyebarkan API Anda untuk GraphQL

Untuk menyebarkan API Anda untuk GraphQL menggunakan alur penyebaran:

  1. Buat alur penyebaran baru atau buka alur yang sudah ada. Untuk instruksi mendetail, lihat Mulai menggunakan alur penyebaran.

  2. Tetapkan ruang kerja ke tahap alur (Pengembangan, Pengujian, Produksi) berdasarkan strategi penyebaran Anda. Setiap tahap harus memiliki ruang kerja khusus.

  3. Tinjau dan bandingkan item antar tahap. Alur menunjukkan API mana untuk GraphQL yang telah berubah, yang ditunjukkan oleh jumlah item di area yang disorot. Perbandingan ini membantu Anda memahami apa yang akan terpengaruh oleh penyebaran.

    Cuplikan layar alur yang mengilustrasikan status item di setiap tahap pengembangan.

  4. Pilih API untuk GraphQL dan item terkait apa pun (seperti sumber data tersambung) yang ingin Anda sebarkan. Lalu pilih Sebarkan untuk memindahkannya ke tahap berikutnya.

    Cuplikan layar alur memperlihatkan item terpilih yang perlu disebarkan.

  5. Tinjau dialog konfirmasi penyebaran, yang menunjukkan semua item yang akan disebarkan. Pilih Sebarkan untuk melanjutkan.

    Cuplikan layar alur memperlihatkan pesan konfirmasi penyebaran.

Batasan saat ini

Saat menyebarkan API untuk GraphQL melalui alur penyebaran, pengikatan otomatis memiliki batasan berikut:

  • Item anak: Autobinding tidak berfungsi saat API terhubung ke SQL Analytics Endpoint yang merupakan bagian anak dari sumber data induk (seperti Lakehouse). API yang disebarkan tetap terhubung ke titik akhir ruang kerja sumber.

  • Kredensial Tersimpan: API yang menggunakan metode autentikasi Kredensial Tersimpan tidak mendukung pengikatan otomatis. API tetap terhubung ke sumber data di ruang kerja asal setelah penyebaran. Untuk informasi terperinci tentang metode autentikasi dan perilaku pengikatan otomatisnya, lihat Metode autentikasi sumber data.

  • GraphQL API dan Perubahan Skema Sumber Data Yang Mendasar: API GraphQL di Fabric tidak secara otomatis mendeteksi perubahan skema di sumber data yang mendasarnya. Jika tabel atau tampilan mengubah strukturnya (misalnya, kolom ditambahkan, diganti namanya, atau dihapus), API terus menggunakan skema yang diambil saat dibuat atau terakhir disegarkan, sehingga bidang baru atau jenis yang diperbarui tidak akan muncul secara otomatis. Untuk mencerminkan pembaruan skema, diperlukan refresh manual metadata API — misalnya, dengan membuka item API GraphQL dan memperbarui skemanya (menambahkan atau menghapus kolom), atau dengan menghapus dan menambahkan kembali tabel. Dalam beberapa situasi, mungkin perlu untuk menghapus dan memasang kembali seluruh sumber data untuk sepenuhnya menangkap semua perubahan skema.

Konten terkait

  • Last updated on