创建第一个数据 API

安装好 dab 工具后，下一步就是创建配置文件并将数据库表发布为 API。整个过程只需要两条命令。

开始之前，请确保你有一个可访问的数据库，并且已经知道它的连接字符串。

初始化配置文件

dab init 会创建一份基础的配置文件，指定数据库类型和连接信息：

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

参数说明

参数	说明
--database-type	数据库类型，可选 mssql、postgresql、mysql
--connection-string	数据库连接字符串，支持 @env() 引用环境变量
--host-mode	运行模式，开发环境设为 Development（启用 Swagger、详细错误信息等），生产环境应设为 Production

运行后，当前目录会生成 dab-config.json，包含数据源定义和默认的运行时设置。

TIP

三种数据库的完整初始化命令：

SQL Server：

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

PostgreSQL：

dab init --database-type "postgresql" --host-mode "Development" --connection-string "Host=localhost;Port=5432;Database=todos;User ID=postgres;Password=P@ssw0rd1;"

MySQL：

dab init --database-type "mysql" --host-mode "Development" --connection-string "Server=localhost;Port=3306;Database=todos;User=root;Password=P@ssw0rd1;"

TIP

不同数据库的连接字符串格式：

SQL Server：

Server=<host>,<port>;Database=<db>;User Id=<user>;Password=<pwd>;TrustServerCertificate=true;

PostgreSQL：

Host=<host>;Port=5432;Database=<db>;User ID=<user>;Password=<pwd>;

MySQL：

Server=<host>;Port=3306;Database=<db>;User=<user>;Password=<pwd>;

添加实体

dab add 将数据库对象注册为 API 实体。以下命令将 dbo.todos 表添加为 Todo 实体，并允许匿名用户执行所有操作：

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

参数说明

参数	说明
Todo	实体名称，也是 API 路径（/api/Todo）和 GraphQL 类型名
--source	数据库对象的名称。表为 schema.name，视图同理，存储过程为完整路径
--source.type	可选，对象类型：table（默认）、view、stored-procedure
--permissions	角色与权限，格式为 "角色名:操作"。* 代表该类型支持的全部操作

NOTE

不同数据库的 --source 写法略有差异：

• SQL Server：dbo.tablename（schema 通常为 dbo）
• PostgreSQL：public.tablename（schema 通常为 public）
• MySQL：直接写表名，不需要 schema 前缀

三种数据库的完整添加实体命令：

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

# PostgreSQL
dab add Todo --source "public.todos" --permissions "anonymous:*"

# MySQL
dab add Todo --source "todos" --permissions "anonymous:*"

可以多次运行 dab add，为每个需要暴露的表或视图添加实体。

查看配置文件

执行完以上两步后，dab-config.json 的内容大致如下：

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

你也可以直接手工编写配置文件——不一定要用 CLI 命令。只要能生成符合规范的 JSON，dab start 都能正常运行。

TIP

三种数据库的配置示例：

PostgreSQL：

{
  "data-source": {
    "database-type": "postgresql",
    "connection-string": "Host=localhost;Port=5432;Database=todos;User ID=postgres;Password=P@ssw0rd1;"
  },
  "runtime": {
    "rest": { "enabled": true },
    "graphql": { "enabled": true },
    "host": {
      "mode": "development",
      "cors": { "origins": ["*"] }
    }
  },
  "entities": {
    "Todo": {
      "source": "public.todos",
      "permissions": [{ "role": "anonymous", "actions": ["*"] }]
    }
  }
}

MySQL：

{
  "data-source": {
    "database-type": "mysql",
    "connection-string": "Server=localhost;Port=3306;Database=todos;User=root;Password=P@ssw0rd1;"
  },
  "runtime": {
    "rest": { "enabled": true },
    "graphql": { "enabled": true },
    "host": {
      "mode": "development",
      "cors": { "origins": ["*"] }
    }
  },
  "entities": {
    "Todo": {
      "source": "todos",
      "permissions": [{ "role": "anonymous", "actions": ["*"] }]
    }
  }
}

NOTE

配置中的 cors 设置允许跨域请求。如果前端应用和 API 不在同一域名下（例如从 file:// 或 localhost:3000 调用），必须配置 CORS，否则浏览器会阻止请求。

同时支持 REST 和 GraphQL

默认配置同时启用了 REST 和 GraphQL。同一个 Todo 实体会在两个协议中自动生成接口：

• REST 端点：GET /api/Todo
• GraphQL 查询：{ todos { items { id title completed } } }

你也可以通过配置文件或 dab configure（用于修改已有实体配置）按需关闭某一协议。

下一步

配置文件就绪后，继续阅读启动并验证服务，运行 dab start 并测试你的第一个数据 API。