你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Azure Static Web Apps 连接到数据库（预览版）

项目
05/27/2024

借助 Azure Static Web Apps 数据库连接功能，无需编写自定义服务器端代码即可从静态 Web 应用访问数据库。

在 Web 应用程序和数据库之间创建连接后，可以在完全支持 CRUD 操作、内置授权和关系的情况下操作数据。

Azure Static Web Apps 根据数据 API 生成器获取 REST 和 GraphQL 请求，并将其转换为数据库查询。

数据库连接支持的功能包括：

Feature	说明
集成安全性	与 Azure Static Web Apps 身份验证和授权安全模型的内置集成。用于保护路由的基于角色的安全性可用于 API 终结点。
基于 CRUD 的完整操作	有关如何操作应用程序中数据的示例，请参阅 Azure Cosmos DB、Azure SQL、MySQL 或 PostgreSQL 教程。
支持 SQL 和 NoSQL	可以使用关系数据库和文档数据库作为应用程序的数据库。
无服务器体系结构	连接从 0 个辅助角色缩放到 1 个辅助角色（在预览期间）。
数据库关系	仅通过 GraphQL 终结点支持。
CLI 支持	使用 Static Web Apps CLI 在本地进行开发。使用 `--data-api-location` 选项可以像在云中处理一样在开发中处理对数据 API 的请求。

支持的数据库

下表显示了对不同关系数据库和 NoSQL 数据库的支持。

名称	Type	描述	REST	GraphQL
Azure Cosmos DB	Standard	全局分布式数据库平台，适用于任何规模的 NoSQL 和关系数据库。除了标准配置，GraphQL 终结点还需要 `gql` 架构文件。		✔
Azure SQL	Standard	一系列智能安全的托管产品，它们使用 Azure 云中的 SQL Server 数据库引擎。	✔	✔
Azure Database for MySQL	Flex	Microsoft 云中基于 MySQL 社区版的关系数据库服务	✔	✔
Azure Database for PostgreSQL	Flex	完全托管的 PostgreSQL 数据库即服务，可处理任务关键型工作负载，并提供可预测的性能和动态可伸缩性。	✔	✔
Azure Database for PostgreSQL（单一）	Single	完全托管的 PostgreSQL 数据库。	✔	✔

可使用以下连接类型进行数据库访问：

连接字符串
用户分配的托管标识
系统分配的托管标识

终结点位置

可以在 /data-api 路径之外访问数据终结点。

下表显示了请求如何路由到静态 Web 应用的不同部分：

路径	说明
`example.com/api/*`	API 函数
`example.com/data-api/*`	支持 REST 和 GraphQL 请求的数据库连接终结点。
`example.com/*`	静态内容

在网站上配置数据库连接时，可以配置 /data-api/* 路由的 REST 或 GraphQL 后缀。 /data-api 前缀是 Static Web Apps 的约定，无法更改。

配置

通过两个步骤在 Static Web Apps 中配置数据库连接。需要在 Azure 门户中将数据库连接到静态 Web 应用，并更新数据库连接配置文件。

有关更多详细信息，请参阅 Azure Static Web Apps 中的数据库连接配置。

本地开发

Azure Static Web Apps CLI (SWA CLI) 包括支持在本地开发期间使用数据库连接。

CLI 将激活本地 /data-api 终结点，并通过代理将来自 4280 端口的请求发送到适当的端口进行数据库访问。

下面是使用数据库连接启动 SWA CLI 的示例命令：

swa start ./src --data-api-location swa-db-connections

此命令在 src 目录中启动 SWA CLI。 --data-api-location 选项告知 CLI 名为 swa-db-connections 的文件夹保存 staticwebapp.database.config.json 文件。

注意

在开发中，如果使用连接字符串进行身份验证，请使用 env() 函数从环境变量读取连接字符串。传入 env 函数的字符串必须用引号括起来。

基于角色的安全性

在 staticwebapp.database.config.json 文件中定义实体时，可以指定访问实体终结点所需的角色列表。

以下配置片段要求具有管理员角色才能访问 orders 实体上的所有操作（create、read、update、delete）。

{
...
"entities": { 
  "Orders": { 
    "source": "dbo.Orders", 
    "permissions": [ 
      { 
        "actions": ["*"], 
        "role": "admin" 
      }
    ]
 }
}
...
}

对需要角色的终结点进行调用时，需要满足以下条件：

当前用户必须进行身份验证。
当前用户必须是所需角色的成员。
REST 或 GraphQL 请求必须包含具有 X-MS-API-ROLE 键的标头，还必须包含与实体配置规则中所列内容匹配的角色名称的值。

例如，以下片段演示如何在请求头中传递管理员角色。
```
{
  method: "POST",
  headers: { 
    "Content-Type": "application/json",
    "X-MS-API-ROLE": "admin"
  },
  body: JSON.stringify(requestPayload)
}
```

约束

数据库必须可由 Azure 的基础结构访问。
在公共预览版期间，数据库连接从 0 个数据库辅助角色缩放到 1 个数据库辅助角色。

后续步骤

配置数据库

通过