共用方式為

在資料 API 生成器中使用 @akv() 進行 Azure Key Vault 機密替換

Data API 產生器（DAB）允許您在載入時取代敏感資訊，例如資料庫連接字串，從而將這些資訊從執行階段的設定檔中隔離開。 最初，這是使用函數來操控環境變數完成的。 從 1.6 版開始，DAB 會透過函 @akv() 式新增 Azure 金鑰保存庫的支援。

什麼@akv()做

您可以直接在組態 JSON 中參考儲存在 Azure 金鑰保存庫中的秘密：

{
  "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 否 物件 覆寫呼叫金鑰保存庫時的重試行為

重試策略物件

領域 預設 註釋
mode exponential 允許的值： fixed 或 exponential
max-count 3 必須大於 0
delay-seconds 1 必須大於 0
max-delay-seconds 60 必須大於 0，指數退避的上限
network-timeout-seconds 60 必須大於 0

重試原則模式

Mode 行為
fixed 在嘗試之間等待常數 delay-seconds ，直到 max-count
exponential 將延遲加倍，直到達到 max-delay-seconds 或 max-count

本地開發：.akv 文件

針對沒有 Azure 金鑰保存庫的開發，請使用 .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 金鑰保存庫設定

您可以使用 CLI 來設定金鑰保存庫設定：

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" ] }
      ]
    }
  }
}

故障排除

癥狀 Steps
找不到機密 驗證名稱、保存庫中的存在性，以及身分權限
重試值無效 使用正整數或移除以使用預設值
設定更新失敗 檢查記錄是否有驗證錯誤
@akv() 未更換 確認端點、機密名稱，以及已啟用機密解析功能
來自 Key Vault 的 HTTP 狀態碼 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 包含秘密的檔案。 |

快速參考

項目 總結
語法 @akv('secret-name')
必須提供端點 Yes
模擬檔案 .akv帶有name=value線條
混合 @env() 支援。

Review

用 @akv() 來解析 Azure 金鑰保存庫的秘密。 設定重試策略以確保可靠性，並使用.akv 檔案在開發中模擬秘密資料。 這可將敏感值排除在組態檔之外，同時支援一致的開發和生產工作流程。

  • Last updated on