Condividi tramite

Sviluppare applicazioni GraphQL in Visual Studio Code

Informazioni su come creare un'applicazione front-end con React, Apollo Client e TypeScript che si integra con un'API GraphQL ospitata in Microsoft Fabric. Questa esercitazione illustra la configurazione di strumenti di sviluppo locali, tra cui il completamento automatico, la generazione di codice e IntelliSense per un'esperienza di sviluppo ottimale.

Chi deve usare gli strumenti di sviluppo di VS Code

Lo sviluppo locale con VS Code è progettato per:

  • Sviluppatori React che creano applicazioni Web che usano i dati di Fabric lakehouse e warehouse tramite GraphQL
  • Sviluppatori TypeScript che necessitano della generazione di codice client indipendente dai tipi per le API GraphQL di Fabric
  • Sviluppatori full-stack che creano applicazioni di analisi personalizzate sulla piattaforma Fabric con supporto dell'IDE locale
  • Team di sviluppo che vogliono strumenti moderni con IntelliSense e debug per le applicazioni di accesso ai dati di Fabric

Usare questo approccio quando si creano applicazioni React che necessitano di supporto avanzato dell'IDE, generazione di codice e funzionalità di debug locale con TypeScript e Apollo Client.

Prerequisiti

Prima di iniziare, assicurarsi di disporre di:

  • Accesso all'area di lavoro di Microsoft Fabric: è necessario essere un membro dell'area di lavoro di Microsoft Fabric con almeno il ruolo Collaboratore (o superiore: Amministratore, Membro) per creare e modificare gli elementi dell'API GraphQL.
  • Autorizzazioni origine dati: autorizzazioni di lettura/scrittura per le origini dati che si prevede di esporre tramite l'API GraphQL
  • Node.js installato nel computer di sviluppo (include npm)
  • Visual Studio Code installato nel computer di sviluppo
  • Conoscenza di base dei concetti di React, TypeScript e GraphQL

Passaggio 1: Creare un'API GraphQL in Microsoft Fabric

Annotazioni

Questa guida illustra la creazione di un'API GraphQL da un contesto di database SQL. Creare prima il database SQL, quindi creare l'API GraphQL direttamente da tale database. Se si ha già un'API GraphQL esistente e si vuole connettersi, seguire la guida introduttiva in cui si crea prima l'API e quindi connettersi a un database SQL o a un'altra origine dati.

Creare un database SQL

Per creare un database SQL contenente dati di esempio per l'API GraphQL:

  1. Nell'area di lavoro Infrastruttura selezionare Nuovo elemento.
  2. Selezionare Database SQL (anteprima) .
  3. Specificare un nome per il database.
  4. Selezionare Dati di esempio per creare automaticamente tabelle e popolarle con dati di esempio. Verrà creato il database di esempio AdventureWorksLT con lo schema SalesLT, incluse tabelle come SalesLT.Customer, SalesLT.Product e SalesLT.SalesOrderHeader.

Suggerimento

Se si dispone già di un database SQL con dati di esempio di un'esercitazione precedente o di creazione dell'API GraphQL, è possibile riutilizzare lo stesso database. Un database singolo può supportare più API GraphQL, quindi non è necessario creare un nuovo database se ne è già disponibile uno con lo schema SalesLT.

Creare l'API GraphQL

Dopo aver creato un database SQL con dati di esempio, creare l'API GraphQL:

  1. Nel database SQL selezionare Nuova API per GraphQL dalla barra multifunzione.

    Screenshot dell'opzione Nuova API per GraphQL nella barra multifunzione del database SQL.

  2. Specificare un nome per l'API.

  3. Selezionare tutte le tabelle SalesLT dal database.

  4. Selezionare Carica per generare l'API.

L'API GraphQL è ora pronta e disponibile nell'area di lavoro infrastruttura.

Passaggio 2: Configurare l'ambiente di sviluppo

Per seguire questa esercitazione, completare questi passaggi per configurare l'applicazione React Starter, installare le dipendenze necessarie e configurare Visual Studio Code con il supporto graphQL.

  1. Clona l'applicazione di avvio - Ottieni l'applicazione di avvio React dal repository degli esempi di Microsoft Fabric:

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

  2. Installare le dipendenze : installare i pacchetti necessari per lo sviluppo GraphQL, il completamento automatico e la generazione di codice:

    npm install

  3. Installare l'estensione necessaria di Visual Studio Code: installare l'estensioneGraphQL: Language Feature Support in Visual Studio Code per abilitare l'evidenziazione della sintassi, la convalida e IntelliSense per le operazioni GraphQL.

Passaggio 3: Configurare lo schema GraphQL

Uno schema GraphQL definisce la struttura dell'API, ovvero i dati disponibili, le operazioni che è possibile eseguire e le relazioni tra tipi di dati diversi. Gli strumenti di sviluppo usano questo schema per fornire IntelliSense, completamento del codice e generazione dei tipi, semplificando notevolmente la scrittura di query e mutazioni GraphQL corrette.

È possibile ottenere lo schema GraphQL in due modi:

