Bagikan melalui

Mengembangkan aplikasi GraphQL di Visual Studio Code

Pelajari cara membangun aplikasi front-end dengan React, Apollo Client, dan TypeScript yang terintegrasi dengan API GraphQL yang dihosting di Microsoft Fabric. Tutorial ini mencakup pengaturan alat pengembangan lokal termasuk pelengkapan otomatis, pembuatan kode, dan IntelliSense untuk pengalaman pengembang yang optimal.

Siapa yang harus menggunakan alat pengembangan Visual Studio Code

Pengembangan lokal dengan Visual Studio Code dirancang untuk:

  • Pengembang React membangun aplikasi web yang mengonsumsi data dari lakehouse dan gudang Fabric melalui GraphQL
  • Pengembang TypeScript yang memerlukan pembuatan kode klien jenis aman untuk FABRIC GraphQL API
  • Full-stack developer membangun aplikasi analitik khusus menggunakan platform Fabric dengan dukungan IDE lokal.
  • Tim pengembangan yang menginginkan peralatan modern dengan IntelliSense dan debugging untuk aplikasi akses data Fabric

Gunakan pendekatan ini saat Anda membangun aplikasi React yang membutuhkan dukungan IDE yang kaya, pembuatan kode, dan kemampuan penelusuran kesalahan lokal dengan TypeScript dan Klien Apollo.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

  • Akses ruang kerja Microsoft Fabric: Jadilah anggota ruang kerja Fabric dengan setidaknya peran Kontributor (atau lebih tinggi: Admin, Anggota) untuk membuat dan memodifikasi item API GraphQL
  • Izin sumber data: Izin baca/tulis pada sumber data yang Anda rencanakan untuk diekspos melalui API GraphQL
  • Node.js diinstal pada komputer pengembangan Anda (termasuk npm)
  • Visual Studio Code terinstal pada komputer pengembangan Anda
  • Pengetahuan dasar tentang konsep React, TypeScript, dan GraphQL

Langkah 1: Membuat API GraphQL di Microsoft Fabric

Nota

Panduan ini menunjukkan pembuatan API GraphQL dari konteks database SQL. Anda membuat database SQL terlebih dahulu, lalu membuat API GraphQL langsung dari dalam database tersebut. Jika Anda sudah memiliki API GraphQL yang sudah ada dan ingin menyambungkannya, ikuti panduan Memulai tempat Anda membuat API terlebih dahulu lalu sambungkan ke database SQL atau sumber data lainnya.

Membuat database SQL

Untuk membuat database SQL yang berisi data sampel untuk API GraphQL Anda:

  1. Di ruang kerja Fabric Anda, pilih Item Baru.
  2. Pilih database SQL (pratinjau).
  3. Berikan nama untuk database Anda.
  4. Pilih Contoh data untuk membuat tabel secara otomatis dan mengisinya dengan data sampel. Ini membuat database sampel AdventureWorksLT dengan skema SalesLT, termasuk tabel seperti SalesLT.Customer, SalesLT.Product, dan SalesLT.SalesOrderHeader.

Tip

Jika Anda sudah memiliki database SQL dengan data sampel dari tutorial sebelumnya atau pembuatan API GraphQL, Anda dapat menggunakan kembali database yang sama. Database tunggal dapat mendukung beberapa API GraphQL, jadi tidak perlu membuat database baru jika Anda sudah memilikinya dengan skema SalesLT.

Membuat API GraphQL

Sekarang setelah Anda memiliki database SQL dengan data sampel, buat API GraphQL:

  1. Di database SQL Anda, pilih API Baru untuk GraphQL dari pita.

    Cuplikan layar opsi API Baru untuk GraphQL di pita database SQL.

  2. Berikan nama untuk API Anda.

  3. Pilih semua tabel SalesLT dari database Anda.

  4. Pilih Muat untuk menghasilkan API.

API GraphQL Anda sekarang siap dan tersedia di ruang kerja Fabric Anda.

Langkah 2: Siapkan lingkungan pengembangan Anda

Untuk mengikuti tutorial ini, selesaikan langkah-langkah ini untuk menyiapkan aplikasi pemula React, menginstal dependensi yang diperlukan, dan mengonfigurasi Visual Studio Code dengan dukungan GraphQL.

  1. Klon aplikasi starter - Dapatkan aplikasi starter React dari repositori sampel Microsoft Fabric:

    git clone https://github.com/microsoft/fabric-samples.git
