Condividi tramite

Guida introduttiva: Usare il Costruttore API dati con SQL

In questa guida introduttiva vengono creati endpoint REST e GraphQL per un database SQL locale usando il generatore di API dati (DAB). Scegliere il motore di database per iniziare.

Prerequisiti

Installare il CLI di Data API Builder

Installare il pacchetto Microsoft.DataApiBuilder da NuGet come strumento di .NET.

  1. Usa dotnet tool install per installare la versione più recente di Microsoft.DataApiBuilder con l'argomento --global.

    dotnet tool install --global Microsoft.DataApiBuilder

    Annotazioni

    Se il pacchetto è già installato, aggiornare invece il pacchetto usando dotnet tool update.

    dotnet tool update --global Microsoft.DataApiBuilder

  2. Verifica che lo strumento sia installato usando dotnet tool list con l'argomento --global.

    dotnet tool list --global

Scaricare l'immagine del database

Suggerimento

Si dispone già di un database? Passare a Creare ed eseguire il seeding del database, eseguire lo script SQL per il motore e quindi passare a Configurare il generatore di API dati con la propria stringa di connessione.

Scaricare l'immagine Docker per il motore di database. Questo passaggio può richiedere alcuni minuti a seconda della velocità di connessione.

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

Avviare il database

Eseguire un'istanza locale del database in 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

Suggerimento

Se la porta 1433 è già in uso (ad esempio, da un'installazione locale di SQL Server), passare --publish a una porta host diversa come 1434:1433 e aggiornare Server=localhost,1433 in Server=localhost,1434 nei passaggi successivi.

Verificare che il motore di database sia pronto prima di eseguire il comando successivo.

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

Se viene restituito un errore, attendere alcuni secondi e riprovare.

Creare ed eseguire il seeding del database

Creare un database e una todos tabella, quindi aggiungere dati di esempio. Se si usa Docker, non è necessario alcun client SQL.docker exec Esegue i comandi direttamente all'interno del contenitore. Se si usa il proprio database, eseguire lo script SQL nello strumento preferito.

  1. Creare il database.

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

  2. Creare la tabella e aggiungere dati di esempio.

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

Suggerimento

Uso di SQL Server personale? Eseguire direttamente questo script:

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

Configurare il generatore di API dati

Creare un file di configurazione DAB e aggiungere un'entità Todo .

Suggerimento

Utilizzo del proprio database? Sostituire la stringa di connessione in dab init con la propria:

  • 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. Inizializzare la configurazione.

    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. Aggiungere l'entità Todo .

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

Il dab-config.json file dovrebbe ora essere simile all'esempio seguente:

{
  "$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": [
            "*"
          ]
        }
      ]
    }
  }
}

Suggerimento

È possibile ignorare i dab init comandi e dab add e creare il dab-config.json file direttamente con il contenuto illustrato qui.

Avviare l'API

Usare dab start per eseguire lo strumento e creare endpoint API per l'entità.

dab start

L'output deve includere l'indirizzo dell'API in esecuzione.

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

Suggerimento

In questo esempio l'applicazione viene eseguita sulla localhost porta 5000. L'applicazione in esecuzione può avere un indirizzo e una porta diversi.

Testare l'API

  1. Aprire il browser e passare all'endpoint REST per l'entità Todo .

    http://localhost:5000/api/Todo

  2. La risposta JSON deve includere tutti e tre gli elementi todo.

    {
  "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. Passare alla pagina della documentazione di Swagger all'indirizzo /swagger.

    http://localhost:5000/swagger

Creare un'app Web

Visualizzare attività in un browser usando un normale file HTML. Creare un file denominato todo.html usando l'endpoint REST o 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>

Aprire todo.html nel browser. La pagina recupera tutte le attività da fare e viene eseguito il rendering come elenco, con gli elementi completati visualizzati in formato barrato.

Importante

L'impostazione cors nella configurazione consente a questo file HTML, aperto dal file system locale, di chiamare l'API. Senza di esso, il browser blocca la richiesta.

Pulizia

Ferma e rimuovi il container Docker al termine.

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

Passo successivo

endpoint REST

  • Last updated on