Data API builder (pré-visualização)

A extensão MSSQL para Visual Studio Code inclui uma interface integrada para o Data API Builder, permitindo criar endpoints REST, GraphQL e MCP para as suas tabelas de base de dados SQL sem escrever ficheiros de configuração ou sair do Visual Studio Code. Pode selecionar quais as tabelas a expor, configurar permissões CRUD, escolher tipos de API, pré-visualizar a configuração gerada e implementar um backend local alimentado pelo Data API Builder, tudo a partir de uma interface visual.

Sugestão

O Data API Builder está atualmente em pré-visualização e pode mudar com base no feedback. Junte-se à comunidade no GitHub Discussions para partilhar ideias ou reportar problemas.

Importante

Esta funcionalidade tem limitações conhecidas, incluindo suporte apenas para autenticação SQL para implementação de contentores e compatibilidade restrita com tipos de dados. Revise as limitações conhecidas e os problemas conhecidos antes de implementar.

Características

A integração do Data API builder oferece as seguintes capacidades:

Selecione entidades de base de dados (tabelas) para expor como endpoints API, organizados por esquema com agrupamento colapsável.
Configure permissões de Crear, Ler, Atualizar e Eliminar (CRUD) de forma independente para cada empresa.
Escolha tipos de API para gerar: REST, GraphQL, MCP ou qualquer combinação.
Configure definições avançadas de entidades, incluindo caminhos REST personalizados, nomes de tipos GraphQL personalizados e papéis de autorização.
Pré-visualize a configuração JSON gerada do Data API builder num painel de Definição apenas de leitura.
Implemente o Data API Builder localmente como um contentor Docker com verificações automáticas de pré-requisitos.
Teste a execução de APIs diretamente no Visual Studio Code usando o Simple Browser integrado.
Usa o chat do GitHub Copilot para configurar entidades através de prompts em linguagem natural.

Pré-requisitos

Antes de usar o Data API Builder, certifique-se de que os seguintes requisitos são cumpridos:

A extensão MSSQL para Visual Studio Code está instalada. Para as etapas de instalação, consulte a visão geral da extensão MSSQL para Visual Studio Code.
Uma ligação ativa à base de dados é estabelecida através da extensão MSSQL. Para os passos de ligação, veja Quickstart: Conectar-se e consultar uma base de dados com a extensão MSSQL para Visual Studio Code.
O Docker Desktop está instalado e a correr na sua máquina (necessário para implementação local).
(Opcional) As extensões GitHub Copilot e GitHub Copilot Chat estão instaladas para configuração de entidades assistidas por IA.

Construtor de APIs de Dados Abertos

Pode abrir a vista de configuração do Data API builder a partir de dois pontos de entrada:

No Object Explorer: Clique com o botão direito num nó da base de dados e selecione Construir API de Dados (Pré-visualização)....
Do Designer de Esquemas: Selecione o botão Design API (botão no canto superior direito da barra de ferramentas), ou selecione o ícone Backend no painel esquerdo.

A vista de configuração do Data API builder abre-se, mostrando as entidades da sua base de dados, opções de tipo de API e controlos de configuração.

Selecionar entidades

A vista de seleção de entidades lista todas as tabelas da sua base de dados conectada, agrupadas por esquema.

Cada linha de esquema é dobrável e mostra um emblema de contagem indicando quantas entidades estão ativadas (por exemplo, "3/5").
Seleciona uma caixa de seleção ao nível do esquema para alternar todas as entidades nesse esquema. A caixa de seleção suporta a seleção de três estados: todos, nenhum ou misto.
Cada linha de entidade apresenta: a caixa de seleção de ativação, o nome da entidade, a tabela de origem, as caixas de seleção CRUD e um botão de configurações.
Desativar uma entidade faz a sua linha cinzentar e desativa as caixas de seleção CRUD e o botão de definições.

Use a caixa de filtro no topo para pesquisar entidades por nome, esquema ou tabela de origem. O filtro é insensível a maiúsculas minúsculas, e a contagem ativada atualiza-se com base nos resultados filtrados.

Configurar permissões e tipos de API

Permissões CRUD

Alterne as caixas de seleção individuais de Criar, Ler, Atualizar e Eliminar para cada entidade. Ao nível do cabeçalho, as caixas de seleção CRUD permitem alternar essa ação para todas as entidades ativadas e suportam a seleção de três estados.

Seleção de tipos de API

No topo da vista de configuração, selecione os tipos de API a gerar:

API REST: Gera endpoints REST com interface Swagger para testes.
GraphQL: Gera endpoints GraphQL com o playground Nitro GraphQL.
MCP (Prévia): Gera endpoints do Protocolo de Contexto do Modelo.
Todos: Seleciona ou desseleciona todos os tipos de API.

Selecione pelo menos um tipo de API.

Configuração avançada de entidades