cd fabric-samples/docs-samples/data-engineering/GraphQL/React-Apollo-TS

  2. Instal dependensi - Instal paket yang diperlukan untuk pengembangan GraphQL, pelengkapan otomatis, dan pembuatan kode:

    npm install

  3. Instal ekstensi Visual Studio Code yang diperlukan - Instal ekstensi GraphQL: Dukungan Fitur Bahasa di Visual Studio Code untuk mengaktifkan penyorotan sintaks, validasi, dan IntelliSense untuk operasi GraphQL.

Langkah 3: Mengonfigurasi skema GraphQL Anda

Skema GraphQL menentukan struktur API Anda - data apa yang tersedia, operasi apa yang dapat Anda lakukan, dan hubungan antara berbagai jenis data. Alat pengembangan Anda menggunakan skema ini untuk menyediakan IntelliSense, penyelesaian kode, dan pembuatan jenis, sehingga jauh lebih mudah untuk menulis kueri dan mutasi GraphQL yang benar.

Anda dapat memperoleh skema GraphQL anda dengan dua cara:

Opsi 1: Ekspor skema sebagai file statis

  1. Di Fabric GraphQL API Anda, pilih Ekspor Skema dari pita.
  2. Nama file yang diunduh menyertakan ID GraphQL API Anda (misalnya, GraphQL_your-api-id_schema.graphql). Simpan ke direktori akar proyek Anda dan ganti namanya menjadi schema.graphql - ini adalah nama file yang Anda gunakan dalam langkah-langkah konfigurasi berikut.

Opsi 2: Gunakan titik akhir jarak jauh

  1. Akses API GraphQL yang Anda buat di Portal Fabric.
  2. Mendapatkan token otorisasi menggunakan PowerShell dengan Get-PowerBIAccessToken

Nota

Meskipun opsi titik akhir jarak jauh selalu menyediakan skema paling up-to-date, token yang diambil bersifat sementara dan kedaluwarsa per jam. Mereka harus digunakan hanya untuk tujuan pengujian dan pengembangan, jika memungkinkan menggunakan file statis untuk menghindari masalah dengan kedaluwarsa token.

Langkah 4: Mengonfigurasi IntelliSense dan pelengkapan otomatis

Sekarang Anda akan menyiapkan IntelliSense menggunakan skema dari Langkah 3. File skema (baik statis atau dari titik akhir jarak jauh) memungkinkan Visual Studio Code untuk memberikan saran kode real time, deteksi kesalahan, dan validasi bidang saat Anda menulis kueri GraphQL.

Buat file konfigurasi di akar proyek Anda:

Menggunakan file skema statis

Gunakan konfigurasi berikut jika Anda mengekspor skema sebagai file statis:

Buat .graphqlrc.yml:

schema: './schema.graphql'
documents: 'src/**/*.{ts,tsx,graphql,gql}'

Menggunakan titik akhir jarak jauh

Gunakan konfigurasi berikut jika Anda lebih suka mengambil skema langsung dari titik akhir GraphQL API Anda:

Buat graphql.config.yml:

schema:
  - https://your-graphql-endpoint.com/graphql:
      headers:
        Authorization: Bearer YOUR_ACCESS_TOKEN
documents: src/**/*.{ts,tsx,graphql,gql}

Opsi konfigurasi

  • skema: Menentukan lokasi skema GraphQL Anda
  • dokumen: Menentukan file mana yang harus memiliki dukungan IntelliSense

Setelah membuat file konfigurasi, mulai ulang Visual Studio Code untuk memastikan perubahan diterapkan.

Langkah 5: Menyiapkan pembuatan kode

Pembuatan kode GraphQL secara otomatis membuat antarmuka TypeScript yang diketik dengan kuat dan kait React dari skema dan operasi Anda, mengurangi kesalahan dan meningkatkan efisiensi pengembangan. Tujuan utamanya adalah untuk meningkatkan keamanan jenis dan menyederhanakan pengembangan dalam proyek GraphQL, terutama ketika bekerja dengan bahasa yang sangat diketik seperti TypeScript.

Membuat konfigurasi codegen

Opsi file statis

Jika Anda mengekspor skema sebagai file statis, buat codegen.yml di akar proyek Anda:

schema: './schema.graphql'
documents: './src/**/*.graphql'
generates:
  src/generated/graphql.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true

Opsi titik akhir jarak jauh

Jika Anda menggunakan pendekatan titik akhir jarak jauh, buat codegen.yml di akar proyek Anda:

