Sdílet prostřednictvím

Vývoj aplikací GraphQL v editoru Visual Studio Code

Zjistěte, jak vytvořit front-endovou aplikaci pomocí react, klienta Apollo a TypeScriptu, který se integruje s rozhraním GraphQL API hostovaným v Microsoft Fabric. Tento kurz se zabývá nastavením místních vývojových nástrojů, včetně automatického dokončování, generování kódu a Technologie IntelliSense pro optimální prostředí pro vývojáře.

Kdo by měl používat vývojové nástroje VS Code

Místní vývoj pomocí nástroje VS Code je navržený pro:

  • React vývojáři vytvářející webové aplikace, které spotřebovávají data z Fabric Lakehouse a z datového skladu prostřednictvím GraphQL
  • Vývojáři TypeScriptu, kteří potřebují generování typově bezpečného klientského kódu pro rozhraní API GraphQL Fabric
  • Plnohodnotní vývojáři vytvářející vlastní analytické aplikace na platformě Fabric s místní podporou integrovaného vývojového prostředí (IDE)
  • Vývojové týmy, které chtějí moderní nástroje s technologií IntelliSense a laděním pro aplikace s přístupem k datům Fabric

Tento přístup použijte při vytváření aplikací React, které potřebují bohatou podporu integrovaného vývojového prostředí (IDE), generování kódu a možnosti místního ladění pomocí TypeScriptu a klienta Apollo.

Požadavky

Než začnete, ujistěte se, že máte:

  • Přístup k pracovnímu prostoru Microsoft Fabric: Být členem pracovního prostoru Fabric s alespoň rolí Přispěvatel (nebo vyšší: Správce, Člen) pro vytváření a úpravu položek rozhraní GraphQL API
  • Oprávnění ke zdroji dat: Oprávnění ke čtení a zápisu u zdrojů dat, které plánujete zveřejnit prostřednictvím rozhraní GraphQL API
  • Node.js nainstalované na vývojovém počítači (včetně npm)
  • Visual Studio Code nainstalovaný na vývojovém počítači
  • Základní znalost konceptů React, TypeScript a GraphQL

Krok 1: Vytvoření rozhraní GraphQL API v Microsoft Fabric

Poznámka:

Tato příručka ukazuje vytvoření rozhraní GraphQL API z kontextu databáze SQL. Nejprve vytvoříte databázi SQL a pak přímo z této databáze vytvoříte rozhraní GraphQL API. Pokud už máte existující rozhraní GraphQL API a chcete se k němu připojit, postupujte podle příručky Začínáme , ve které nejprve vytvoříte rozhraní API, a pak se připojte k databázi SQL nebo jinému zdroji dat.

Vytvoření databáze SQL

Vytvoření databáze SQL, která obsahuje ukázková data pro rozhraní GraphQL API:

  1. V pracovním prostoru Prostředky infrastruktury vyberte Možnost Nová položka.
  2. Vyberte databázi SQL (Preview).
  3. Zadejte název databáze.
  4. Výběrem ukázkových dat můžete automaticky vytvářet tabulky a naplnit je ukázkovými daty. Tím se vytvoří ukázková databáze AdventureWorksLT se schématem SalesLT, včetně tabulek, jako jsou SalesLT.Customer, SalesLT.Product a SalesLT.SalesOrderHeader.

Návod

Pokud už máte databázi SQL s ukázkovými daty z předchozího kurzu nebo vytvoření rozhraní GraphQL API, můžete stejnou databázi znovu použít. Jedna databáze může podporovat více rozhraní GraphQL API, takže není nutné vytvořit novou databázi, pokud ji už máte se schématem SalesLT.

Vytvoření rozhraní GraphQL API

Teď, když máte databázi SQL s ukázkovými daty, vytvořte rozhraní GraphQL API:

  1. V databázi SQL vyberte na pásu karet nové rozhraní API pro GraphQL .

    Snímek obrazovky možnosti Nového rozhraní API pro GraphQL na pásu karet databáze SQL

  2. Zadejte název rozhraní API.

  3. Vyberte všechny tabulky SalesLT z databáze.

  4. Výběrem možnosti Načíst vygenerujete rozhraní API.

Rozhraní GraphQL API je teď připravené a dostupné v pracovním prostoru Fabric.

Krok 2: Nastavení vývojového prostředí

Pokud chcete postupovat podle tohoto kurzu, proveďte tyto kroky pro nastavení úvodní aplikace React, instalaci potřebných závislostí a konfiguraci nástroje Visual Studio Code s podporou GraphQL.

  1. Naklonujte úvodní aplikaci – Získejte úvodní aplikaci React z úložiště ukázek Microsoft Fabric:

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

  2. Instalace závislostí – Nainstalujte požadované balíčky pro vývoj, automatické dokončování a generování kódu GraphQL:

    npm install

  3. Nainstalujte požadované rozšíření editoru Visual Studio Code – NainstalujtegraphQL: Rozšíření podpory jazykových funkcí v editoru Visual Studio Code, které umožňuje zvýrazňování syntaxe, ověřování a IntelliSense pro operace GraphQL.

Krok 3: Konfigurace schématu GraphQL

Schéma GraphQL definuje strukturu vašeho rozhraní API – jaká data jsou k dispozici, jaké operace můžete provádět a jaké jsou relace mezi různými datovými typy. Vaše vývojové nástroje používají toto schéma k poskytování IntelliSense, generování typů a dokončování kódu, což značně usnadňuje psaní správných dotazů a mutací GraphQL.

