次の方法で共有

Data API ビルダーで Azure Key Vault シークレットの置換に @akv() を使用する

データ API ビルダー (DAB) を使用すると、読み込み時にシークレットを置き換えることで、データベース接続文字列などのシークレットをランタイム構成ファイルから保持できます。 もともとこれは環境変数 の @env() 関数 で行われました。 バージョン 1.6 以降、DAB では、 @akv() 関数を通じて Azure Key Vault のサポートが追加されました。

@akv()の機能

Azure Key Vault に格納されているシークレットは、構成 JSON で直接参照できます。

{
  "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 を使用している場合) 文字列 完全なキー・ボールト エンドポイント 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 より大きい値にする必要があります

再試行ポリシー モード

Mode 行動
fixed 試行間の待機時間として一定の delay-seconds が過ぎるのを待ちます。max-count まで
exponential max-delay-secondsまたはmax-countに達するまでの遅延を2倍にします。

ローカル開発: .akv ファイル

Azure Key Vault を使用せずに開発する場合は、 .akv ファイルを使用してシークレットをシミュレートします。 形式は 1 行あたり name=value です。

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

注

開発用のローカル .akv ファイルを指定した場合、そのエントリは、Azure Key Vault へのネットワーク呼び出しを行わずに、 @akv('secret-name') 参照を満たすために使用されます。

ガイドライン：

  • .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

検証：

  • エンドポイントのない Retry-policy フィールドによって検証エラーが発生する
  • 省略可能な再試行パラメーターは正の整数である必要があります

構成での @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
シークレットが見つかりません 名前、ボールト内の存在、および ID アクセス権を確認する
再試行値が無効です 正の整数を使用するか、削除して既定値を使用する
構成の更新が失敗する 検証エラーのログを確認する
@akv() 置き換えられていない エンドポイント、シークレット名、およびシークレット解決が有効になっていることを確認する
Key Vault からの 401/403 ID の割り当てとアクセス許可を確認する

完全な構成例

{
  "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;

Important

シークレットを含むファイル .akv コミットしないでください。 |

クイック リファレンス

Item 概要
構文 @akv('secret-name')
エンドポイントが必要 イエス
シミュレーション ファイル .akvはname=value行を含む
@env() と混合する Supported.

Review

@akv()を使用して、Azure Key Vault からシークレットを解決します。 信頼性のために再試行ポリシーを構成し、 .akv ファイルを使用して開発中のシークレットをシミュレートします。 これにより、一貫した開発および運用ワークフローをサポートしながら、機密性の高い値が構成ファイルから除外されます。

  • Last updated on