Zdieľať cez

Vývoj aplikácií GraphQL vo Visual Studio Code

Naučte sa, ako vytvoriť front-endovú aplikáciu pomocou Reactu, Apollo Client a TypeScriptu, ktorá sa integruje s rozhraním GraphQL API hosťovaným v Microsoft Fabric. Tento kurz sa zaoberá nastavením lokálnych vývojových nástrojov vrátane automatického dokončovania, generovania kódu a technológie IntelliSense pre optimálne prostredie pre vývojárov.

Kto by mal používať nástroje na vývoj VS Code

Lokálny rozvoj s VS Code je navrhnutý pre:

  • Vývojári Reactu vytvárajú webové aplikácie, ktoré spotrebovávajú dáta z Fabric lakehouse a skladu cez GraphQL
  • Vývojári TypeScriptu , ktorí potrebujú typovo bezpečné generovanie klientskeho kódu pre Fabric GraphQL API
  • Full-stack vývojári vytvárajú vlastné analytické aplikácie na platforme Fabric s podporou lokálneho IDE
  • Vývojové tímy , ktoré chcú moderné nástroje s IntelliSense a ladením pre aplikácie na prístup k dátam vo Fabric

Tento prístup používajte, keď vytvárate React aplikácie, ktoré potrebujú bohatú podporu IDE, generovanie kódu a možnosti lokálneho ladenia s TypeScriptom a Apollo Clientom.

Požiadavky

Skôr než začnete, uistite sa, že máte:

  • Prístup k pracovnému priestoru Microsoft Fabric: Buďte členom pracovného priestoru Fabric aspoň s rolou Prispievateľa (alebo vyššou: Administrátor, Člen) na vytváranie a úpravu položiek API GraphQL
  • Oprávnenia na zdroje dát: Práva na čítanie/zápis na zdrojoch dát, ktoré plánujete sprístupniť cez GraphQL API
  • Node.js nainštalované na vašom vývojovom počítači (vrátane npm)
  • Visual Studio Code nainštalovaný na vašom vývojovom počítači
  • Základné znalosti konceptov React, TypeScript a GraphQL

Krok 1: Vytvorenie rozhrania GraphQL API v službe Microsoft Fabric

Poznámka

Tento návod demonštruje vytvorenie GraphQL API z kontextu SQL databázy. Najprv vytvoríte SQL databázu, potom priamo z tejto databázy vytvoríte GraphQL API. Ak už máte existujúce GraphQL API a chcete sa naň pripojiť, postupujte podľa návodu Začnite tým, kde najskôr vytvoríte API a potom sa pripojíte k SQL databáze alebo inému zdroju dát.

Vytvorenie databázy SQL

Na vytvorenie SQL databázy, ktorá obsahuje ukážkové dáta pre vaše GraphQL API:

  1. V pracovnom priestore Fabric vyberte položku Nová položka.
  2. Vyberte položku Databáza SQL (Preview).
  3. Zadajte názov databázy.
  4. Výberom položky Vzorové údaje automaticky vytvoríte tabuľky a vyplníte ich vzorovými údajmi. Tým vzniká vzorová databáza AdventureWorksLT so schémou SalesLT, vrátane tabuliek ako SalesLT.Customer, SalesLT.Product a SalesLT.SalesOrderHeader.

Prepitné

Ak už máte SQL databázu s ukážkovými dátami z predchádzajúceho tutoriálu alebo vytvorenia GraphQL API, môžete tú istú databázu znovu použiť. Jedna databáza môže podporovať viacero GraphQL API, takže nie je potrebné vytvárať novú databázu, ak už máte jednu so schémou SalesLT.

Vytvorenie rozhrania GraphQL API

Teraz, keď máte SQL databázu so vzorovými dátami, vytvorte GraphQL API:

  1. V databáze SQL vyberte na páse s nástrojmi položku Nové rozhranie API pre GraphQL .

    Snímka obrazovky novej možnosti API pre GraphQL v SQL databázovej páske.

  2. Zadajte názov rozhrania API.

  3. Vyberte všetky tabuľky SalesLT z databázy.

  4. Výberom položky Načítať vygenerujte rozhranie API.

Vaše rozhranie GraphQL API je teraz pripravené a dostupné vo vašom pracovnom priestore Fabric.

Krok 2: Nastavenie vývojového prostredia

Ak chcete sledovať tento tutoriál, dokončite tieto kroky na nastavenie React starter aplikácie, inštaláciu potrebných závislostí a konfiguráciu Visual Studio kódu s podporou GraphQL.

  1. Klonujte štartovaciu aplikáciu – Získajte štartovaciu aplikáciu React z repozitára ukážok Microsoft Fabric:

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

  2. Inštalujte závislosti – Nainštalujte potrebné balíky pre vývoj, automatické dokončovanie a generovanie kódu v GraphQL:

    npm install

  3. Nainštalujte požadované rozšírenie Visual Studio Code – Nainštalujte rozšírenie GraphQL: Language Feature Support vo Visual Studio Code, ktoré umožní zvýrazňovanie syntaxe, validáciu a IntelliSense pre operácie GraphQL.

Krok 3: Konfigurácia schémy GraphQL

Schéma GraphQL definuje štruktúru vášho API – aké dáta sú dostupné, aké operácie môžete vykonávať a aké sú vzťahy medzi rôznymi typmi dát. Vaše vývojové nástroje využívajú túto schému na poskytovanie IntelliSense, dokončovania kódu a generovania typov, čo výrazne uľahčuje písanie správnych GraphQL dotazov a mutácií.

Schému GraphQL môžete získať dvoma spôsobmi:

