พัฒนาแอปพลิเคชัน GraphQL ใน Visual Studio Code

เรียนรู้วิธีสร้างแอปพลิเคชันส่วนหน้าด้วย React, Apollo Client และ TypeScript ที่รวมเข้ากับ GraphQL API ที่โฮสต์ใน Microsoft Fabric บทช่วยสอนนี้ครอบคลุมการตั้งค่าเครื่องมือการพัฒนาภายในเครื่อง รวมถึงการเติมข้อความอัตโนมัติ การสร้างโค้ด และ IntelliSense เพื่อประสบการณ์ที่ดีที่สุดของนักพัฒนา

ใครควรใช้เครื่องมือพัฒนา VS Code

การพัฒนาในพื้นที่ด้วย VS Code ออกแบบมาสําหรับ:

• นักพัฒนาปฏิกิริยา ที่สร้างเว็บแอปพลิเคชันที่ใช้ข้อมูลเลคเฮาส์และคลังสินค้าของ Fabric ผ่าน GraphQL
• นักพัฒนา TypeScript ที่ต้องการการสร้างโค้ดไคลเอ็นต์ที่ปลอดภัยสําหรับ Fabric GraphQL API
• นักพัฒนาฟูลสแตก ที่สร้างแอปพลิเคชันการวิเคราะห์แบบกําหนดเองบนแพลตฟอร์ม Fabric พร้อมรองรับ IDE ในเครื่อง
• ทีมพัฒนา ที่ต้องการเครื่องมือที่ทันสมัยด้วย IntelliSense และการดีบักสําหรับแอปพลิเคชันการเข้าถึงข้อมูล Fabric

ใช้วิธีนี้เมื่อคุณสร้างแอปพลิเคชัน React ที่ต้องการการสนับสนุน IDE ที่หลากหลาย การสร้างโค้ด และความสามารถในการดีบักในเครื่องด้วย TypeScript และ Apollo Client

ข้อกําหนดเบื้องต้น

ก่อนที่คุณจะเริ่ม ให้แน่ใจว่าคุณมีสิ่งต่อไปนี้

• การเข้าถึงพื้นที่ทํางาน Microsoft Fabric: เป็นสมาชิกของพื้นที่ทํางาน Fabric ที่มีบทบาท ผู้สนับสนุน เป็นอย่างน้อย (หรือสูงกว่า: ผู้ดูแลระบบ สมาชิก) เพื่อสร้างและปรับเปลี่ยนรายการ GraphQL API
• สิทธิ์ของแหล่งข้อมูล: สิทธิ์ในการอ่าน/เขียนแหล่งข้อมูลที่คุณวางแผนจะเปิดเผยผ่าน GraphQL API
• Node.js ติดตั้งบนเครื่องพัฒนาของคุณ (รวมถึง NPM)
• Visual Studio Code ที่ติดตั้งบนเครื่องพัฒนาของคุณ
• ความรู้พื้นฐานเกี่ยวกับแนวคิด React, TypeScript และ GraphQL

ขั้นตอนที่ 1: สร้าง GraphQL API ใน Microsoft Fabric

สร้างฐานข้อมูล SQL

เมื่อต้องการสร้างฐานข้อมูล SQL ที่มีข้อมูลตัวอย่างสําหรับ GraphQL API ของคุณ:

1. ในพื้นที่ทํางาน Fabric ของคุณ ให้เลือก รายการใหม่
2. เลือก ฐานข้อมูล SQL (พรีวิว)
3. ระบุชื่อสําหรับฐานข้อมูลของคุณ
4. เลือก ข้อมูลตัวอย่าง เพื่อสร้างตารางโดยอัตโนมัติและเติมข้อมูลด้วยข้อมูลตัวอย่าง ซึ่งจะสร้างฐานข้อมูลตัวอย่าง AdventureWorksLT ด้วยสคีมา SalesLT รวมถึงตารางเช่น SalesLT.Customer, SalesLT.Product และ SalesLT.SalesOrderHeader

สร้าง GraphQL API

เมื่อคุณมีฐานข้อมูล SQL ที่มีข้อมูลตัวอย่างแล้ว ให้สร้าง GraphQL API:

1. ในฐานข้อมูล SQL ของคุณ ให้เลือก API ใหม่สําหรับ GraphQL จาก Ribbon

   

2. ระบุชื่อ API ของคุณ

3. เลือกตาราง SalesLT ทั้งหมดจากฐานข้อมูลของคุณ

4. เลือก โหลด เพื่อสร้าง API

GraphQL API ของคุณพร้อมแล้วและพร้อมใช้งานในพื้นที่ทํางาน Fabric ของคุณ

ขั้นตอนที่ 2: ตั้งค่าสภาพแวดล้อมการพัฒนาของคุณ

หากต้องการทําตามบทช่วยสอนนี้ ให้ทําตามขั้นตอนเหล่านี้เพื่อตั้งค่าแอปพลิเคชัน React starter ติดตั้งการพึ่งพาที่จําเป็น และกําหนดค่า Visual Studio Code ด้วยการสนับสนุน GraphQL

1. โคลนแอปพลิเคชันเริ่มต้น - รับแอปพลิเคชันเริ่มต้น React จากที่เก็บตัวอย่าง Microsoft Fabric:

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

2. ติดตั้งการขึ้นต่อกัน - ติดตั้งแพ็คเกจที่จําเป็นสําหรับการพัฒนา GraphQL การเติมข้อความอัตโนมัติ และการสร้างโค้ด:

   npm install
   

