Compartir a través de

Desarrollo de aplicaciones graphQL en Visual Studio Code

Obtenga información sobre cómo crear una aplicación de front-end con React, Apollo Client y TypeScript que se integra con una API de GraphQL hospedada en Microsoft Fabric. En este tutorial se tratan la configuración de herramientas de desarrollo local, como la autocompletar, la generación de código e IntelliSense para una experiencia de desarrollador óptima.

Quién debe usar las herramientas de desarrollo de VS Code

El desarrollo local con VS Code está diseñado para:

  • Desarrolladores de React que crean aplicaciones web que consumen datos del lakehouse y del almacén de Fabric con GraphQL
  • Desarrolladores de TypeScript que necesitan generación de código de cliente seguro para tipos para las API de GraphQL de Fabric
  • Desarrolladores de pila completa que crean aplicaciones de análisis personalizadas en la plataforma Fabric con soporte para IDE locales
  • Equipos de desarrollo que desean herramientas modernas con IntelliSense y depuración para aplicaciones de acceso a datos de Fabric

Use este enfoque al compilar aplicaciones react que necesitan compatibilidad enriquecida con IDE, generación de código y funcionalidades de depuración local con TypeScript y Apollo Client.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene:

  • Acceso al área de trabajo de Microsoft Fabric: sea miembro del área de trabajo de Fabric con al menos el rol Colaborador (o superior: Administrador, Miembro) para crear y modificar elementos de GraphQL API.
  • Permisos de origen de datos: permisos de lectura y escritura en los orígenes de datos que planea exponer a través de GraphQL API
  • Node.js instalado en la máquina de desarrollo (incluye npm)
  • Visual Studio Code instalado en la máquina de desarrollo
  • Conocimientos básicos de los conceptos de React, TypeScript y GraphQL

Paso 1: Crear una API de GraphQL en Microsoft Fabric

Nota:

En esta guía se muestra cómo crear una API de GraphQL a partir de un contexto de base de datos SQL. Primero debe crear la base de datos SQL y, a continuación, crear graphQL API directamente desde esa base de datos. Si ya tiene una API de GraphQL existente y quiere conectarse a ella, siga la guía Introducción donde cree primero la API y, a continuación, conéctese a una base de datos SQL u otro origen de datos.

Creación de una base de datos SQL

Para crear una base de datos SQL que contenga datos de ejemplo para GraphQL API:

  1. En el área de trabajo de Fabric, seleccione Nuevo elemento.
  2. Seleccione BASE de datos SQL (versión preliminar) .
  3. Proporcione un nombre para la base de datos.
  4. Seleccione Datos de ejemplo para crear tablas automáticamente y rellenarlas con datos de ejemplo. Esto crea la base de datos de ejemplo AdventureWorksLT con el esquema SalesLT, incluidas tablas como SalesLT.Customer, SalesLT.Product y SalesLT.SalesOrderHeader.

Sugerencia

Si ya tiene una base de datos SQL con datos de ejemplo de un tutorial anterior o creación de GraphQL API, puede reutilizar esa misma base de datos. Una base de datos única puede admitir varias API de GraphQL, por lo que no es necesario crear una nueva base de datos si ya tiene una con el esquema SalesLT.

Creación de GraphQL API

Ahora que tiene una base de datos SQL con datos de ejemplo, cree GraphQL API:

  1. En la base de datos SQL, seleccione Nueva API para GraphQL en la cinta de opciones.

    Captura de pantalla de la opción New API for GraphQL (Nueva API para GraphQL) en la cinta de opciones de SQL Database.

  2. Proporcione un nombre para la API.

  3. Seleccione todas las tablas SalesLT de la base de datos.

  4. Seleccione Cargar para generar la API.

El API de GraphQL está ahora listo y disponible en tu área de trabajo de Fabric.

Paso 2: Configuración del entorno de desarrollo

Para seguir este tutorial, complete estos pasos para configurar la aplicación de inicio de React, instalar las dependencias necesarias y configurar Visual Studio Code con compatibilidad con GraphQL.

  1. Clone la aplicación de inicio : obtenga la aplicación de inicio de React desde el repositorio de ejemplos de Microsoft Fabric:

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

  2. Instalar dependencias - Instale los paquetes necesarios para el desarrollo, la autocompleción y la generación de código de GraphQL.

    npm install

  3. Instale la extensión de Visual Studio Code necesaria: instale la extensión GraphQL: Language Feature Support en Visual Studio Code para habilitar el resaltado de sintaxis, la validación e IntelliSense para las operaciones de GraphQL.

Paso 3: Configurar el esquema de GraphQL

Un esquema de GraphQL define la estructura de la API: qué datos están disponibles, qué operaciones puede realizar y cuáles son las relaciones entre diferentes tipos de datos. Las herramientas de desarrollo usan este esquema para proporcionar IntelliSense, finalización de código y generación de tipos, lo que facilita mucho la escritura de las consultas y mutaciones de GraphQL correctas.

Puede obtener el esquema de GraphQL de dos maneras:

Opción 1: Exportar esquema como archivo estático

  1. En Fabric GraphQL API, seleccione Exportar esquema en la cinta de opciones.
  2. El nombre de archivo descargado incluye el identificador de GraphQL API (por ejemplo, GraphQL_your-api-id_schema.graphql). Guárdelo en el directorio raíz del proyecto y cámbielo por schema.graphql : este es el nombre de archivo que se usa en los pasos de configuración siguientes.

Opción 2: Uso del punto de conexión remoto

  1. Acceda al GraphQL API que creó en el Fabric Portal.
  2. Obtención de un token de autorización mediante PowerShell con Get-PowerBIAccessToken

Nota:

Aunque la opción de extremo remoto siempre proporciona el esquema más actualizado, el token recuperado es temporal y caduca cada hora. Solo deben usarse con fines de prueba y desarrollo, siempre que sea posible, usar un archivo estático para evitar problemas con la expiración del token.

Paso 4: Configurar IntelliSense y autocompletar

Ahora configurará IntelliSense con el esquema del paso 3. El archivo de esquema (ya sea estático o desde un punto de conexión remoto) permite a VS Code proporcionar sugerencias de código en tiempo real, detección de errores y validación de campos a medida que escribe consultas de GraphQL.

Cree un archivo de configuración en la raíz del proyecto:

Uso de un archivo de esquema estático

Use la siguiente configuración si exportó el esquema como un archivo estático:

Crear .graphqlrc.yml:

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

Uso del punto de conexión remoto

Use la siguiente configuración si prefiere capturar el esquema directamente desde el punto de conexión de GraphQL API:

Crear graphql.config.yml:

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

Opciones de configuración

  • esquema: especifica la ubicación del esquema de GraphQL.
  • documentos: define qué archivos deben tener compatibilidad con IntelliSense

Después de crear el archivo de configuración, reinicie Visual Studio Code para asegurarse de que los cambios surtan efecto.

Paso 5: Configuración de la generación de código

La generación de código GraphQL crea automáticamente interfaces TypeScript fuertemente tipadas y hooks de React a partir de tu esquema y operaciones, lo que reduce los errores y mejora la eficiencia del desarrollo. Su objetivo principal es mejorar la seguridad de tipos y simplificar el desarrollo en proyectos de GraphQL, especialmente cuando se trabaja con lenguajes fuertemente tipados como TypeScript.

Creación de una configuración de codegen

Opción de archivo estático

Si exportó el esquema como un archivo estático, cree codegen.yml en la raíz del proyecto:

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

Opción punto de conexión remoto

Si está utilizando el enfoque de punto final remoto, cree codegen.yml en la raíz del proyecto:

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

Desglose de la configuración

  • schema: ruta de acceso al archivo de esquema o al punto de conexión remoto
  • documentos: patrón global para localizar archivos de operación de GraphQL
  • genera: especifica el archivo de salida para el código generado.
  • plugins: determina qué código se va a generar (tipos TypeScript y enlaces de React Apollo)

Adición de script codegen

Agregue el script de generación de código al archivo en el package.json directorio del proyecto (este archivo se incluyó al clonar el repositorio en el paso 2):

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

Paso 6: Escribir operaciones de GraphQL

Cree .graphql archivos en el src/operations directorio para definir las consultas y las mutaciones. IntelliSense proporciona autocompletado y validación.

Consultas de ejemplo

Cree src/operations/queries.graphql y escriba las siguientes consultas:

Esta es una consulta de ejemplo para recuperar los datos del cliente:

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

Esta es una mutación de ejemplo:

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

Paso 7: Generar tipos y enlaces

Ejecute el comando de generación de código para crear tipos TypeScript y enlaces de React:

npm run codegen

Al completar con éxito, tendrá el código generado en src/generated/graphql.tsx que contiene:

  • Interfaces de TypeScript para todos los tipos de GraphQL
  • Hooks de React fuertemente tipados para cada operación.
  • Definiciones de tipo de entrada y salida

Paso 8: Uso del código generado en los componentes de React

Importe y use los enlaces generados en los componentes de React, por ejemplo:

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;

Paso 9: Configuración de la autenticación

Configura la autenticación de Microsoft Entra ID para tu aplicación:

  1. Cree una aplicación de Microsoft Entra siguiendo la sección Creación de una aplicación de Microsoft Entra en Conexión de aplicaciones a Fabric API para GraphQL.

  2. Actualice el authConfig.ts archivo del proyecto con los parámetros necesarios:

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

Para obtener el archivo de configuración completo, consulte el ejemplo de authConfig.ts en el repositorio.

Paso 10: Ejecución de la aplicación

Inicie el servidor de desarrollo:

npm run dev

La aplicación se inicia en el explorador en http://localhost:3000. Se le pedirá que inicie sesión con sus credenciales de Microsoft para acceder a los datos de GraphQL API. Después de la autenticación correcta, verá que los datos de cliente de la tabla de SalesLT.Customer la base de datos SQL de Fabric se muestran en la aplicación React.

Contenido relacionado

  • Last updated on