Schéma GraphQL můžete získat dvěma způsoby:

Možnost 1: Export schématu jako statického souboru

  1. V rozhraní API Fabric GraphQL vyberte na pásu karet možnost Exportovat schéma .
  2. Stažený název souboru obsahuje ID rozhraní GraphQL API (například GraphQL_your-api-id_schema.graphql). Uložte ho do kořenového adresáře projektu a přejmenujte ho na schema.graphql – jedná se o název souboru, který používáte v následujících krocích konfigurace.

Možnost 2: Použití vzdáleného koncového bodu

  1. Přejděte k rozhraní GraphQL API, které jste vytvořili na portálu Fabric.
  2. Získání autorizačního tokenu pomocí PowerShellu s rutinou Get-PowerBIAccessToken

Poznámka:

Ačkoli možnost vzdáleného koncového bodu vždy poskytuje nejaktuálnější schéma, načtený token je dočasný a vyprší každou hodinu. Měly by se používat pouze pro účely testování a vývoje, kdykoli je to možné, použijte statický soubor, abyste se vyhnuli problémům s vypršením platnosti tokenu.

Krok 4: Konfigurace technologie IntelliSense a automatického dokončování

Teď nastavíte IntelliSense pomocí schématu z kroku 3. Soubor schématu (ať už statický nebo z dálkového zdroje) umožňuje VS Code poskytovat návrhy kódu, detekci chyb a validaci polí při psaní dotazů GraphQL v reálném čase.

Vytvořte konfigurační soubor v kořenovém adresáři projektu:

Použití souboru statického schématu

Pokud jste schéma exportovali jako statický soubor, použijte následující konfiguraci:

Vytvořit .graphqlrc.yml:

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

Použití vzdáleného koncového bodu

Pokud chcete schéma načíst přímo z koncového bodu rozhraní GraphQL API, použijte následující konfiguraci:

Vytvořit graphql.config.yml:

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

Možnosti konfigurace

  • schéma: Určuje umístění schématu GraphQL.
  • dokumenty: Definuje, které soubory by měly podporovat IntelliSense.

Po vytvoření konfiguračního souboru restartujte Visual Studio Code, aby se změny projevily.

Krok 5: Nastavení generování kódu

Generování kódu GraphQL automaticky vytváří rozhraní TypeScript silného typu a hooky React ze schématu a operací, což snižuje chyby a zlepšuje efektivitu vývoje. Jejím primárním účelem je zvýšit bezpečnost typů a zjednodušit vývoj v projektech GraphQL, zejména při práci se silnými jazyky, jako je TypeScript.

Vytvoření konfigurace codegenu

Možnost statického souboru

Pokud jste schéma exportovali jako statický soubor, vytvořte codegen.yml ho v kořenovém adresáři projektu:

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

Možnost vzdáleného koncového bodu

Pokud používáte přístup ke vzdálenému koncovému bodu, vytvořte codegen.yml soubor v kořenovém adresáři 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 konfigurace

  • schéma: Cesta k souboru schématu nebo vzdálenému koncovému bodu
  • documents: Glob vzorec pro vyhledání souborů operací GraphQL
  • generates: Určuje výstupní soubor pro vygenerovaný kód.
  • moduly plug-in: Určuje, jaký kód se má generovat (typy TypeScriptu a háky React Apollo)

Přidání skriptu codegen

Do souboru v adresáři projektu přidejte skript package.json pro generování kódu (tento soubor byl zahrnutý při klonování úložiště v kroku 2):

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

Krok 6: Zápis operací GraphQL

Vytvořte .graphql v src/operations adresáři soubory pro definování dotazů a mutací. IntelliSense poskytuje automatické dokončování a ověřování.

Příkladové dotazy

Vytvořte src/operations/queries.graphql a zadejte následující dotazy:

Tady je ukázkový dotaz pro načtení zákaznických dat:

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

Tady je příklad mutaci:

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

Krok 7: Generování typů a háků

Spuštěním příkazu generování kódu vytvořte typy TypeScriptu a hooky React:

npm run codegen

Po úspěšném dokončení máte vygenerovaný kód, který src/generated/graphql.tsx obsahuje:

  • Rozhraní TypeScript pro všechny typy GraphQL
  • Háky React se silnými typy pro každou operaci
  • Definice vstupního a výstupního typu

Krok 8: Použití vygenerovaného kódu v komponentách Reactu

Naimportujte a používejte vygenerované háky v komponentách Reactu, napří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: Konfigurace ověřování

Nakonfigurujte ověřování Microsoft Entra ID pro vaši aplikaci:

  1. Vytvořte aplikaci Microsoft Entra podle části Vytvoření aplikace Microsoft Entra v části Připojení aplikací k rozhraní API Fabric pro GraphQL.

  2. authConfig.ts Aktualizujte soubor v projektu požadovanými parametry:

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í soubor najdete v ukázce authConfig.ts v úložišti.

Krok 10: Spuštění aplikace

Spusťte vývojový server:

npm run dev

Aplikace se spustí v prohlížeči na adrese http://localhost:3000. Zobrazí se výzva k přihlášení pomocí přihlašovacích údajů Microsoftu pro přístup k datům rozhraní GraphQL API. Po úspěšném ověření se v aplikaci React zobrazí zákaznická data z tabulky databáze FABRIC SQL SalesLT.Customer .

Související obsah

  • Last updated on