Desenvolver aplicativos GraphQL no Visual Studio Code

Saiba como criar um aplicativo front-end com React, Apollo Client e TypeScript que se integra a uma API do GraphQL hospedada no Microsoft Fabric. Este tutorial aborda a configuração de ferramentas de desenvolvimento locais, 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 o VS Code foi projetado para:

Desenvolvedores do React que criam aplicativos Web que consomem dados do Fabric Lakehouse e do warehouse por meio do GraphQL
Desenvolvedores TypeScript que precisam de geração de código de cliente com tipagem segura para APIs GraphQL do Fabric
Desenvolvedores full-stack criando aplicativos de análise personalizada sobre a plataforma Fabric com suporte ao IDE local
Equipes de desenvolvimento que desejam ferramentas modernas com o IntelliSense e depuração para aplicativos de acesso a dados do Fabric

Use essa abordagem ao criar aplicativos React que precisam de suporte avançado do IDE, geração de código e recursos de depuração local com TypeScript e Apollo Client.

Pré-requisitos

Antes de começar, verifique se você tem:

Acesso ao workspace do Microsoft Fabric: seja membro do workspace do Fabric com pelo menos a função colaborador (ou superior: Administrador, Membro) para criar e modificar itens da API do GraphQL
Permissões de fonte de dados: permissões de leitura/gravação nas fontes de dados que você planeja expor por meio da API do GraphQL
Node.js instalado em seu computador de desenvolvimento (inclui npm)
Visual Studio Code instalado em seu computador de desenvolvimento
Conhecimento básico dos conceitos React, TypeScript e GraphQL

Etapa 1: Criar uma API do GraphQL no Microsoft Fabric

Observação

Este guia demonstra a criação de uma API do GraphQL a partir de um contexto de banco de dados SQL. Você cria o banco de dados SQL primeiro e, em seguida, cria a API do GraphQL diretamente dentro desse banco de dados. Se você já tiver uma API do GraphQL existente e quiser se conectar a ela, siga o guia Introdução em que você cria a API primeiro e, em seguida, conecte-se a um banco de dados SQL ou outra fonte de dados.

Criar um banco de dados SQL

Para criar um banco de dados SQL que contenha dados de exemplo para sua API do GraphQL:

No workspace do Fabric, selecione Novo Item.
Selecione o banco de dados SQL (versão prévia).
Forneça um nome para o banco de dados.
Selecione Dados de exemplo para criar tabelas automaticamente e preenchê-las com dados de exemplo. Isso cria o banco de dados de exemplo AdventureWorksLT com o esquema SalesLT, incluindo tabelas como SalesLT.Customer, SalesLT.Product e SalesLT.SalesOrderHeader.

Dica

Se você já tiver um banco de dados SQL com dados de exemplo de um tutorial anterior ou criação da API do GraphQL, poderá reutilizar esse mesmo banco de dados. Um banco de dados individual pode dar suporte a várias APIs do GraphQL, portanto, não será necessário criar um novo banco de dados se você já tiver um com o esquema SalesLT.

Criar a API do GraphQL

Agora que você tem um banco de dados SQL com dados de exemplo, crie a API do GraphQL:

No banco de dados SQL, selecione Nova API para GraphQL na faixa de opções.
Forneça um nome para sua API.
Selecione todas as tabelas SalesLT do banco de dados.
Selecione Carregar para gerar a API.

Sua API do GraphQL agora está pronta e disponível no workspace do Fabric.

Etapa 2: Configurar seu ambiente de desenvolvimento

Para acompanhar este tutorial, conclua estas etapas para configurar o aplicativo react starter, instalar as dependências necessárias e configurar o Visual Studio Code com suporte ao GraphQL.

Clone o aplicativo inicial – Obtenha o aplicativo starter do React do repositório de amostras 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 – Instale os pacotes necessários para desenvolvimento, preenchimento automático e geração de código do GraphQL:
```
npm install
```
Instale a extensão necessária do Visual Studio Code – Instale a extensão de Suporte a Recursos de Linguagem do GraphQL no Visual Studio Code para habilitar o realce, a validação e o IntelliSense para operações do GraphQL.

