使用 @akv() 在 Data API 生成器中替换 Azure Key Vault 的机密

2025-09-27

数据 API 构建器（DAB）可以让您在加载时替换机密，例如数据库连接字符串，从而避免在运行时配置文件中直接存储这些机密。最初，这是使用@env()环境变量的函数完成的。从版本 1.6 开始，DAB 通过 @akv() 函数添加了对 Azure Key Vault 的支持。

什么是@akv()的功能

可以直接在配置 JSON 中引用存储在 Azure Key Vault 中的机密：

{
  "data-source": {
    "connection-string": "@akv('my-connection-secret')"
  }
}

在配置加载时，DAB 会解析占位符并用机密值替换它，类似于 @env('VAR_NAME') 的工作方式。如果无法检索机密，配置加载将失败。错误包括缺少机密或授权失败。

配置结构

在配置的根级别添加 azure-key-vault 部分。

{
  "azure-key-vault": {
    "endpoint": "https://my-vault-name.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  }
}

属性

资产	必选	类型	Description
`endpoint`	如果使用 Key Vault，则为“是”	字符串	完整的 Key Vault 端点 URL
`retry-policy`	否	对象	调用 Key Vault 时覆盖重试行为

重试策略对象

领域	违约	注释
`mode`	`exponential`	允许的值： `fixed` 或 `exponential`
`max-count`	3	必须大于 0
`delay-seconds`	1	必须大于 0
`max-delay-seconds`	60	必须大于 0，指数退避的最大值
`network-timeout-seconds`	60	必须大于 0

重试策略模式

模式	行为
`fixed`	在各次尝试之间一直等待常量时间 `delay-seconds`，直到 `max-count`
`exponential`	将延迟加倍，直到到达 `max-delay-seconds` 或 `max-count`

本地开发：.akv 文件

对于没有 Azure Key Vault 的开发，请使用 .akv 文件来模拟机密。每行的格式为name=value：

my-connection-secret=Server=.;Database=AppDb;User Id=app;Password=local-dev;
api-key=dev-api-key-123

注释

如果提供用于开发的本地 .akv 文件，则其条目用于满足 @akv(“secret-name”查找，而无需对 Azure Key Vault 进行网络调用。

指引：

避免将 .akv 放入源代码管理
机密名称必须与在 @akv('name') 中使用的名称匹配

使用 CLI 添加 Azure Key Vault 设置

可以使用 CLI 配置 Key Vault 设置：

dab configure \
  --azure-key-vault.endpoint "https://my-vault.vault.azure.net/" \
  --azure-key-vault.retry-policy.mode exponential \
  --azure-key-vault.retry-policy.max-count 5 \
  --azure-key-vault.retry-policy.delay-seconds 2 \
  --azure-key-vault.retry-policy.max-delay-seconds 30 \
  --azure-key-vault.retry-policy.network-timeout-seconds 45 \
  --config dab-config.json

验证：

没有终结点的重试策略字段会导致验证失败
可选重试参数必须是正整数

在 @akv() 配置中使用

基本替换

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  }
}

混合与 @env()

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@akv('sql-connection')"
  },
  "runtime": {
    "rest": { "enabled": true }
  }
}

注释

启动时，@env() 替换发生在 @akv() 替换之前。

存储过程参数

{
  "entities": {
    "RunJob": {
      "source": {
        "object": "dbo.RunJob",
        "type": "stored-procedure",
        "parameters": {
          "apiKey": "@akv('job-runner-apikey')"
        }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ "execute" ] }
      ]
    }
  }
}

Troubleshooting

症状	Steps
找不到机密	验证保管库中的名称、存在以及标识权限
无效的重试值	使用正整数或删除以使用默认值
配置更新失败	检查日志中是否存在验证错误
`@akv()` 未替换	确认终结点、机密名称，并确保已启用机密解析功能。
Key Vault 返回 401/403 状态码	检查身份分配和权限

完整示例配置

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  },
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  },
  "runtime": {
    "rest": { "enabled": true }
  },
  "entities": {
    "Books": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

示例 `.akv` 文件：

primary-sql-connection=Server=localhost;Database=BooksDb;User Id=app;Password=password;

重要

不要提交 .akv 包含机密的文件。 |

快速参考

Item	概要
Syntax	`@akv('secret-name')`
所需的终结点	是的
模拟文件	`.akv` 带有 `name=value` 行
混合 `@env()`	支持.

Review

使用 @akv() 解析 Azure Key Vault 中的机密。为可靠性配置重试策略，并使用 .akv 文件来模拟开发中的机密。这会将敏感值移出配置文件，同时支持一致的开发和生产工作流。

反馈

此页面是否有帮助？