Selecione o ícone de engrenagem numa linha de entidade para abrir o diálogo de Configuração Avançada da Entidade , onde pode configurar:

Nome da Entidade: O nome usado nas rotas e respostas da API (por padrão, é o nome da tabela).
Papel de Autorização: Alternar entre Anónimo (sem necessidade de autenticação) e Autenticado (requer autenticação do utilizador).
Caminho REST Personalizado: Substituição opcional para o caminho predefinido api/entityName.
Tipo GraphQL Personalizado: Substituição opcional para o nome de tipo GraphQL padrão.

Selecione Aplicar Alterações para guardar a sua configuração, ou Cancelar para descartar.

Configuração de pré-visualização

Selecione o botão Ver Configuração na barra de ferramentas para abrir o painel de Definição na parte inferior da vista de configuração. Este painel mostra o ficheiro de configuração JSON do Data API builder gerado em formato apenas de leitura.

O painel de Definição:

Reflete a seleção atual de entidades, tipos de API e definições avançadas.
Mantém-se sincronizado com a interface e o chat do GitHub Copilot: as alterações feitas em qualquer um dos locais atualizam imediatamente a pré-visualização.
Inclui apenas entidades ativadas na saída de configuração.
Mostra secções de runtime REST, GraphQL e MCP baseadas em tipos de API selecionados.

Selecione Abrir no Editor para visualizar a configuração num separador completo do editor Visual Studio Code. Selecione Copiar para copiar a configuração para a prancheta.

Implementar localmente com Docker

O Data API Builder é implementado como um contentor Docker local. O assistente de implementação guia-o pelo processo:

Selecione o botão Deploy na barra de ferramentas.
Abre-se o diálogo Deploy DAB Container , descrevendo a implementação local do contenteur. Selecione Avançar.
O ecrã Getting Docker Ready executa verificações pré-requisitos sequencialmente:
- Verificação da instalação do Docker: Verifica que o Docker está instalado no seu sistema.
- Iniciar o Docker Desktop: Garante que o Docker Desktop está a funcionar.
- Verificação do motor Docker: Verifica se o motor Docker está pronto.
Selecione Next para prosseguir assim que todas as verificações estiverem concluídas.
O ecrã de Definições do Contentor aparece:
- Nome do Contentor: Nome opcional para o contentor Docker (é fornecido um padrão gerado automaticamente).
- Porta: A porta na qual expor a API (padrão: 5000).
- O contentor reutiliza a cadeia de ligação da base de dados ativa.
Selecione Criar contêiner.
A implementação executa três passos sequenciais: extrair imagem, iniciar o contentor e verificar a prontidão.

Após a implementação bem-sucedida, o assistente mostra os URLs dos endpoints para cada tipo de API ativado:

Tipo de API	Ponto final	Action
REST	`http://localhost:{port}/api`	Ver Swagger abre a interface Swagger
GraphQL	`http://localhost:{port}/graphql`	Nitro abre o parque de diversões do GraphQL
MCP	`http://localhost:{port}/mcp`	Add to VS Code escreve a configuração do servidor MCP para `.vscode/mcp.json`

Selecione qualquer link para abrir a interface de teste no Navegador Simples integrado no Visual Studio Code.

O exemplo seguinte mostra a interface Swagger para testar endpoints REST diretamente no Visual Studio Code:

O exemplo seguinte mostra o playground do Nitro GraphQL para testar consultas e mutações do GraphQL:

Teste a API em execução

Após a implementação, pode testar as suas APIs diretamente a partir do diálogo de conclusão de implementação usando o Simple Browser integrado no Visual Studio Code.

API REST

Selecione Ver Swagger para abrir a interface Swagger, uma interface visual interativa para explorar e testar endpoints REST. Pode navegar pelas entidades disponíveis, visualizar esquemas de pedido e resposta, e executar chamadas API diretamente.

O Data API Builder gera os seguintes endpoints REST para cada entidade habilitada:

Método	Ponto final	Descrição
`GET`	`/api/{entity}`	Liste todos os registos de uma entidade
`GET`	`/api/{entity}/{primaryKey}/{value}`	Obtenha um único registo utilizando a chave primária
`POST`	`/api/{entity}`	Criar um novo registo
`PUT`	`/api/{entity}/{primaryKey}/{value}`	Substituir um registo existente
`PATCH`	`/api/{entity}/{primaryKey}/{value}`	Atualizar campos específicos de um registo
`DELETE`	`/api/{entity}/{primaryKey}/{value}`	Eliminar um registo

Para mais informações sobre endpoints REST, consulte Data API builder REST API.

GraphQL

Selecione Nitro para abrir o playground Nitro GraphQL, onde pode escrever e testar consultas e mutações GraphQL de forma interativa.

Para mais informações sobre endpoints GraphQL, consulte o Data API builder GraphQL API.

MCP