Opzione 1: Esportare lo schema come file statico

  1. Nell'API GraphQL di Infrastruttura selezionare Esporta schema dalla barra multifunzione.
  2. Il nome del file scaricato include l'ID dell'API GraphQL , ad esempio GraphQL_your-api-id_schema.graphql. Salvarlo nella directory radice del progetto e rinominarlo schema.graphql in : questo è il nome file usato nei passaggi di configurazione che seguono.

Opzione 2: Usare l'endpoint remoto

  1. Accedere all'API GraphQL creata nel portale di Infrastruttura.
  2. Ottenere un token di autorizzazione usando PowerShell con Get-PowerBIAccessToken

Annotazioni

Mentre l'opzione endpoint remoto fornisce sempre lo schema più up-to-date, il token recuperato è temporaneo e scade ogni ora. Devono essere usati solo a scopo di test e sviluppo, quando possibile usare un file statico per evitare problemi con la scadenza del token.

Passaggio 4: Configurare IntelliSense e il completamento automatico

A questo punto si configurerà IntelliSense usando lo schema del passaggio 3. Il file di schema (statico o dall'endpoint remoto) consente a VS Code di fornire suggerimenti di codice in tempo reale, rilevamento degli errori e convalida dei campi durante la scrittura di query GraphQL.

Creare un file di configurazione nella radice del progetto:

Uso del file di schema statico

Usare la configurazione seguente se lo schema è stato esportato come file statico:

Creare .graphqlrc.yml:

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

Uso dell'endpoint remoto

Usare la configurazione seguente se si preferisce recuperare lo schema direttamente dall'endpoint dell'API GraphQL:

Creare graphql.config.yml:

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

Opzioni di configurazione

  • schema: specifica il percorso dello schema GraphQL
  • documenti: definisce quali file devono avere il supporto di IntelliSense

Dopo aver creato il file di configurazione, riavviare Visual Studio Code per assicurarsi che le modifiche siano effettive.

Passaggio 5: Configurare la generazione di codice

La generazione di codice GraphQL crea automaticamente interfacce TypeScript fortemente tipizzato e hook React dallo schema e dalle operazioni, riducendo gli errori e migliorando l'efficienza dello sviluppo. Il suo scopo principale è quello di migliorare la sicurezza dei tipi e semplificare lo sviluppo nei progetti GraphQL, in particolare quando si lavora con linguaggi fortemente tipizzato come TypeScript.

Creare una configurazione codegen

Opzione file statico

Se lo schema è stato esportato come file statico, creare codegen.yml nella radice del progetto:

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

Opzione Endpoint remoto

Se si usa l'approccio endpoint remoto, creare codegen.yml nella radice del progetto:

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

Suddivisione della configurazione

  • schema: percorso del file di schema o dell'endpoint remoto
  • documents: modello Glob per l'individuazione dei file dell'operazione GraphQL
  • generate: specifica il file di output per il codice generato
  • plugins: determina il codice da generare (tipi TypeScript e hook React Apollo)

Aggiungere script codegen

Aggiungere lo script di generazione del codice al file nella directory del package.json progetto (questo file è stato incluso durante la clonazione del repository nel passaggio 2):

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

Passaggio 6: Scrivere operazioni GraphQL

Creare .graphql file nella src/operations directory per definire le query e le mutazioni. IntelliSense fornisce il completamento automatico e la convalida.

Interrogazioni di esempio

Creare src/operations/queries.graphql e immettere le query seguenti:

Ecco una query di esempio per recuperare i dati dei clienti:

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

Ecco una mutazione di esempio:

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

Passaggio 7: Generare tipi e hook

Eseguire il comando di generazione del codice per creare tipi TypeScript e hook React:

npm run codegen

Al termine, il codice generato in src/generated/graphql.tsx contiene:

  • Interfacce TypeScript per tutti i tipi GraphQL
  • Hook React fortemente tipizzato per ogni operazione
  • Definizioni dei tipi di input e di output

Passaggio 8: Usare il codice generato nei componenti React

Importare e usare gli hook generati nei componenti React, ad esempio:

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;

Passaggio 9: Configurare l'autenticazione

Configurare l'autenticazione di Microsoft Entra ID per l'applicazione:

  1. Creare un'app Microsoft Entra seguendo la sezione Creare un'app Microsoft Entra in Connettere le applicazioni all'API infrastruttura per GraphQL.

  2. Aggiornare il authConfig.ts file nel progetto con i parametri obbligatori:

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

Per il file di configurazione completo, vedere l'esempio di authConfig.ts nel repository.

Passaggio 10: Eseguire l'applicazione

Avviare il server di sviluppo:

npm run dev

L'applicazione viene avviata nel browser all'indirizzo http://localhost:3000. Viene richiesto di accedere con le credenziali Microsoft per accedere ai dati dell'API GraphQL. Dopo una corretta autenticazione, vedrai i dati dei clienti dalla tabella SalesLT.Customer del database SQL di Fabric visualizzati nell'applicazione React.

Contenuti correlati

  • Last updated on