Desenvolver aplicações GraphQL em Visual Studio Code

Saiba como criar um aplicativo front-end com React, Apollo Client e TypeScript que se integra a uma API GraphQL hospedada no Microsoft Fabric. Este tutorial aborda a configuração de ferramentas de desenvolvimento local, incluindo preenchimento automático, geração de código e IntelliSense para uma experiência de desenvolvedor ideal.

Quem deve usar as ferramentas de desenvolvimento do VS Code

O desenvolvimento local com VS Code foi concebido para:

Desenvolvedores React a construir aplicações web que consomem dados Fabric de lagos e armazéns via GraphQL
Desenvolvedores TypeScript que precisam de geração de código cliente com segurança de tipos para APIs Fabric GraphQL
Desenvolvedores full-stack que constroem aplicações de análise personalizadas sobre plataforma Fabric com suporte de IDE local
Equipas de desenvolvimento que querem ferramentas modernas com IntelliSense e depuração para aplicações de acesso a dados Fabric

Use esta abordagem quando estiver a construir aplicações React que necessitem de suporte avançado para IDE, geração de código e capacidades de depuração local com TypeScript e Apollo Client.

Pré-requisitos

Antes de começar, certifique-se de que tem:

Acesso ao espaço de trabalho Microsoft Fabric: Ser membro do espaço de trabalho Fabric com pelo menos um papel de Contribuidor (ou superior: Administrador, Membro) para criar e modificar itens da API GraphQL
Permissões de fontes de dados: Permissões de leitura/escrita nas fontes de dados que planeia expor através da API GraphQL
Node.js instalado na tua máquina de desenvolvimento (inclui o NPM)
Visual Studio Code instalado na sua máquina de desenvolvimento
Conhecimento básico dos conceitos React, TypeScript e GraphQL

Etapa 1: Criar uma API GraphQL no Microsoft Fabric

Observação

Este guia demonstra como criar uma API GraphQL a partir de um contexto de base de dados SQL. Crias primeiro a base de dados SQL e depois crias a API GraphQL diretamente a partir dessa base de dados. Se já tem uma API GraphQL existente e quer ligar-se a ela, siga o guia de início onde cria primeiro a API e depois liga-se a uma base de dados SQL ou outra fonte de dados.

Criar um banco de dados SQL

Para criar uma base de dados SQL que contenha dados de exemplo para a sua API GraphQL:

No seu espaço de trabalho Fabric, selecione Novo Item.
Selecione Banco de dados SQL (visualização).
Forneça um nome para seu banco de dados.
Selecione Dados de exemplo para criar tabelas automaticamente e preenchê-las com dados de exemplo. Isto cria a base de dados de exemplo AdventureWorksLT com o esquema SalesLT, incluindo tabelas como SalesLT.Customer, SalesLT.Product e SalesLT.SalesOrderHeader.

Sugestão

Se já tiver uma base de dados SQL com dados de exemplo de um tutorial anterior ou criação de API GraphQL, pode reutilizar essa mesma base de dados. Uma única base de dados pode suportar múltiplas APIs GraphQL, por isso não há necessidade de criar uma nova base de dados se já tiver uma com o esquema SalesLT.

Criar a API do GraphQL

Agora que tem uma base de dados SQL com dados de exemplo, crie a API GraphQL:

Na sua base de dados SQL, selecione Nova API para GraphQL na barra de ferramentas.
Forneça um nome para sua API.
Selecione todas as tabelas SalesLT do seu banco de dados.
Selecione Carregar para gerar a API.

Sua API do GraphQL agora está pronta e disponível em seu espaço de trabalho do Fabric.

Etapa 2: Configurar seu ambiente de desenvolvimento

Para acompanhar este tutorial, complete estes passos para configurar a aplicação inicial do React, instalar as dependências necessárias e configurar o Visual Studio Code com suporte a GraphQL.

Clone a aplicação inicial - Obtenha a aplicação inicial React do repositório de exemplos do Microsoft Fabric:

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

Instalar dependências - Instalar os pacotes necessários para desenvolvimento, autocompletação e geração de código em GraphQL:
```
npm install
```
Instale a extensão necessária Visual Studio Code - Instale a extensão GraphQL: Language Feature Support no Visual Studio Code para permitir o realce de sintaxe, validação e IntelliSense para operações GraphQL.

Etapa 3: Configurar o esquema do GraphQL

Um esquema GraphQL define a estrutura da sua API – que dados estão disponíveis, que operações pode realizar e quais são as relações entre os diferentes tipos de dados. As suas ferramentas de desenvolvimento usam este esquema para fornecer IntelliSense, completamento de código e geração de tipos, facilitando muito a escrita correta de consultas e mutações em GraphQL.

Você pode obter seu esquema GraphQL de duas maneiras:

Opção 1: Exportar esquema como arquivo estático