Selecione Adicionar ao VS Code para escrever a configuração do servidor MCP em .vscode/mcp.json. Esta configuração disponibiliza o endpoint Data API builder como servidor MCP dentro do Visual Studio Code. Ferramentas de IA como o GitHub Copilot podem então interagir com a sua base de dados através da API Data API builder.

Para mais informações sobre MCP no Visual Studio Code, consulte Usar servidores MCP no Visual Studio Code.

Testes de terminais

Também pode testar endpoints a partir do terminal:

API REST:

Obtenha todos os registos de uma entidade específica:

curl http://localhost:{port}/api/{entityName}

Criar um novo registo (se a permissão de criação estiver ativada):

curl -X POST http://localhost:{port}/api/{entityName} \
  -H "Content-Type: application/json" \
  -d '{"Column1": "Value1", "Column2": "Value2"}'

GraphQL:

curl -X POST http://localhost:{port}/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ {entityName} { items { Column1 Column2 } } }"}'

Sugestão

Substitua {port} pela porta que configurou durante a implementação (por defeito: 5000).

Integração com o GitHub Copilot

Para programadores que preferem linguagem natural, o GitHub Copilot está integrado na experiência do Data API builder. Selecione o botão Chat na barra de ferramentas para abrir uma sessão de chat do GitHub Copilot com âmbito no contexto de configuração do Data API builder. O GitHub Copilot e a interface mantêm-se sincronizados: as alterações feitas através do chat refletem-se imediatamente na interface e vice-versa.

Aqui estão alguns exemplos de prompts:

"Enable all SalesLT entities for read operations"
"Expose only the Customer and Product tables with full CRUD permissions"
"Set all entities in the dbo schema to read-only"
"Disable the BuildVersion and ErrorLog entities"
"Can you also enable MCP for the Data API builder API?"

O exemplo seguinte mostra o GitHub Copilot a ativar entidades e a configurar permissões CRUD através de um aviso de chat:

O exemplo seguinte mostra o GitHub Copilot a ativar endpoints MCP para a configuração do Data API builder:

Observação

A integração do GitHub Copilot requer que as extensões GitHub Copilot e GitHub Copilot Chat estejam instaladas e conectadas. Para instruções de configuração, consulte Configurar o GitHub Copilot.

Limitações conhecidas

Apenas tabelas: A interface de configuração suporta apenas tabelas. Vistas e procedimentos armazenados não estão disponíveis no designer neste momento.
Docker Desktop necessário: A implementação local requer que o Docker Desktop esteja instalado e a funcionar.
Apenas autenticação SQL: Os contentores locais Docker não suportam métodos de autenticação Microsoft Entra ID, como ActiveDirectoryInteractive, porque o ambiente do contentor não consegue abrir um navegador para o fluxo interativo de início de sessão. A extensão mostra uma notificação se a sua ligação atual usar um tipo de autenticação não suportado.
A base de dados SQL no Microsoft Fabric não é suportada: a base de dados SQL no Microsoft Fabric requer exclusivamente autenticação Microsoft Entra e não suporta autenticação SQL. Como a implementação local de contentores requer autenticação SQL, implementar em base de dados SQL no Fabric não é um cenário viável.
Chave primária necessária: Cada entidade de tabela exposta através do Data API Builder deve ter uma restrição de chave primária definida ao nível da base de dados. Tabelas sem uma chave primária fazem com que o motor Data API builder falhe no arranque.
A saída gerada por IA deve ser revista: o GitHub Copilot pode produzir configurações incorretas ou subótimas. Revise sempre as configurações geradas antes de implementar.

Problemas conhecidos

Tipos de dados SQL Server não suportados: O Data API Builder não consegue serializar certos tipos de dados SQL Server. Tabelas contendo colunas com tipos não suportados podem causar falhas no motor no arranque. Tipos não suportados incluem geography, geometry, hierarchyid, rowversion, sql_variant, e xml. A extensão marca as entidades afetadas com um ícone de aviso e impede que sejam selecionadas para implementação. Para as informações mais recentes sobre suporte a tipos de dados, consulte a edição #3181 do GitHub.
Autenticação interativa Microsoft Entra ID não suportada para implementação de contentores: O contentor Data API builder não consegue realizar autenticação interativa Microsoft Entra. As ligações que utilizam métodos interativos Microsoft Entra ID são bloqueadas com uma notificação. Para mais informações, consulte a edição #3246 do GitHub.
O MCP está em pré-visualização: A experiência do Data API builder no MCP está atualmente em pré-visualização. Para mais informações, consulte Data API builder MCP Preview.

Comentários e suporte

Se você tiver ideias, comentários ou quiser se envolver com a comunidade, participe da discussão em https://aka.ms/vscode-mssql-discussions. Para reportar um bug, visite https://aka.ms/vscode-mssql-bug. Para solicitar um novo recurso, vá para https://aka.ms/vscode-mssql-feature-request.

Comentários

Esta página foi útil?

Last updated on 2026-03-18