Bagikan melalui

Gunakan @akv() untuk penggantian rahasia Azure Key Vault di penyusun API Data

Penyusun API Data (DAB) memungkinkan Anda menyimpan rahasia, seperti string koneksi database, dari file konfigurasi runtime dengan menggantinya pada waktu pemuatan. Awalnya ini dilakukan dengan @env() fungsi untuk variabel lingkungan. Dimulai dengan versi 1.6, DAB menambahkan dukungan untuk Azure Key Vault melalui @akv() fungsi .

Apa yang @akv() dilakukan

Anda dapat mereferensikan rahasia yang disimpan di Azure Key Vault langsung dalam konfigurasi JSON:

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

Pada saat pemuatan konfigurasi, DAB menyelesaikan placeholder dan menggantinya dengan nilai rahasia, mirip dengan cara kerja @env('VAR_NAME'). Jika rahasia tidak dapat diambil, pemuatan konfigurasi gagal. Kesalahan termasuk hilangnya rahasia atau kegagalan otorisasi.

Struktur konfigurasi

Tambahkan bagian azure-key-vault di tingkat akar konfigurasi Anda:

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

Karakteristik

Harta benda Diperlukan Tipe Description
endpoint Ya jika menggunakan Key Vault string URL lengkap titik akhir Key Vault
retry-policy Tidak. objek Mengambil alih perilaku coba lagi saat memanggil Key Vault

Objek kebijakan coba lagi

Bidang Bawaan Catatan
mode exponential Nilai yang diizinkan: fixed atau exponential
max-count 3 Harus lebih besar dari 0
delay-seconds 1 Harus lebih besar dari 0
max-delay-seconds 60 Harus lebih besar dari 0, batas maksimum untuk mundur eksponensial
network-timeout-seconds 60 Harus lebih besar dari 0

Mode kebijakan coba lagi

Pengaturan Perilaku
fixed Menunggu waktu tetap delay-seconds antara percobaan hingga max-count
exponential Menggandakan penundaan hingga mencapai max-delay-seconds atau max-count

Pengembangan lokal: File .akv

Untuk pengembangan tanpa Azure Key Vault, gunakan .akv file untuk mensimulasikan rahasia. Format adalah name=value per baris:

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

Nota

Jika Anda menyediakan file lokal .akv untuk pengembangan, entrinya digunakan untuk memenuhi @akv(pencarian 'nama rahasia') tanpa melakukan panggilan jaringan ke Azure Key Vault.

Pedoman:

  • Jauhkan .akv dari kontrol sumber
  • Nama rahasia harus cocok dengan nama yang digunakan di @akv('name')

Menambahkan pengaturan Azure Key Vault dengan CLI

Anda dapat mengonfigurasi pengaturan Key Vault menggunakan 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

Validasi:

  • Bidang kebijakan pengulangan tanpa endpoint menyebabkan kegagalan validasi.
  • Parameter coba lagi opsional harus bilangan bulat positif

Menggunakan @akv() dalam konfigurasi

Substitusi dasar

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

Dicampur dengan @env()

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

Nota

Saat startup, @env() substitusi terjadi sebelum @akv() substitusi.

Parameter prosedur tersimpan

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

Troubleshooting

Gejala Steps
Rahasia tidak ditemukan Memverifikasi nama, keberadaan di brankas, dan izin-izin identitas
Nilai coba lagi tidak valid Gunakan bilangan bulat positif atau hapus untuk menggunakan default
Pembaruan konfigurasi gagal Periksa log untuk kesalahan validasi
@akv() tidak diganti Mengonfirmasi titik akhir, nama rahasia, dan resolusi rahasia tersebut diaktifkan
401/403 dari Key Vault Memeriksa penetapan identitas dan izin

Konfigurasi contoh lengkap

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

Contoh .akv file:

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

Penting

Jangan memasukkan .akv file yang berisi rahasia. |

Referensi cepat

Item Ringkasan
Syntax @akv('secret-name')
Titik akhir diperlukan Yes
File simulasi .akv dengan name=value baris
Mencampur dengan @env() Supported.

Tinjauan

Gunakan @akv() untuk mengatasi rahasia dari Azure Key Vault. Konfigurasikan kebijakan pengulangan untuk keandalan, dan gunakan .akv file untuk mensimulasikan rahasia dalam pengembangan. Ini menjaga agar nilai sensitif tidak dimasukkan ke dalam file konfigurasi sambil mendukung alur kerja pengembangan dan produksi yang konsisten.

  • Last updated on