3. ติดตั้งส่วนขยาย Visual Studio Code ที่จําเป็น - ติดตั้งส่วนขยาย GraphQL: การสนับสนุนคุณลักษณะภาษา ใน Visual Studio Code เพื่อเปิดใช้งานการเน้นไวยากรณ์ การตรวจสอบความถูกต้อง และ IntelliSense สําหรับการดําเนินการ GraphQL

ขั้นตอนที่ 3: กําหนดค่าสคีมา GraphQL ของคุณ

สคีมา GraphQL กําหนดโครงสร้างของ API ของคุณ - ข้อมูลใดที่พร้อมใช้งาน การดําเนินการใดที่คุณสามารถทําได้ และความสัมพันธ์ระหว่างประเภทข้อมูลต่างๆ คืออะไร เครื่องมือการพัฒนาของคุณใช้สคีมานี้เพื่อจัดเตรียม IntelliSense การเติมโค้ด และการสร้างประเภท ทําให้ง่ายต่อการเขียนการสืบค้นและการกลายพันธุ์ GraphQL ที่ถูกต้อง

คุณสามารถรับสคีมา GraphQL ได้สองวิธี:

ตัวเลือกที่ 1: ส่งออกสคีมาเป็นไฟล์แบบคงที่

1. ใน Fabric GraphQL API ของคุณ ให้เลือก ส่งออกสคีมา จาก Ribbon
2. ชื่อไฟล์ที่ดาวน์โหลดจะมีรหัสของ GraphQL API ของคุณ (เช่น GraphQL_your-api-id_schema.graphql) บันทึกลงในไดเรกทอรีรากของโครงการของคุณและเปลี่ยนชื่อเป็น schema.graphql - นี่คือชื่อไฟล์ที่คุณใช้ในขั้นตอนการกําหนดค่าที่ตามมา

ตัวเลือกที่ 2: ใช้ปลายทางระยะไกล

1. เข้าถึง GraphQL API ที่คุณสร้างขึ้นใน Fabric Portal
2. รับโทเค็นการอนุญาตโดยใช้ PowerShell กับ Get-PowerBIAccessToken

ขั้นตอนที่ 4: กําหนดค่า IntelliSense และการเติมข้อความอัตโนมัติ

ตอนนี้คุณจะตั้งค่า IntelliSense โดยใช้ Schema จากขั้นตอนที่ 3 ไฟล์ Schema (ไม่ว่าจะเป็นแบบคงที่หรือจากปลายทางระยะไกล) ช่วยให้ VS Code สามารถให้คําแนะนําโค้ดแบบเรียลไทม์ การตรวจจับข้อผิดพลาด และการตรวจสอบฟิลด์ในขณะที่คุณเขียนการสืบค้น GraphQL

สร้างไฟล์การกําหนดค่าที่รากโปรเจ็กต์ของคุณ:

การใช้ไฟล์ Schema แบบคงที่

ใช้การกําหนดค่าต่อไปนี้หากคุณ ส่งออก Schema เป็นไฟล์แบบคงที่:

สร้าง .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: ระบุตําแหน่งของ schema GraphQL ของคุณ
• เอกสาร: กําหนดไฟล์ที่ควรได้รับการสนับสนุน 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

รายละเอียดการกําหนดค่า

• schema: เส้นทางไปยังไฟล์ Schema หรือปลายทางระยะไกล
• เอกสาร: รูปแบบ Glob สําหรับค้นหาไฟล์การดําเนินการ GraphQL
• generates: ระบุไฟล์เอาต์พุตสําหรับโค้ดที่สร้างขึ้น
• plugins: กําหนดโค้ดที่จะสร้าง (ประเภท TypeScript และ React Apollo hooks)

เพิ่มสคริปต์ codegen

เพิ่มสคริปต์การสร้างโค้ดลงใน 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 และ Reacthook

npm run codegen

เมื่อสําเร็จ คุณจะมีรหัสที่สร้างขึ้นซึ่ง src/generated/graphql.tsx ประกอบด้วย:

• อินเทอร์เฟซ TypeScript สําหรับ GraphQL ทุกประเภท
• hook React ที่พิมพ์อย่างแรงสําหรับแต่ละการดําเนินการ
• คําจํากัดความชนิดอินพุตและเอาต์พุต

ขั้นตอนที่ 8: ใช้โค้ดที่สร้างขึ้นในส่วนประกอบ React ของคุณ

นําเข้าและใช้ hook ที่สร้างขึ้นในส่วนประกอบ 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 สําหรับแอปพลิเคชันของคุณ:

1. สร้างแอป Microsoft Entra ตามส่วน สร้างแอป Microsoft Entra ในเชื่อมต่อแอปพลิเคชันกับ Fabric API สําหรับ GraphQL

2. อัปเดต authConfig.ts ไฟล์ในโปรเจ็กต์ของคุณด้วยพารามิเตอร์ที่จําเป็น:

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 หลังจากการรับรองความถูกต้องสําเร็จ คุณจะเห็นข้อมูลลูกค้าจากตารางฐานข้อมูล SalesLT.Customer Fabric SQL ของคุณที่แสดงในแอปพลิเคชัน React

เนื้อหาที่เกี่ยวข้อง

• ภาพรวมของ Microsoft Fabric GraphQL API
• เชื่อมต่อแอปพลิเคชันกับ Fabric API สําหรับ GraphQL
• เอกสาร Apollo Client
• เอกสารประกอบ GraphQL Code Generator