Fabric API untuk introspeksi GraphQL dan ekspor skema

Saat Anda membuat aplikasi atau mengintegrasikan alat eksternal dengan Fabric API untuk GraphQL, Anda perlu memahami struktur API Anda—jenis apa yang tersedia, bidang apa yang dikandungnya, dan bagaimana hubungannya satu sama lain. Baik Anda membuat kode klien, membuat dokumentasi, atau mengonfigurasi alat manajemen API, mengakses definisi skema Anda sangat penting.

Fabric API untuk GraphQL menyediakan dua mekanisme pelengkap untuk mengambil informasi skema: introspeksi untuk kueri runtime terprogram dan ekspor skema untuk mendapatkan file skema lengkap. Kedua metode memberi Anda akses ke skema yang mendasar yang sama, tetapi masing-masing melayani alur kerja dan kasus penggunaan yang berbeda.

Tip

Ingin melihat introspeksi dalam tindakan? Coba tutorial Sambungkan Agen AI ke Fabric API untuk GraphQL dengan server Protokol Konteks Model (MCP) lokal. Panduan langsung ini menunjukkan bagaimana agen AI menggunakan introspeksi untuk menemukan dan mengkueri data Fabric Anda secara otomatis menggunakan bahasa alami.

Siapa yang menggunakan introspeksi dan eksportasi skema

Ekspor introspeksi dan skema sangat berharga untuk:

  • Pengembang aplikasi membangun klien yang mengonsumsi data Fabric dan perlu menghasilkan kode jenis aman
  • Kontributor ruang kerja Fabric memahami struktur data yang tersedia dan menguji akses data
  • Alat pengembangan dan IDE yang menyediakan pelengkapan otomatis dan IntelliSense untuk API Fabric GraphQL
  • Integrasi Azure API Management yang merutekan dan mengamankan lalu lintas Fabric GraphQL di tingkat perusahaan
  • Administrator fabric mengaudit struktur data yang diekspos dan memvalidasi kontrol akses
  • Agen dan asisten AI yang menggunakan Model Context Protocol (MCP) untuk menemukan dan mengkueri data Fabric secara alami
  • Pengembang Power Platform memahami skema data Fabric sebelum membangun integrasi
  • Alur CI/CD melacak versi skema Fabric GraphQL dan memvalidasi kompatibilitas di seluruh lingkungan

Pilih introspeksi saat Anda perlu mengkueri informasi skema secara terprogram pada runtime, seperti menggerakkan alat pengembangan, mengaktifkan agen AI, atau menerapkan fitur klien dinamis. Pilih ekspor skema saat Anda memerlukan file skema lengkap untuk penggunaan offline, kontrol versi, integrasi gateway API, atau berbagi dengan tim eksternal.

  • Introspeksi: Mengkueri skema Anda secara terprogram menggunakan sistem introspeksi GraphQL, yang merupakan bagian dari standar GraphQL. Kueri introspeksi memungkinkan Anda menemukan jenis, bidang, dan hubungan secara dinamis, dan mereka mendukung banyak alat pengembangan GraphQL.

  • Ekspor skema: Unduh file SDL (Bahasa Definisi Skema GraphQL) lengkap yang berisi seluruh definisi skema Anda untuk penggunaan offline, berbagi, atau integrasi alat.

Introspeksi

Secara default, introspeksi dinonaktifkan pada API Anda untuk item GraphQL. Pengaturan ini hanya dapat diubah oleh admin ruang kerja. Semua pengguna lain akan melihat penggeser yang dinonaktifkan.

Untuk mengaktifkan introspeksi:

  1. Pilih ikon gerigi Pengaturan API di menu atas.

    Cuplikan layar yang memperlihatkan bilah portal yang memperlihatkan tombol gigi pengaturan.

  2. Dari navigasi kiri, pilih halaman Introspeksi .

    Cuplikan layar yang memperlihatkan penggerak pengaturan introspeksi.

  3. Pilih tombol untuk mengaktifkan introspeksi. Mengaktifkan introspeksi mengekspos informasi skema ke semua pengguna dengan akses ke titik akhir API.

  4. Dialog konfirmasi akan ditampilkan. Pilih Konfirmasi untuk mengaktifkan introspeksi atau Batal untuk membiarkannya dinonaktifkan.

    Cuplikan layar yang memperlihatkan dialog konfirmasi aktifkan introspeksi.

Contoh kueri introspeksi

Berikut adalah contoh cepat kueri introspeksi untuk mengambil jenis yang tersedia dari skema:

  1. Buat kueri baru di editor GraphQL. Pilih ikon plus + di samping tab yang sudah ada untuk membuka tab kueri baru.

    Cuplikan layar yang memperlihatkan tombol kueri baru di editor GraphQL.

  2. Masukkan kueri introspeksi berikut di editor:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Pilih tombol Jalankan untuk menjalankan kueri.

  4. Panel hasil menampilkan daftar semua jenis yang ditentukan dalam skema.

    Cuplikan layar yang memperlihatkan contoh kueri introspeksi.