schema:
  - https://your-graphql-endpoint.com/graphql:
      headers:
        Authorization: Bearer YOUR_ACCESS_TOKEN
documents: 'src/**/*.{ts,tsx,graphql,gql}'
generates:
  src/generated/graphql.tsx:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true

Perincian konfigurasi

  • skema: Jalur ke file skema atau titik akhir jarak jauh Anda
  • dokumen: Pola glob untuk menemukan file operasi GraphQL
  • generates: Menentukan file output untuk kode yang dihasilkan
  • plugin: Menentukan kode apa yang akan dihasilkan (jenis TypeScript dan kait React Apollo)

Menambahkan skrip codegen

Tambahkan skrip pembuatan kode ke package.json file di direktori proyek Anda (file ini disertakan saat Anda mengkloning repositori di Langkah 2):

{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.yml"
  }
}

Langkah 6: Tulis operasi GraphQL

Buat .graphql file di direktori Anda src/operations untuk menentukan kueri dan mutasi Anda. IntelliSense menyediakan pelengkapan dan validasi otomatis.

Contoh pertanyaan

Buat src/operations/queries.graphql dan masukkan kueri berikut:

Berikut adalah contoh kueri untuk mengambil data pelanggan:

query GET_CUSTOMERS(
  $after: String
  $first: Int
  $filter: CustomerFilterInput
  $orderBy: CustomerOrderByInput
) {
  customers(after: $after, first: $first, filter: $filter, orderBy: $orderBy) {
    items {
      CustomerID
      FirstName
      LastName
    }
  }
}

Berikut adalah contoh mutasi:

mutation ADD_CUSTOMER($input: CreateCustomerInput!) {
  createCustomer(item: $input) {
    CustomerID
    FirstName
    LastName
    Title
    Phone
    PasswordHash
    PasswordSalt
    rowguid
    ModifiedDate
    NameStyle
  }
}

Langkah 7: Hasilkan jenis dan kait

Jalankan perintah pembuatan kode untuk membuat jenis TypeScript dan kait React:

npm run codegen

Setelah berhasil diselesaikan, Anda memiliki kode yang dihasilkan yang src/generated/graphql.tsx berisi:

  • Antarmuka TypeScript untuk semua jenis GraphQL
  • Kait React yang sangat ditik untuk setiap operasi
  • Definisi jenis input dan output

Langkah 8: Gunakan kode yang dihasilkan di komponen React Anda

Impor dan gunakan kait yang dihasilkan di komponen React Anda, misalnya:

import React from 'react';
import { useGetCustomersQuery, useAddCustomerMutation } from '../generated/graphql';

const CustomersComponent: React.FC = () => {
  const { data, loading, error } = useGetCustomersQuery({
    variables: { first: 10 }
  });

  const [addCustomer] = useAddCustomerMutation();

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {data?.customers?.items?.map(customer => (
        <div key={customer.CustomerID}>
          {customer.FirstName} {customer.LastName}
        </div>
      ))}
    </div>
  );
};

export default CustomersComponent;

Langkah 9: Mengonfigurasi autentikasi

Konfigurasikan autentikasi ID Microsoft Entra untuk aplikasi Anda:

  1. Buat aplikasi Microsoft Entra setelah bagian Buat aplikasi Microsoft Entra di Sambungkan aplikasi ke Fabric API untuk GraphQL.

  2. authConfig.ts Perbarui file di proyek Anda dengan parameter yang diperlukan:

export const AUTH_CONFIG = {
    clientId: "<Enter_the_Application_Id_Here>",
    tenantId: "<Enter_the_Tenant_Id_Here>",
    clientSecret: "<Enter_the_Client_Secret_Here>", //optional
}
export const GRAPHQL_ENDPOINT = '<Enter_the_GraphQL_Endpoint_Here>';

// The scope required for Fabric GraphQL API access
export const DEFAULT_SCOPE = "https://analysis.windows.net/powerbi/api/.default";

Untuk file konfigurasi lengkap, lihat sampel authConfig.ts di repositori.

Langkah 10: Jalankan aplikasi Anda

Mulai server pengembangan Anda:

npm run dev

Aplikasi Anda diluncurkan di browser di http://localhost:3000. Anda diminta untuk masuk dengan kredensial Microsoft Anda untuk mengakses data GraphQL API. Setelah autentikasi berhasil, Anda akan melihat data pelanggan dari tabel database SalesLT.Customer Fabric SQL Anda yang ditampilkan di aplikasi React.

Konten terkait

  • Last updated on