Partage via

Développer des applications GraphQL dans Visual Studio Code

Découvrez comment créer une application frontale avec React, Apollo Client et TypeScript qui s’intègre à une API GraphQL hébergée dans Microsoft Fabric. Ce tutoriel traite de la configuration des outils de développement locaux, notamment la saisie automatique, la génération de code et IntelliSense pour une expérience de développement optimale.

Qui doit utiliser les outils de développement VS Code

Le développement local avec VS Code est conçu pour :

  • Développeurs React créant des applications web qui consomment des données de Fabric Lakehouse et Warehouse via GraphQL
  • Développeurs TypeScript qui ont besoin d’une génération de code client de type sécurisé pour les API Fabric GraphQL
  • Développeurs full-stack qui créent des applications d'analytique sur mesure sur la plateforme Fabric avec prise en charge de l'IDE local
  • Équipes de développement qui souhaitent des outils modernes avec IntelliSense et le débogage pour les applications d’accès aux données Fabric

Utilisez cette approche lorsque vous créez des applications React qui ont besoin d’une prise en charge complète de l’IDE, de la génération de code et des fonctionnalités de débogage locales avec TypeScript et Apollo Client.

Prerequisites

Avant de commencer, vérifiez que vous disposez des points suivants :

  • Accès à l’espace de travail Microsoft Fabric : être membre de l’espace de travail Fabric avec au moins le rôle Contributeur (ou supérieur : Administrateur, Membre) pour créer et modifier des éléments d’API GraphQL
  • Autorisations de source de données : autorisations en lecture/écriture sur les sources de données que vous envisagez d’exposer via l’API GraphQL
  • Node.js installé sur votre ordinateur de développement (inclut npm)
  • Visual Studio Code installé sur votre ordinateur de développement
  • Connaissance de base des concepts React, TypeScript et GraphQL

Étape 1 : Créer une API GraphQL dans Microsoft Fabric

Note

Ce guide montre comment créer une API GraphQL à partir d’un contexte de base de données SQL. Vous créez d’abord la base de données SQL, puis créez l’API GraphQL directement à partir de cette base de données. Si vous disposez déjà d’une API GraphQL existante et que vous souhaitez vous y connecter, suivez le guide de prise en main où vous créez d’abord l’API, puis connectez-vous à une base de données SQL ou à une autre source de données.

Créer une base de données SQL

Pour créer une base de données SQL qui contient des exemples de données pour votre API GraphQL :

  1. Dans votre espace de travail Fabric, sélectionnez Nouvel élément.
  2. Sélectionnez base de données SQL (préversion).
  3. Indiquez un nom pour votre base de données.
  4. Sélectionnez Exemples de données pour créer automatiquement des tables et les remplir avec des exemples de données. Cela crée l’exemple de base de données AdventureWorksLT avec le schéma SalesLT, y compris les tables telles que SalesLT.Customer, SalesLT.Product et SalesLT.SalesOrderHeader.

Conseil / Astuce

Si vous disposez déjà d’une base de données SQL avec des exemples de données à partir d’un didacticiel précédent ou de la création d’API GraphQL, vous pouvez réutiliser cette même base de données. Une base de données unique peut prendre en charge plusieurs API GraphQL. Il n’est donc pas nécessaire de créer une base de données si vous en avez déjà une avec le schéma SalesLT.

Créer l’API GraphQL

Maintenant que vous disposez d’une base de données SQL avec des exemples de données, créez l’API GraphQL :

  1. Dans votre base de données SQL, sélectionnez Nouvelle API pour GraphQL dans le ruban.

    Capture d’écran de l’option Nouvelle API pour GraphQL dans le ruban de base de données SQL.

  2. Indiquez un nom pour votre API.

  3. Sélectionnez toutes les tables SalesLT de votre base de données.

  4. Sélectionnez Charger pour générer l’API.

Votre API GraphQL est maintenant prête et disponible dans votre espace de travail Fabric.

Étape 2 : Configurer votre environnement de développement

Pour suivre ce didacticiel, procédez comme suit pour configurer l’application de démarrage React, installer les dépendances nécessaires et configurer Visual Studio Code avec la prise en charge de GraphQL.

  1. Clonez l’application de démarrage : obtenez l’application de démarrage React à partir du référentiel d’exemples Microsoft Fabric :

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

  2. Installer les dépendances : installez les packages requis pour le développement GraphQL, la saisie automatique et la génération de code :

    npm install

  3. Installez l’extension Visual Studio Code requise : installez l’extension GraphQL : Language Feature Support dans Visual Studio Code pour activer la mise en surbrillance de la syntaxe, la validation et IntelliSense pour les opérations GraphQL.

Étape 3 : Configurer votre schéma GraphQL

Un schéma GraphQL définit la structure de votre API : quelles données sont disponibles, quelles opérations vous pouvez effectuer et quelles relations entre différents types de données sont. Vos outils de développement utilisent ce schéma pour fournir IntelliSense, la saisie semi-automatique du code et la génération de types, ce qui facilite considérablement l’écriture de requêtes et de mutations GraphQL correctes.

Vous pouvez obtenir votre schéma GraphQL de deux façons :

