在 Visual Studio Code 中開發 GraphQL 應用程式

瞭解如何使用 React、Apollo Client 和 TypeScript 建置前端應用程式，以與裝載於 Microsoft Fabric 的 GraphQL API 整合。本教學課程涵蓋設定本機開發工具，包括自動完成、程式碼產生和 IntelliSense，以獲得最佳開發人員體驗。

誰應該使用 VS Code 開發工具

使用 VS Code 進行本機開發，其用途包括：

React 開發者 使用 GraphQL 來存取 Fabric 湖庫和倉庫資料以建立網頁應用程式
需要為 Fabric GraphQL API 生成型別安全用戶端程式碼的 TypeScript 開發者
全端開發人員在 Fabric 平台上建構自訂的分析應用程式，並提供本地 IDE 支援
想要使用現代化 IntelliSense 和除錯工具來存取 Fabric 資料應用程式的開發團隊

當你在建置需要豐富 IDE 支援、程式碼產生及本地除錯功能的 React 應用程式時，請使用這種方法，搭配 TypeScript 和 Apollo 客戶端。

先決條件

在開始之前，請確保您擁有：

Microsoft Fabric 工作空間存取權：成為 Fabric 工作空間的成員，至少具備貢獻者角色（或更高：管理員、會員），以建立及修改 GraphQL API 項目
資料來源權限：對你計畫透過 GraphQL API 暴露的資料來源進行讀寫權限
Node.js 安裝在你的開發機器上（包含 NPM）
安裝在你的開發機器上的 Visual Studio Code
React、TypeScript 和 GraphQL 概念的基本知識

步驟 1：在 Microsoft Fabric 中建立 GraphQL API

備註

本指南示範如何從 SQL 資料庫上下文建立 GraphQL API。你先建立 SQL 資料庫，然後直接從該資料庫內建立 GraphQL API。如果你已經有現有的 GraphQL API，想要連接它，請依照入門指南操作，先建立 API，再連接到 SQL 資料庫或其他資料來源。

建立 SQL 資料庫

要建立包含 GraphQL API 範例資料的 SQL 資料庫：

在您的 Fabric 工作區中，選取 [新增專案]。
選取 [SQL 資料庫（預覽版）]。
提供資料庫的名稱。
選取 [範例資料] 以自動建立資料表，並使用範例資料填入資料表。這會建立帶有 SalesLT 架構的 AdventureWorksLT 範例資料庫，包括像 SalesLT.Customer、SalesLT.Product 和 SalesLT.SalesOrderHeader 這類資料表。

小提示

如果你已經有一個包含之前教學或 GraphQL API 建立範例資料的 SQL 資料庫，你可以重複使用同一個資料庫。一個資料庫可以支援多個 GraphQL API，所以如果你已經有一個帶有 SalesLT 架構的資料庫，就不需要再建立新的資料庫。

建立 GraphQL API

現在你已經有一個包含範例資料的 SQL 資料庫，請建立 GraphQL API：

在您的 SQL 資料庫中，從功能區選取 [新的 GraphQL API ]。
提供 API 的名稱。
從資料庫中選取所有 SalesLT 資料表。
選取載入以產生 API。

您的 GraphQL API 現在已準備就緒，並可在 Fabric 工作區中使用。

步驟 2：設定您的開發環境

要跟著這個教學進行，請完成以下步驟，設定 React 入門應用程式、安裝必要的相依性，以及配置支援 GraphQL 的 Visual Studio Code。

複製入門範例應用程式 - 從 Microsoft Fabric 範例庫中獲取 React 入門範例應用程式：

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

安裝相依關係 - 安裝 GraphQL 開發、自動補全及程式碼產生所需的套件：
```
npm install
```
安裝必要的 Visual Studio Code 擴充功能 - 在 Visual Studio Code 中安裝 GraphQL： Language Feature Support 擴充功能，以啟用語法高亮、驗證及 IntelliSense 進行 GraphQL 操作。

步驟 3：設定您的 GraphQL 結構描述

GraphQL 架構定義了 API 的結構——有哪些資料可用、你可以執行哪些操作，以及不同資料類型之間的關係。你的開發工具會利用這個架構來提供 IntelliSense、程式碼補全和型別產生，讓你更容易撰寫正確的 GraphQL 查詢和變異。