Etapa 3: Configurar o esquema do GraphQL

Um esquema GraphQL define a estrutura da API – quais dados estão disponíveis, quais operações você pode executar e quais são as relações entre diferentes tipos de dados. Suas ferramentas de desenvolvimento usam esse esquema para fornecer IntelliSense, preenchimento de código e geração de tipos, facilitando muito a gravação de consultas e mutações corretas do GraphQL.

Você pode obter seu esquema GraphQL de duas maneiras:

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

Na API do GraphQL do Fabric, selecione Exportar Esquema na faixa de opções.
O nome do arquivo baixado inclui a ID da API do GraphQL (por exemplo, GraphQL_your-api-id_schema.graphql). Salve-o no diretório raiz do projeto e renomeie-o para schema.graphql : esse é o nome de arquivo que você usa nas etapas de configuração a seguir.

Opção 2: usar o ponto de extremidade remoto

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

Observação

Embora a opção de ponto de extremidade remoto sempre forneça o esquema mais atualizado, o token recuperado é temporário e expira a cada hora. Eles devem ser usados somente 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 você configurará o IntelliSense usando o esquema da Etapa 3. O arquivo de esquema (estático ou de ponto de extremidade remoto) permite que o VS Code forneça sugestões de código em tempo real, detecção de erros e validação de campo ao escrever 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 você exportou o esquema como um arquivo estático:

Criar .graphqlrc.yml:

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

Usando o ponto de extremidade remoto

Use a seguinte configuração se preferir buscar o esquema diretamente do ponto de extremidade da API do 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

esquema: especifica o local do esquema do GraphQL
documentos: define quais arquivos devem ter suporte do 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 tipada e ganchos react de seu esquema e operações, reduzindo erros e melhorando a eficiência de desenvolvimento. Sua principal finalidade é aprimorar a segurança do tipo e simplificar o desenvolvimento em projetos do GraphQL, especialmente ao trabalhar com linguagens fortemente tipadas, como TypeScript.

Criar configuração de codegen

Opção de arquivo estático

Se você exportou o esquema como um arquivo estático, crie codegen.yml na raiz do 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 ponto de extremidade remoto

Se você estiver usando a abordagem de ponto de extremidade remoto, crie codegen.yml na raiz do 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

esquema: caminho para o arquivo de esquema ou ponto de extremidade remoto
documentos: padrão Glob para localizar arquivos de operação do GraphQL
gera: especifica o arquivo de saída para o código gerado
plug-ins: determina qual código gerar (tipos TypeScript e ganchos do React Apollo)

Adicionar script codegen

Adicione o script de geração de código ao package.json arquivo no diretório do projeto (esse arquivo foi incluído quando você clonou o repositório na Etapa 2):

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

Etapa 6: Escrever operações do GraphQL

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

Consultas de exemplo

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

Aqui está uma consulta de exemplo para recuperar dados do 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
    }
  }
}

Veja 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, você terá o código gerado contendo src/generated/graphql.tsx :

Interfaces TypeScript para todos os tipos do GraphQL
Ganchos react fortemente tipado para cada operação
Definições de tipo 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 do 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 da ID do Microsoft Entra para seu aplicativo:

Crie um aplicativo do Microsoft Entra seguindo a seção Criar um aplicativo do Microsoft Entra em aplicativos Connect à API do Fabric 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 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

Seu aplicativo é iniciado no navegador em http://localhost:3000. Você será solicitado a entrar com suas credenciais da Microsoft para acessar os dados da API do GraphQL. Após a autenticação bem-sucedida, você verá os dados do cliente da tabela do seu banco de dados SQL do SalesLT.Customer Fabric exibidos no aplicativo React.

Comentários

Esta página foi útil?

Last updated on 2026-01-21