Na API do Fabric GraphQL, selecione Exportar esquema na faixa de opções.
O nome do ficheiro descarregado inclui o ID da sua API GraphQL (por exemplo, GraphQL_your-api-id_schema.graphql). Guarde-o no diretório raiz do seu projeto e renomeie-o para schema.graphql - este é o nome de ficheiro que usa nos passos de configuração que se seguem.

Opção 2: Usar ponto de extremidade remoto

Acesse a API do GraphQL que você criou no Fabric Portal.
Obter um token de autorização usando o PowerShell com Get-PowerBIAccessToken

Observação

Embora a opção de endpoint remoto forneça sempre o esquema mais atual, o token recuperado é temporário e expira a cada hora. Eles devem ser usados apenas para fins de teste e desenvolvimento, sempre que possível use um arquivo estático para evitar problemas com a expiração do token.

Etapa 4: Configurar o IntelliSense e o preenchimento automático

Agora vais configurar o IntelliSense usando o esquema do Passo 3. O ficheiro de esquema (seja estático ou de ponto final remoto) permite ao VS Code fornecer sugestões de código em tempo real, deteção de erros e validação de campos enquanto escreve consultas GraphQL.

Crie um arquivo de configuração na raiz do projeto:

Usando o arquivo de esquema estático

Use a seguinte configuração se exportou o esquema como um ficheiro estático:

Criar .graphqlrc.yml:

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

Usando ponto de extremidade remoto

Use a seguinte configuração se preferir obter o esquema diretamente do endpoint da sua API GraphQL:

Criar graphql.config.yml:

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

Opções de configuração

schema: especifica o local do esquema GraphQL
documentos: Define quais arquivos devem ter suporte ao IntelliSense

Depois de criar o arquivo de configuração, reinicie o Visual Studio Code para garantir que as alterações entrem em vigor.

Etapa 5: configurar a geração de código

A geração de código GraphQL cria automaticamente interfaces TypeScript fortemente tipadas e ganchos React a partir do seu esquema e operações, reduzindo erros e melhorando a eficiência do desenvolvimento. Seu principal objetivo é melhorar a segurança de tipo e agilizar o desenvolvimento em projetos GraphQL, particularmente quando se trabalha com linguagens fortemente tipadas como TypeScript.

Criar configuração de geração de código

Opção de ficheiro estático

Se exportaste o esquema como ficheiro estático, cria codegen.yml na raiz do teu projeto:

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

Opção de endpoint remoto

Se estiver a usar a abordagem de endpoint remoto, crie codegen.yml na raiz do seu projeto:

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

Detalhamento de configuração

schema: caminho para o ficheiro de esquema ou endpoint remoto
documentos: Padrão Glob para localizar arquivos de operação GraphQL
gera: especifica o arquivo de saída para o código gerado
plugins: Determina qual código gerar (tipos TypeScript e ganchos React Apollo)

Adicionar script de geração de código

Adicione o script de geração de código ao package.json ficheiro no diretório do seu projeto (este ficheiro foi incluído quando clonou o repositório no Passo 2):

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

Etapa 6: Escrever operações GraphQL

Crie .graphql ficheiros no seu src/operations diretório para definir as suas consultas e mutações. O IntelliSense fornece preenchimento automático e validação.

Exemplos de consultas

Crie src/operations/queries.graphql e introduza as seguintes consultas:

Aqui está uma consulta de exemplo para recuperar dados de clientes:

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

Aqui está um exemplo de mutação:

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

Etapa 7: Gerar tipos e ganchos

Execute o comando de geração de código para criar tipos TypeScript e ganchos React:

npm run codegen

Após a conclusão bem-sucedida, terá o código gerado em src/generated/graphql.tsx contendo:

Interfaces de TypeScript para todos os tipos de GraphQL
Ganchos React fortemente tipados para cada operação
Definições de tipos de entrada e saída

Etapa 8: Usar o código gerado em seus componentes do React

Importe e use os ganchos gerados em seus componentes React, por exemplo:

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;

Etapa 9: Configurar a autenticação

Configure a autenticação do Microsoft Entra ID para seu aplicativo:

Crie um aplicativo Microsoft Entra seguindo a seção Criar um aplicativo Microsoft Entra em Conectar aplicativos à API de malha para GraphQL.
Atualize o authConfig.ts arquivo em seu projeto com os parâmetros necessários:

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 obter o arquivo de configuração completo, consulte o exemplo de authConfig.ts no repositório.

Etapa 10: Executar seu aplicativo

Inicie o servidor de desenvolvimento:

npm run dev

A sua aplicação inicia-se no navegador em http://localhost:3000. É-lhe pedido que inicie sessão com as suas credenciais Microsoft para aceder aos dados da API GraphQL. Após a autenticação bem-sucedida, verá os dados do cliente apresentados na aplicação React a partir da tabela SalesLT.Customer da sua base de dados SQL Fabric.

Feedback

Esta página foi útil?

Last updated on 2026-01-21