您可以透過兩種方式取得GraphQL結構描述：

選項 1：將結構描述匯出為靜態檔案

在您的 Fabric GraphQL API 中，從功能區選取 匯出結構描述。
下載的檔名會包含你的 GraphQL API 的 ID（例如， GraphQL_your-api-id_schema.graphql）。把它存到你的專案根目錄，然後重新命名為 schema.graphql ——這就是你在接下來設定步驟中使用的檔名。

選項 2：使用遠端端點

存取您在 Fabric 入口網站中建立的 GraphQL API。
使用 PowerShell 搭配 Get-PowerBIAccessToken 取得授權權杖

備註

雖然遠端端點選項總是提供最新的結構描述，但取得的權杖是臨時的，並且每小時會過期。它們應該僅用於測試和開發目的，盡可能使用靜態檔案以避免權杖過期問題。

步驟 4：設定 IntelliSense 和自動完成

現在你會用步驟3的架構來設定IntelliSense。這個結構檔案（無論是靜態還是遠端端點）讓 VS Code 在你撰寫 GraphQL 查詢時，能即時提供程式碼建議、錯誤偵測和欄位驗證。

在專案根目錄建立組態檔：

使用靜態結構描述檔案

如果你是將結構匯出為靜態檔案，請使用以下設定：

創建 .graphqlrc.yml：

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

使用遠端端點

如果你偏好直接從 GraphQL API 端點擷取結構，請使用以下設定：

創建 graphql.config.yml：

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

設定選項

schema：指定GraphQL結構描述的位置
documents：定義哪些檔案應該具有 IntelliSense 支援

建立設定檔後，重新啟動 Visual Studio Code 以確保變更生效。

步驟 5：設定程式碼產生

GraphQL 程式碼產生會自動從您的模式和操作建立強類型 TypeScript 介面和 React 鉤子，從而減少錯誤並提高開發效率。其主要目的是增強類型安全性並簡化 GraphQL 專案的開發，特別是在使用 TypeScript 等強類型語言時。

建立 codegen 設定

靜態檔案選項

如果你匯出結構為靜態檔案，請在專案根建立 codegen.yml ：

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

遠端端點選項

如果你使用遠端端點方法，請在專案根建立 codegen.yml ：

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

配置明細

結構描述：結構描述檔案或遠端端點的路徑
documents：用於尋找 GraphQL 作業檔案的 Glob 模式
generates：指定產生程式碼的輸出檔案
plugins：確定要生成的代碼（TypeScript 類型和 React Apollo 鉤子）

新增程式碼生成腳本

將程式碼產生腳本加入你的專案目錄檔案 package.json （這個檔案在你複製倉庫時步驟 2 時就包含了）：

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

步驟 6：撰寫 GraphQL 作業

在目錄.graphql中建立src/operations檔案以定義查詢和變動。 IntelliSense 提供自動完成和驗證。

範例查詢

請建立 src/operations/queries.graphql 並輸入以下查詢：

以下是用來取得客戶資料的範例查詢：

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

這裡有一個突變的例子：

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

步驟 7：產生類型和掛鉤

執行程式碼產生指令來建立TypeScript類型和React鉤子：

npm run codegen

成功完成後，生成的程式碼在src/generated/graphql.tsx中包含：

適用於所有 GraphQL 類型的 TypeScript 介面
每個操作的強類型 React 鉤子
輸入和輸出類型定義

第 8 步：在 React 元件中使用產生的程式碼

將產生的鉤子匯入並使用於您的 React 元件中，例如：

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;

步驟 9：設定驗證

為您的應用程式設定 Microsoft Entra ID 驗證：

在將應用程式連線到適用於 GraphQL 的 Fabric API 中的建立 Microsoft Entra 應用程式一節之後，建立 Microsoft Entra 應用程式。
在專案中的檔案中，使用必要的引數進行更新：

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";

如需完整的組態檔，請參閱存放庫中的 authConfig.ts範例。

步驟 10：執行您的應用程式

啟動您的開發伺服器：

npm run dev

您的應用程式會在瀏覽器中於http://localhost:3000開啟。系統會提示你用 Microsoft 憑證登入以存取 GraphQL API 資料。成功認證後，你會在 React 應用程式中看到 Fabric SQL 資料庫 SalesLT.Customer 資料表中的客戶資料。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-21