Možnosť 1: Exportovať schému ako statický súbor

  1. V rozhraní GraphQL API Fabric vyberte na páse s nástrojmi položku Exportovať schému .
  2. Stiahnutý názov súboru obsahuje ID vášho GraphQL API (napríklad, GraphQL_your-api-id_schema.graphql). Uložte ho do koreňového adresára projektu a premenujte ho na schema.graphql – toto je názov súboru, ktorý použijete v nasledujúcich konfiguračných krokoch.

Možnosť 2: Použitie vzdialeného koncového bodu

  1. Získajte prístup k rozhraniu GraphQL API, ktoré ste vytvorili na portáli Fabric.
  2. Získanie autorizačného tokenu pomocou prostredia PowerShell s Get-PowerBIAccessToken

Poznámka

Zatiaľ čo možnosť vzdialeného koncového bodu vždy poskytuje schému s najväčším up-todátumom, získaný token je dočasný a vyprší hodinovo. Mali by sa používať iba na testovacie a vývojové účely, vždy, keď je to možné, použite statický súbor, aby ste sa vyhli problémom s vypršaním platnosti tokenu.

Krok 4: Konfigurácia technológie IntelliSense a automatického dokončovania

Teraz nastavíte IntelliSense pomocou schémy z kroku 3. Schéma súbor (či už statický alebo z vzdialeného koncového bodu) umožňuje VS Code poskytovať návrhy kódu v reálnom čase, detekciu chýb a validáciu polí pri písaní dotazov v GraphQL.

Vytvorte konfiguračný súbor v koreňovom adresári projektu:

Použitie súboru statickej schémy

Použite nasledujúcu konfiguráciu, ak ste schému exportovali ako statický súbor:

Vytvoriť .graphqlrc.yml:

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

Používanie vzdialeného koncového bodu

Použite nasledujúcu konfiguráciu, ak uprednostňujete načítať schému priamo z vášho GraphQL API endpointu:

Vytvoriť graphql.config.yml:

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

Možnosti konfigurácie

  • schéma: Určuje umiestnenie schémy GraphQL
  • documents: Definuje, ktoré súbory by mali mať podporu IntelliSense

Po vytvorení konfiguračného súboru reštartujte Visual Studio Code, aby ste sa uistili, že zmeny sa prejavia.

Krok 5: Nastavenie generovania kódu

Generovanie kódu GraphQL automaticky vytvára rozhrania TypeScriptu so silným typom a háčiky Reactu z vašej schémy a operácií, čím sa znižuje počet chýb a zvyšuje efektivita vývoja. Jeho primárnym účelom je zvýšiť bezpečnosť písma a zefektívniť vývoj v projektoch GraphQL, najmä pri práci so silne typovanými jazykmi, ako je TypeScript.

Vytvorenie konfigurácie codegen

Možnosť statického súboru

Ak ste schému exportovali ako statický súbor, vytvorte codegen.yml ju v koreňoch projektu:

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

Možnosť vzdialeného koncového bodu

Ak používate prístup vzdialeného koncového bodu, vytvorte codegen.yml priamo pri koreňoch projektu:

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

Rozpis konfigurácie

  • schéma: Cesta k súboru schémy alebo vzdialenému koncovému bodu
  • dokumenty: Globový vzor na vyhľadanie operačných súborov GraphQL
  • generuje: Určuje výstupný súbor pre vygenerovaný kód
  • pluginy: Určuje, aký kód sa má vygenerovať (typy TypeScript a háčiky React Apollo)

Pridanie kódexového skriptu

Pridajte skript na generovanie kódu do súboru package.json vo vašom projektovom adresári (tento súbor bol zahrnutý, keď ste v kroku 2 klonovali repozitár):

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

Krok 6: Zápis operácií GraphQL

Vytvárajte .graphql súbory v adresári src/operations na definovanie dotazov a mutácií. IntelliSense poskytuje automatické dokončovanie a overovanie.

Príklady dotazov

Vytvorte src/operations/queries.graphql a zadajte nasledujúce dotazy:

Tu je ukážkový dotaz na získanie údajov o zákazníkoch:

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

Tu je príklad mutácie:

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

Krok 7: Generovanie typov a háčikov

Spustite príkaz generovania kódu a vytvorte typy TypeScript a háčiky React:

npm run codegen

Po úspešnom dokončení máte vygenerovaný kód, ktorý src/generated/graphql.tsx obsahuje:

  • Rozhrania TypeScript pre všetky typy GraphQL
  • Silne typované háčiky React pre každú operáciu
  • Definície typov vstupov a výstupov

Krok 8: Použite vygenerovaný kód v komponentoch Reactu

Importujte a používajte vygenerované háčiky vo svojich komponentoch React, napríklad:

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;

Krok 9: Konfigurácia overenia

Nakonfigurujte overenie Microsoft Entra ID pre svoju aplikáciu:

  1. Vytvorte aplikáciu Microsoft Entra podľa časti Vytvorenie aplikácie Microsoft Entra v téme Pripojenie aplikácií k rozhraniu Fabric API pre GraphQL.

  2. Aktualizujte authConfig.ts súbor vo svojom projekte požadovanými parametrami:

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

Úplný konfiguračný súbor nájdete v ukážke authConfig.ts v úložisku.

Krok 10: Spustite aplikáciu

Spustite vývojový server:

npm run dev

Vaša aplikácia sa spustí v prehliadači na http://localhost:3000. Na prístup k dátam GraphQL API ste vyzvaní, aby ste sa prihlásili pomocou Microsoft prihlasovacích údajov. Po úspešnej autentifikácii uvidíte zákaznícke dáta z tabuľky SalesLT.Customer vašej Fabric SQL databázy zobrazené v aplikácii React.

Súvisiaci obsah

  • Last updated on