Option 1 : Exporter le schéma en tant que fichier statique

  1. Dans votre API Fabric GraphQL, sélectionnez Exporter le schéma dans le ruban.
  2. Le nom de fichier téléchargé inclut l’ID de votre API GraphQL (par exemple). GraphQL_your-api-id_schema.graphql Enregistrez-le dans le répertoire racine de votre projet et renommez-le schema.graphql : il s’agit du nom de fichier que vous utilisez dans les étapes de configuration qui suivent.

Option 2 : Utiliser un point de terminaison distant

  1. Accédez à l’API GraphQL que vous avez créée dans le portail Fabric.
  2. Obtenir un jeton d’autorisation à l’aide de PowerShell avec Get-PowerBIAccessToken

Note

Bien que l’option de point de terminaison distant fournit toujours le schéma le plus up-to-date, le jeton récupéré est temporaire et expire toutes les heures. Ils doivent être utilisés uniquement à des fins de test et de développement, dans la mesure du possible, utiliser un fichier statique pour éviter les problèmes liés à l’expiration du jeton.

Étape 4 : Configurer IntelliSense et la saisie automatique

Vous allez maintenant configurer IntelliSense à l’aide du schéma de l’étape 3. Le fichier de schéma (qu’il s’agisse d’un point de terminaison statique ou distant) permet à VS Code de fournir des suggestions de code en temps réel, la détection des erreurs et la validation de champ lorsque vous écrivez des requêtes GraphQL.

Créez un fichier de configuration à la racine de votre projet :

Utilisation du fichier de schéma statique

Utilisez la configuration suivante si vous avez exporté le schéma en tant que fichier statique :

Créer .graphqlrc.yml:

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

Utilisation du point de terminaison distant

Utilisez la configuration suivante si vous préférez récupérer le schéma directement à partir de votre point de terminaison d’API GraphQL :

Créer graphql.config.yml:

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

Options de configuration

  • schéma : spécifie l’emplacement de votre schéma GraphQL
  • documents : définit les fichiers qui doivent prendre en charge IntelliSense

Après avoir créé le fichier de configuration, redémarrez Visual Studio Code pour vous assurer que les modifications prennent effet.

Étape 5 : Configurer la génération de code

La génération de code GraphQL crée automatiquement des interfaces TypeScript fortement typées et des hooks React à partir de votre schéma et opérations, ce qui réduit les erreurs et améliore l’efficacité du développement. Son objectif principal est d’améliorer la sécurité des types et de simplifier le développement dans les projets GraphQL, en particulier lors de l’utilisation de langages fortement typés comme TypeScript.

Créer une configuration codegen

Option de fichier statique

Si vous avez exporté le schéma en tant que fichier statique, créez codegen.yml à la racine de votre projet :

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

Option de point de terminaison distant

Si vous utilisez l’approche de point de terminaison distant, créez codegen.yml à la racine de votre projet :

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

Répartition de la configuration

  • schéma : chemin d’accès à votre fichier de schéma ou point de terminaison distant
  • documents : modèle Glob pour localiser les fichiers d’opération GraphQL
  • génère : spécifie le fichier de sortie pour le code généré
  • plug-ins : détermine le code à générer (types TypeScript et hooks React Apollo)

Ajouter un script codegen

Ajoutez le script de génération de code au fichier dans votre package.json répertoire de projet (ce fichier a été inclus lorsque vous avez cloné le référentiel à l’étape 2) :

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

Étape 6 : Écrire des opérations GraphQL

Créez des .graphql fichiers dans votre src/operations répertoire pour définir vos requêtes et mutations. IntelliSense fournit la saisie automatique et la validation.

Exemples de requêtes

Créez src/operations/queries.graphql et entrez les requêtes suivantes :

Voici un exemple de requête pour récupérer les données client :

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

Voici un exemple de mutation :

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

Étape 7 : Générer des types et des hooks

Exécutez la commande de génération de code pour créer des types TypeScript et des hooks React :

npm run codegen

Une fois l’opération terminée, vous disposez du code généré dans src/generated/graphql.tsx lequel se trouver :

  • Interfaces TypeScript pour tous les types GraphQL
  • Crochets React fortement typés pour chaque opération
  • Définitions de type d’entrée et de sortie

Étape 8 : Utiliser le code généré dans vos composants React

Importez et utilisez les hooks générés dans vos composants React, par exemple :

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;

Étape 9 : Configurer l’authentification

Configurez l’authentification d’ID Microsoft Entra pour votre application :

  1. Créez une application Microsoft Entra en suivant la section Créer une application Microsoft Entra dans Connecter des applications à l’API Fabric pour GraphQL.

  2. Mettez à jour le authConfig.ts fichier dans votre projet avec les paramètres requis :

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

Pour le fichier de configuration complet, reportez-vous à l’exemple authConfig.ts dans le référentiel.

Étape 10 : Exécuter votre application

Démarrez votre serveur de développement :

npm run dev

Votre application démarre dans le navigateur à l’adresse http://localhost:3000. Vous êtes invité à vous connecter avec vos informations d’identification Microsoft pour accéder aux données de l’API GraphQL. Une fois l’authentification réussie, vous verrez les données client de la table de votre base de SalesLT.Customer données Fabric SQL affichée dans l’application React.

Contenu connexe

  • Last updated on