你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
Azure Static Web Apps 中的数据库连接配置（预览）
Azure Static Web Apps 数据库连接适用于各种 Azure 数据库。
将数据库连接到静态 Web 应用时，需要配置数据库的防火墙，通过允许来自 Azure 资源的网络访问以接受来自 Static Web Apps 辅助角色的网络访问。 不支持允许特定的 Static Web Apps IP 地址。
如果使用托管标识身份验证类型，则你需要配置静态 Web 应用的托管标识配置文件以访问数据库。
使用此表，详细了解数据库的防火墙和托管标识配置。
| 名称 | 类型 | 防火墙 | 托管标识 |
|---|---|---|---|
| Azure Cosmos DB | Standard | 配置防火墙 | 配置托管标识 |
| Azure SQL | Standard | 配置防火墙 | 配置托管标识 |
| Azure Database for MySQL | Flex | 配置防火墙 | 不支持 |
| Azure Database for PostgreSQL | Flex | 配置防火墙 | 不支持 |
| Azure Database for PostgreSQL（单一） | Single | 配置防火墙 | 配置托管标识 |
配置
在 staticwebapp.database.config.json 文件中定义数据库连接的运行时行为。 将数据库链接到静态 Web 应用之前，需要在存储库中创建此文件。 按照约定，此文件存在于存储库根的 swa-db-connections 文件夹中，但如果你愿意，可将其重新定位。
配置文件的目的是：
- 将
/data-api终结点的路径映射到数据库表或实体 - 公开 REST 或 GraphQL 终结点（或两者）
- 定义实体安全规则
- 控制开发配置设置
如果将 Azure Cosmos DB 与 GraphQL 配合使用，则你还需要提供一个 gql 架构文件。
注意
Static Web Apps 数据库连接需要一个包含配置文件的文件夹。 此文件夹必须包含所有数据库类型的 staticwebapp.database.config.json 配置文件。 对于 Cosmos DB for NoSQL 数据库，还需要一个 staticwebapp.database.schema.gql 架构文件。
按照约定，此文件夹命名为 swa-db-connections，并放置在存储库的根处。 可使用 custom-configuration-folder 替代此约定。
示例配置文件
以下示例配置文件演示如何连接到 Azure SQL 数据库并公开 REST 和 GraphQL 终结点。 有关配置文件及其支持的功能的完整详细信息，请参阅数据 API 生成器文档。
{
"$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
"data-source": {
"database-type": "mssql",
"options": {
"set-session-context": false
},
"connection-string": "@env('DATABASE_CONNECTION_STRING')"
},
"runtime": {
"rest": {
"enabled": true,
"path": "/rest"
},
"graphql": {
"allow-introspection": true,
"enabled": true,
"path": "/graphql"
},
"host": {
"mode": "production",
"cors": {
"origins": ["http://localhost:4280"],
"allow-credentials": false
},
"authentication": {
"provider": "StaticWebApps"
}
}
},
"entities": {
"Person": {
"source": "dbo.MyTestPersonTable",
"permissions": [
{
"actions": ["create", "read", "update", "delete"],
"role": "anonymous"
}
]
}
}
}
| properties | 说明 |
|---|---|
$schema |
Azure Static Web Apps 用于解释配置文件的数据库 API 生成器的版本。 |
data-source |
特定于目标数据库的配置设置。 database-type 属性接受 mssql、postgresql、cosmosdb_nosql 或 mysql。当数据库连接到 Static Web Apps 资源时，在部署时会覆盖连接字符串。 在本地开发期间，配置文件中定义的连接字符串用于连接到数据库。 |
runtime |
定义公开终结点的部分。 rest 和 graphql 属性控制用于访问相应 API 协议的 URL 片段。 host 配置部分定义特定于开发环境的设置。 请确保 origins 数组包含 localhost 地址和端口。 当数据库连接到 Static Web Apps 资源时，host.mode 被覆盖为 production。 |
entities |
将 URL 路径映射到数据库实体和表的部分。 用于保护路径的相同基于角色的身份验证规则也保护数据库实体，并可用于定义每个实体的权限。 实体对象还指定实体之间的关系。 |
生成配置文件
使用 Static Web Apps CLI，可生成配置文件存根。
重要
为了提高通过 Static Web Apps CLI 进行部署的安全性，我们引入了一项中断性变更，要求在 2025 年 1 月 15 日前升级到 Static Web Apps CLI 的最新版本 (2.0.2)。
使用 swa db init --database-type <YOUR_DATABASE_TYPE> 生成配置文件。 默认情况下，CLI 在名为 swa-db-connections 的文件夹中创建一个新的 staticwebapp.database.config.json。
支持的数据库类型包括：
mssqlpostgresqlcosmosdb_nosqlmysql
自定义配置文件夹
staticwebapp.database.config.json 文件的默认文件夹名称为 swa-db-connections。 若要使用不同的文件夹，需要更新工作流文件，以告知 Static Web Apps 运行时在何处查找配置文件。 使用 data_api_location 属性，可定义配置文件夹的位置。
注意
保存 staticwebapp.database.config.json 文件的文件夹必须位于 Static Web Apps 存储库的根处。
以下代码显示如何对数据库配置文件使用名为 db-config 的文件夹。
app_location: "/src"
api_location: "api"
output_location: "/dist"
data_api_location: "db-config" # Folder holding the staticwebapp.database.config.json file
配置数据库连接
Azure Static Web Apps 必须对数据库具有网络访问权限，数据库连接才能正常工作。 此外，若要使用 Azure 数据库进行本地开发，需要配置数据库，以允许来自你自己的 IP 地址的请求。 以下是适用于所有数据库的通用步骤。 有关数据库类型的特定步骤，请参阅上述链接。
- 在 Azure 门户中转到你的数据库。
- 转到“网络”选项卡。
- 在“防火墙规则”部分下，选择“添加客户端 IPv4 地址”。 此步骤可确保可以将此数据库用于本地开发。
- 选中“允许 Azure 服务和资源访问此服务器”复选框。 此步骤可确保部署的 Static Web Apps 资源可以访问数据库。
- 选择“保存”。
连接数据库
在发布到 Azure 时，将数据库链接到静态 Web 应用会在网站和数据库之间建立生产连接。
在 Azure 门户中打开静态 Web 应用。
在“设置”部分中，选择“数据库连接”。
在“生产”部分下，选择“链接现有数据库”链接。
在“链接现有数据库”窗口中，输入以下值：
属性 值 数据库类型 从下拉列表中选择你的数据库类型。 订阅 从下拉列表中选择你的 Azure 订阅。 资源名称 选择具有所需数据库的数据库服务器名称。 数据库名称 选择要链接到静态 Web 应用的数据库的名称。 身份验证类型 选择连接到数据库所需的连接类型。
相关内容
使用以下数据库之一，将数据库添加到静态 Web 应用：
此外，你还可了解如何将数据 API 生成器与 Azure Static Web Apps 配合使用。