Teilen über

Entwickeln von GraphQL-Anwendungen in Visual Studio Code

Erfahren Sie, wie Sie eine Front-End-Anwendung mit React, Apollo Client und TypeScript erstellen, die in eine in Microsoft Fabric gehostete GraphQL-API integriert wird. In diesem Lernprogramm werden lokale Entwicklungstools wie AutoVervollständigen, Codegenerierung und IntelliSense für eine optimale Entwicklerumgebung eingerichtet.

Wer sollte VS Code-Entwicklungstools verwenden?

Die lokale Entwicklung mit VS Code wurde für Folgendes entwickelt:

  • React-Entwickler erstellen Webanwendungen, die Fabric Lakehouse- und Warehouse-Daten über GraphQL nutzen
  • TypeScript-Entwickler , die typsichere Clientcodegenerierung für Fabric GraphQL-APIs benötigen
  • Full-Stack-Entwickler , die benutzerdefinierte Analyseanwendungen auf der Fabric-Plattform mit lokaler IDE-Unterstützung erstellen
  • Entwicklungsteams , die moderne Tools mit IntelliSense und Debuggen für Fabric-Datenzugriffsanwendungen benötigen

Verwenden Sie diesen Ansatz, wenn Sie React-Anwendungen erstellen, die umfangreiche IDE-Unterstützung, Codegenerierung und lokale Debugfunktionen mit TypeScript und Apollo Client benötigen.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

  • Microsoft Fabric-Arbeitsbereichszugriff: Mitglied des Fabric-Arbeitsbereichs mit mindestens der Rolle "Mitwirkender " (oder höher: Administrator, Mitglied) zum Erstellen und Ändern von GraphQL-API-Elementen
  • Datenquellenberechtigungen: Lese-/Schreibberechtigungen für die Datenquellen, die Sie über die GraphQL-API verfügbar machen möchten
  • Node.js auf Ihrem Entwicklungscomputer installiert (einschließlich npm)
  • Visual Studio Code auf Dem Entwicklungscomputer installiert
  • Grundlegende Kenntnisse von React-, TypeScript- und GraphQL-Konzepten

Schritt 1: Erstellen einer GraphQL-API in Microsoft Fabric

Hinweis

In diesem Handbuch wird das Erstellen einer GraphQL-API aus einem SQL-Datenbankkontext veranschaulicht. Sie erstellen zuerst die SQL-Datenbank und erstellen dann die GraphQL-API direkt aus dieser Datenbank. Wenn Sie bereits über eine vorhandene GraphQL-API verfügen und eine Verbindung damit herstellen möchten, folgen Sie dem Leitfaden "Erste Schritte ", in dem Sie die API zuerst erstellen und dann eine Verbindung mit einer SQL-Datenbank oder einer anderen Datenquelle herstellen.

Erstellen einer SQL-Datenbank

So erstellen Sie eine SQL-Datenbank, die Beispieldaten für Ihre GraphQL-API enthält:

  1. Wählen Sie im Fabric-Arbeitsbereich "Neues Element" aus.
  2. Wählen Sie sql-Datenbank (Vorschau) aus.
  3. Geben Sie einen Namen für Ihre Datenbank an.
  4. Wählen Sie Beispieldaten aus, um Automatisch Tabellen zu erstellen und mit Beispieldaten aufzufüllen. Dadurch wird die AdventureWorksLT-Beispieldatenbank mit dem Schema "SalesLT" erstellt, einschließlich Tabellen wie "SalesLT.Customer", "SalesLT.Product" und "SalesLT.SalesOrderHeader".

Tipp

Wenn Sie bereits über eine SQL-Datenbank mit Beispieldaten aus einem vorherigen Lernprogramm oder einer GraphQL-API-Erstellung verfügen, können Sie dieselbe Datenbank wiederverwenden. Eine einzelne Datenbank kann mehrere GraphQL-APIs unterstützen, daher ist es nicht erforderlich, eine neue Datenbank zu erstellen, wenn Sie bereits über eins mit dem SalesLT-Schema verfügen.

Erstellen der GraphQL-API

