将配置文件环境与数据 API 生成器配合使用

2025-07-17

本指南逐步讲解通过配置文件定位开发环境的步骤。最终结果配置文件应足够灵活，将来只需进行少量更改即可添加生产数据库配置。

先决条件

现有 SQL 数据库。
数据 API 生成器 CLI。安装 CLI

创建 SQL 表和数据

创建包含虚构数据的表，以在此示例方案中使用。

使用首选客户端或工具连接到 SQL Server 和数据库。示例包括但不限于： SQL Server Management Studio 和 Visual Studio Code 的 SQL Server 扩展。

创建包含列id和name列的Books表。

DROP TABLE IF EXISTS dbo.Books;

CREATE TABLE dbo.Books
(
    id int NOT NULL PRIMARY KEY,
    title nvarchar(1000) NOT NULL,
    [year] int null,
    [pages] int null
);
GO

将四个示例书籍行插入Books表中。

INSERT INTO dbo.Books VALUES
    (1000, 'Practical Azure SQL Database for Modern Developers', 2020, 326),
    (1001, 'SQL Server 2019 Revealed: Including Big Data Clusters and Machine Learning', 2019, 444),
    (1002, 'Azure SQL Revealed: A Guide to the Cloud for SQL Server Professionals', 2020, 528),
    (1003, 'SQL Server 2022 Revealed: A Hybrid Data Platform Powered by Security, Performance, and Availability', 2022, 506)
GO

使用简单的 SELECT * 查询测试数据。
```
SELECT * FROM dbo.Books
```

创建基本配置文件

使用 DAB CLI 创建基线配置文件。

使用 dab init.. 创建典型配置文件。

dab init --database-type "mssql" --host-mode "Development"

使用 dab add 添加 Book 实体。

dab add Book --source "dbo.Books" --permissions "anonymous:*"

观察当前的 dab-config.json 配置文件。该文件应包含具有单个实体、REST API 终结点和 GraphQL 终结点的 API 的基线实现。

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "",
    "options": {
      "set-session-context": false
    }
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true
    },
    "host": {
      "cors": {
        "origins": [],
        "allow-credentials": false
      },
      "authentication": {
        "provider": "StaticWebApps"
      },
      "mode": "development"
    }
  },
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.Books",
        "type": "table"
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        }
      },
      "rest": {
        "enabled": true
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

创建环境变量文件

现在，添加一个环境文件来存储 DAB 的环境变量。

在 DAB CLI 配置文件所在的同一目录中创建一个名为 .env 的文件。

注释

.env文件名（例如.gitignore和.editorconfig文件）没有文件名，只有文件扩展名。名称不区分大小写，但惯例为小写。

添加一个值为Development的DAB_ENVIRONMENT环境变量。此外，使用数据库连接字符串添加 SQL_DOCKER_CONNECTION_STRING 环境变量。
```
SQL_DOCKER_CONNECTION_STRING=<connection-string>
DAB_ENVIRONMENT=Development
```

创建环境配置文件

最后，添加一个开发配置文件，其中包含当前配置与目标环境配置之间的差异。

创建 dab-config.Development.json 文件。添加以下内容以使用 @env() 函数在开发环境中设置 connection-string 值。

{
  "$schema": "<https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json>",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_DOCKER_CONNECTION_STRING')"
  }
}

保存对 .env、 dab-config.json和 dab-config.Development.json 文件的更改。

测试设置

用于 dab start 验证工具是否按预期启动。
```
dab start
```
该工具的输出应包含用于导航到正在运行的 API 的地址。
```
      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>
info: Microsoft.Hosting.Lifetime[0]
```
小窍门

在此示例中，应用程序在端口 localhost 上运行。正在运行的应用程序可能有不同的地址和端口。
首先，通过向该 API 发出 GET 请求 /api/Book来手动尝试该 API。

小窍门

在此示例中，URL 为 https://localhost:5000/api/Book. 可以使用 Web 浏览器导航到此 URL。
接下来，导航到 Swagger 文档页面。/swagger

小窍门

在此示例中，URL 为 <https://localhost:5000/swagger. 同样，可以使用 Web 浏览器导航到此 URL。
最后，尝试 GraphQL 终结点，请导航到 /graphql 并运行这个操作。
```
query {
  books(filter: {
    pages: {
      lt: 500
    }
  }) {
    items {
      id
      title
      year
      pages
    }
  }
}
```
小窍门

在此示例中，URL 为 https://localhost:5000/graphql. 同样，可以使用 Web 浏览器导航到此 URL。