Kueri introspeksi dapat mengembalikan informasi dalam jumlah besar. Anda dapat mempersempit cakupan apa yang Anda kueri dengan menjadi lebih spesifik dalam permintaan introspeksi Anda. Misalnya, alih-alih mengkueri semua jenis, Anda bisa mengkueri jenis tertentu:

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

Menjalankan kueri mengembalikan informasi terperinci tentang jenisnya ProductCategory :

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

Pola pemfilteran umum saat memproses hasil introspeksi meliputi:

  • Mengecualikan jenis yang dimulai dengan garis bawah ganda (__), yang merupakan jenis sistem GraphQL
  • Termasuk jenis yang dimulai dengan awalan tertentu seperti ProductCategory

Contoh-contoh ini menunjukkan sintaks introspeksi GraphQL standar yang berfungsi di semua implementasi GraphQL. Gambaran umum ini mencakup pola introspeksi dasar—untuk detail komprehensif tentang sistem introspeksi, teknik kueri tingkat lanjut, dan kemampuan tambahan, lihat dokumentasi resmi GraphQL Foundation tentang introspeksi.

Mengekspor skema

Ketika Anda memerlukan salinan lengkap dan offline dari definisi skema Anda, gunakan fitur ekspor skema langsung dari portal Fabric. Buka API Anda untuk GraphQL dan pilih Ekspor skema dari toolbar. Browser Anda mengunduh file SDL (Bahasa Definisi Skema) yang berisi definisi skema lengkap Anda.

Cuplikan layar yang memperlihatkan tombol skema ekspor.

Memahami file SDL

File yang diekspor menggunakan Schema Definition Language (SDL) GraphQL, format yang dapat dibaca manusia yang menentukan jenis, bidang, dan hubungan API Anda. File SDL meliputi:

  • Jenis objek yang mewakili entitas data Anda dengan bidangnya
  • Operasi kueri yang menentukan cara mengambil data
  • Operasi mutasi untuk membuat, memperbarui, atau menghapus data
  • Argumen bidang yang menentukan parameter input dan jenisnya
  • Deskripsi tipe menyediakan dokumentasi untuk setiap elemen

Anda dapat membuka file SDL di editor teks apa pun untuk meninjau struktur skema Anda. Ini sangat berguna untuk memahami permukaan API lengkap sebelum mengintegrasikannya ke dalam aplikasi Anda.

Menggunakan skema yang diekspor

Kasus penggunaan umum untuk file SDL yang diekspor meliputi:

  • Integrasi gateway API: Impor ke Azure API Management untuk menambahkan autentikasi, pembatasan laju, dan caching
  • Penyiapan lingkungan pengembangan: Mengonfigurasi IntelliSense di Visual Studio Code untuk pelengkapan dan validasi otomatis
  • Kontrol versi: Berkomitmen ke Git atau sistem kontrol sumber lainnya untuk melacak evolusi skema dari waktu ke waktu
  • Kolaborasi tim: Berbagi dengan mitra eksternal atau tim pengembangan yang perlu memahami struktur API Anda
  • Pembuatan kode: Gunakan dengan generator kode GraphQL untuk membuat klien jenis aman di TypeScript, C#, Java, atau bahasa lain
  • Dokumentasi: Membuat dokumentasi referensi API menggunakan alat seperti GraphQL Voyager atau GraphQL Markdown

Tidak seperti kueri introspeksi, ekspor skema tidak memerlukan introspeksi untuk diaktifkan dan berfungsi terlepas dari pengaturan introspeksi API Anda. Ini menjadikannya cara yang dapat diandalkan untuk mengakses definisi skema Anda untuk tujuan administratif dan pengembangan.

Mengelola perubahan skema

Skema GraphQL dapat berkembang dari waktu ke waktu saat Anda menambahkan jenis, bidang, atau kemampuan baru ke API Anda. Ketika skema berubah, file SDL yang diekspor menjadi kedaluarsa. Pertimbangkan praktik ini:

  • Ekspor ulang setelah perubahan: Unduh file SDL baru setiap kali Anda memodifikasi skema API Anda di Fabric. Perubahan skema termasuk menambahkan sumber data, memodifikasi jenis yang diekspos, atau memperbarui definisi bidang.
  • Kontrol versi: Terapkan setiap skema yang diekspor ke sistem kontrol sumber Anda dengan pesan penerapan deskriptif. Ini membuat jejak audit dari evolusi skema dan memungkinkan rollback jika diperlukan.
  • Komunikasi: Jika tim atau aplikasi eksternal bergantung pada skema Anda, beri tahu mereka tentang perubahan signifikan. Meskipun GraphQL mendukung perubahan aditif tanpa merusak kueri yang ada, menghapus atau mengganti nama bidang dapat memengaruhi klien.
  • Otomatisasi: Untuk alur CI/CD, pertimbangkan untuk mengotomatiskan ekspor skema sebagai bagian dari proses penyebaran Anda untuk memastikan dokumentasi dan alat tetap disinkronkan dengan API Anda.

Orang yang bertanggung jawab untuk memodifikasi skema API (biasanya teknisi data atau pengembang API) harus mengekspor dan membuat versi skema yang diperbarui untuk mempertahankan konsistensi antara Fabric API dan sistem eksternal yang bergantung padanya.

Konten terkait

  • Last updated on