Nachdem Sie nun über eine SQL-Datenbank mit Beispieldaten verfügen, erstellen Sie die GraphQL-API:

  1. Wählen Sie in Ihrer SQL-Datenbank im Menüband "Neue API für GraphQL " aus.

    Screenshot der Option

  2. Geben Sie einen Namen für Ihre API an.

  3. Wählen Sie alle SalesLT-Tabellen aus Ihrer Datenbank aus.

  4. Wählen Sie "Laden" aus, um die API zu generieren.

Ihre GraphQL-API ist jetzt bereit und in Ihrem Fabric-Arbeitsbereich verfügbar.

Schritt 2: Einrichten Ihrer Entwicklungsumgebung

Führen Sie die folgenden Schritte aus, um die React-Startanwendung einzurichten, die erforderlichen Abhängigkeiten zu installieren und Visual Studio Code mit GraphQL-Unterstützung zu konfigurieren.

  1. Klonen Sie die Startanwendung – Rufen Sie die React-Startanwendung aus dem Microsoft Fabric-Beispiel-Repository ab:

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

  2. Installieren von Abhängigkeiten – Installieren Sie die erforderlichen Pakete für die GraphQL-Entwicklung, sowie Autovervollständigung und Codegenerierung.

    npm install

  3. Installieren Sie die erforderliche Visual Studio Code-Erweiterung – Installieren Sie die GraphQL: Language Feature Support-Erweiterung in Visual Studio Code, um Syntaxmarkierung, Validierung und IntelliSense für GraphQL-Vorgänge zu ermöglichen.

Schritt 3: Konfigurieren des GraphQL-Schemas

Ein GraphQL-Schema definiert die Struktur Ihrer API – welche Daten verfügbar sind, welche Vorgänge Sie ausführen können und welche Beziehungen zwischen verschiedenen Datentypen bestehen. Ihre Entwicklungstools verwenden dieses Schema, um IntelliSense, Codevervollständigung und Typgenerierung bereitzustellen, wodurch es wesentlich einfacher ist, korrekte GraphQL-Abfragen und -Mutationen zu schreiben.

Sie können Ihr GraphQL-Schema auf zwei Arten abrufen:

Option 1: Exportieren des Schemas als statische Datei

  1. Wählen Sie in Ihrer Fabric GraphQL-API im Menüband "Schema exportieren " aus.
  2. Der heruntergeladene Dateiname enthält die ID Ihrer GraphQL-API (z. B GraphQL_your-api-id_schema.graphql. ). Speichern Sie es in Ihrem Projektstammverzeichnis, und benennen Sie es schema.graphql um – dies ist der Dateiname, den Sie in den folgenden Konfigurationsschritten verwenden.

Option 2: Remoteendpunkt verwenden

  1. Greifen Sie auf die GraphQL-API zu, die Sie im Fabric-Portal erstellt haben.
  2. Abrufen eines Autorisierungstokens mithilfe von PowerShell mit Get-PowerBIAccessToken

Hinweis

Die Remoteendpunktoption stellt zwar immer das am meisten up-to-date-Schema bereit, das abgerufene Token ist jedoch temporär und läuft stündlich ab. Sie sollten nur zu Test- und Entwicklungszwecken verwendet werden, wenn möglich, eine statische Datei verwenden, um Probleme mit dem Ablauf von Token zu vermeiden.

Schritt 4: Konfigurieren von IntelliSense und AutoVervollständigen

Jetzt richten Sie IntelliSense mithilfe des Schemas in Schritt 3 ein. Die Schemadatei, sei sie statisch oder von einem Remote-Endpunkt, ermöglicht es VS Code, während Sie GraphQL-Abfragen schreiben, Echtzeit-Code-Vorschläge, Fehlererkennung und Feldüberprüfung bereitzustellen.

Erstellen Sie eine Konfigurationsdatei im Projektstamm:

Verwenden einer statischen Schemadatei

Verwenden Sie die folgende Konfiguration, wenn Sie das Schema als statische Datei exportiert haben:

Erstellen:.graphqlrc.yml

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

Verwenden des Remoteendpunkts

Verwenden Sie die folgende Konfiguration, wenn Sie das Schema lieber direkt vom GraphQL-API-Endpunkt abrufen möchten:

Erstellen:graphql.config.yml

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

