Partilhar via

Guia de início rápido: usar o construtor de API de dados com SQL

Neste início rápido, cria endpoints REST e GraphQL para uma base de dados SQL local usando o Data API builder (DAB). Escolha o seu motor de base de dados para começar.

Pré-requisitos

Instalar a CLI do construtor de API de dados

Instala o pacote Microsoft.DataApiBuilder do NuGet como ferramenta .NET.

  1. Use dotnet tool install para instalar a versão mais recente do Microsoft.DataApiBuilder com o --global argumento.

    dotnet tool install --global Microsoft.DataApiBuilder

    Observação

    Se o pacote já estiver instalado, atualize-o usando dotnet tool update.

    dotnet tool update --global Microsoft.DataApiBuilder

  2. Verifique se a ferramenta está instalada com dotnet tool list utilizando o argumento --global.

    dotnet tool list --global

Extrair a imagem da base de dados

Sugestão

Já tem uma base de dados? Avance para Criar e popular a base de dados, execute o script SQL para o seu motor e depois prossiga para Configurar o Data API Builder com a sua própria string de ligação.

Descarregue a imagem Docker para o seu motor de base de dados. Este passo pode demorar alguns minutos, dependendo da velocidade da sua ligação.

docker pull mcr.microsoft.com/mssql/server:2025-latest

Iniciar a base de dados

Executa uma instância de base de dados local no Docker.

docker run --name dab-mssql --env "ACCEPT_EULA=Y" --env "MSSQL_SA_PASSWORD=P@ssw0rd1" --publish 1433:1433 --detach mcr.microsoft.com/mssql/server:2025-latest

Sugestão

Se a porta 1433 já estiver em uso (por exemplo, por uma instalação local do SQL Server), mude --publish para uma porta host diferente, como 1434:1433, e atualize Server=localhost,1433 para Server=localhost,1434 nas etapas seguintes.

Verifique se o motor da base de dados está pronto antes de executar o próximo comando.

docker exec dab-mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "P@ssw0rd1" -C -Q "SELECT 1"

Se isto devolver um erro, espere alguns segundos e tente novamente.

Criar e semear a base de dados

Cria uma base de dados e uma todos tabela, depois adiciona dados de exemplo. Se estiveres a usar Docker, não é necessário nenhum cliente SQL —docker exec executa os comandos diretamente dentro do contentor. Se estiveres a usar a tua própria base de dados, executa o script SQL na tua ferramenta preferida.

  1. Cria a base de dados.

    docker exec dab-mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "P@ssw0rd1" -C -Q "CREATE DATABASE todos;"

  2. Crie a tabela e adicione dados de exemplo.

    docker exec dab-mssql /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "P@ssw0rd1" -C -d todos -Q "CREATE TABLE dbo.todos (id int PRIMARY KEY, title nvarchar(100) NOT NULL, completed bit NOT NULL DEFAULT 0); INSERT INTO dbo.todos VALUES (1, 'Walk the dog', 0), (2, 'Feed the fish', 0), (3, 'Comb the cat', 1);"

Sugestão

Usar o seu próprio SQL Server? Execute este script diretamente:

CREATE DATABASE todos;
GO
USE todos;
GO
CREATE TABLE dbo.todos (id int PRIMARY KEY, title nvarchar(100) NOT NULL, completed bit NOT NULL DEFAULT 0);
INSERT INTO dbo.todos VALUES (1, 'Walk the dog', 0), (2, 'Feed the fish', 0), (3, 'Comb the cat', 1);

Configurar construtor de APIs de Dados

Cria um ficheiro de configuração DAB e adiciona uma entidade Todo .

Sugestão

Usar a tua própria base de dados? Substitua a corda dab init de ligação pela sua própria:

  • SQL Server:Server=<host>,<port>;Database=todos;User Id=<user>;Password=<password>;TrustServerCertificate=true;Encrypt=true;
  • PostgreSQL:Host=<host>;Port=5432;Database=todos;User ID=<user>;Password=<password>;
  • MySQL:Server=<host>;Port=3306;Database=todos;User=<user>;Password=<password>;

  1. Inicialize a configuração.

    dab init --database-type "mssql" --host-mode "Development" --connection-string "Server=localhost,1433;Database=todos;User Id=sa;Password=P@ssw0rd1;TrustServerCertificate=true;Encrypt=true;"

  2. Adiciona a entidade Todo .

    dab add Todo --source "dbo.todos" --permissions "anonymous:*"

O seu dab-config.json ficheiro deverá agora parecer semelhante ao seguinte exemplo:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/vmajor.minor.patch/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=localhost,1433;Database=todos;User Id=sa;Password=P@ssw0rd1;TrustServerCertificate=true;Encrypt=true;"
  },
  "runtime": {
    "rest": {
      "enabled": true
    },
    "graphql": {
      "enabled": true
    },
    "host": {
      "mode": "development",
      "cors": {
        "origins": ["*"]
      }
    }
  },
  "entities": {
    "Todo": {
      "source": "dbo.todos",
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            "*"
          ]
        }
      ]
    }
  }
}

Sugestão

Poderá saltar os comandos dab init e dab add e criar diretamente o ficheiro dab-config.json com o conteúdo aqui mostrado.

Inicie a API

Use dab start para executar a ferramenta e criar endpoints de API para a sua entidade.

dab start

A saída deve incluir o endereço da API em execução.

      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>

Sugestão

Neste exemplo, o aplicativo está sendo executado na localhost porta 5000. Seu aplicativo em execução pode ter um endereço e uma porta diferentes.

Testar a API

  1. Abra o seu navegador e navegue até ao endpoint REST da entidade Todo .

    http://localhost:5000/api/Todo

  2. A resposta JSON deve incluir os três itens de tarefas pendentes.

    {
  "value": [
    { "id": 1, "title": "Walk the dog", "completed": false },
    { "id": 2, "title": "Feed the fish", "completed": false },
    { "id": 3, "title": "Comb the cat", "completed": true }
  ]
}

  3. Navegue até à página de documentação do Swagger em /swagger.

    http://localhost:5000/swagger

Criar um aplicativo Web

Mostre as suas tarefas num navegador usando um ficheiro HTML simples. Crie um ficheiro nomeado todo.html usando o endpoint REST ou GraphQL.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Todo App</title>
  <style>
    body { font-family: sans-serif; max-width: 400px; margin: 2rem auto; }
    li.done { text-decoration: line-through; color: gray; }
    #error { color: red; }
  </style>
</head>
<body>
  <h1>Todos</h1>
  <ul id="list"></ul>
  <p id="error"></p>
  <script>
    fetch('http://localhost:5000/api/Todo')
      .then(r => r.json())
      .then(data => {
        const ul = document.getElementById('list');
        data.value.forEach(todo => {
          const li = document.createElement('li');
          li.textContent = todo.title;
          if (todo.completed) li.className = 'done';
          ul.appendChild(li);
        });
      })
      .catch(() => {
        document.getElementById('error').textContent =
          'Could not reach the API. Make sure DAB is running on http://localhost:5000.';
      });
  </script>
</body>
</html>

Abra todo.html no seu navegador. A página recolhe todos os itens de tarefas pendentes e exibe-os como uma lista, com os itens concluídos mostrados em riscado.

Importante

A cors definição na sua configuração permite que este ficheiro HTML — aberto no seu sistema de ficheiros local — chame a API. Sem isso, o navegador bloqueia o pedido.

Limpeza

Pare e remova o contentor Docker quando terminar.

docker stop dab-mssql && docker rm dab-mssql

Próximo passo

pontos finais REST

  • Last updated on