Konfigurationsoptionen

  • schema: Gibt den Speicherort Ihres GraphQL-Schemas an.
  • documents: Definiert, welche Dateien intelliSense unterstützen sollen

Starten Sie nach dem Erstellen der Konfigurationsdatei Visual Studio Code neu, um sicherzustellen, dass Änderungen wirksam werden.

Schritt 5: Einrichten der Codegenerierung

Die GraphQL-Codegenerierung erstellt automatisch stark typierte TypeScript-Schnittstellen und React-Hooks aus Ihrem Schema und Ihren Vorgängen, reduziert Fehler und verbessert die Entwicklungseffizienz. Der Hauptzweck besteht darin, die Typsicherheit zu verbessern und die Entwicklung in GraphQL-Projekten zu optimieren, insbesondere bei der Arbeit mit stark typisierte Sprachen wie TypeScript.

Erstellen der Codegenkonfiguration

Option "Statische Datei"

Wenn Sie das Schema als statische Datei exportiert haben, erstellen Sie im Projektstamm eine Datei codegen.yml.

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

Option "Remote-Endpunkt"

Wenn Sie den Remoteendpunktansatz verwenden, erstellen Sie codegen.yml im Projektverzeichnis:

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

Aufschlüsselung der Konfiguration

  • Schema: Pfad zur Schemadatei oder zum Remoteendpunkt
  • documents: Glob-Muster zur Lokalisierung von GraphQL-Operationsdateien
  • generiert: Gibt die Ausgabedatei für generierten Code an.
  • plugins: Bestimmt, welcher Code generiert werden soll (TypeScript-Typen und React Apollo-Hooks)

Hinzufügen eines Codegenskripts

Fügen Sie das Codegenerierungsskript zur package.json Datei in Ihrem Projektverzeichnis hinzu (diese Datei wurde beim Klonen des Repositorys in Schritt 2 enthalten):

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

Schritt 6: Schreiben von GraphQL-Vorgängen

Erstellen Sie .graphql Dateien in Ihrem src/operations Verzeichnis, um Ihre Abfragen und Mutationen zu definieren. IntelliSense bietet AutoVervollständigen und Validierung.

Beispielabfragen

Erstellen Sie src/operations/queries.graphql und geben Sie die folgenden Abfragen ein:

Hier ist eine Beispielabfrage zum Abrufen von Kundendaten:

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

Hier ist eine Beispielmutation:

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

Schritt 7: Generieren von Typen und Hooks

Führen Sie den Codegenerierungsbefehl aus, um TypeScript-Typen und React-Hooks zu erstellen:

npm run codegen

Nach erfolgreichem Abschluss haben Sie den generierten Code in src/generated/graphql.tsx folgendem Code enthalten:

  • TypeScript-Schnittstellen für alle GraphQL-Typen
  • Stark typierte React-Hooks für jeden Vorgang
  • Eingabe- und Ausgabetypdefinitionen

Schritt 8: Verwenden von generierten Code in Ihren React-Komponenten

Importieren und verwenden Sie die generierten Hooks in Ihren React-Komponenten, z. B.:

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;

Schritt 9: Konfigurieren der Authentifizierung

Konfigurieren Sie die Microsoft Entra ID-Authentifizierung für Ihre Anwendung:

  1. Erstellen Sie eine Microsoft Entra-App nach dem Abschnitt "Erstellen einer Microsoft Entra-App " in Connect-Anwendungen mit der Fabric-API für GraphQL.

  2. Aktualisieren Sie die authConfig.ts Datei in Ihrem Projekt mit den erforderlichen Parametern:

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

Die vollständige Konfigurationsdatei finden Sie im authConfig.ts Beispiel im Repository.

Schritt 10: Ausführen der Anwendung

Starten Sie Ihren Entwicklungsserver:

npm run dev

Ihre Anwendung startet im Browser unter http://localhost:3000. Sie werden aufgefordert, sich mit Ihren Microsoft-Anmeldeinformationen anzumelden, um auf die GraphQL-API-Daten zuzugreifen. Nach erfolgreicher Authentifizierung werden die Kundendaten aus der Tabelle SalesLT.Customer Ihrer Fabric SQL-Datenbank in der React-Anwendung angezeigt.

Verwandte Inhalte

  • Last updated on