Azure Key Vault gizli anahtar değişimi için Data API Builder'da @akv() kullanın

Veri API'si oluşturucusu (DAB), veritabanı bağlantı dizeleri gibi gizli dizileri yükleme zamanında değiştirerek çalışma zamanı yapılandırma dosyasından çıkarmanıza olanak tanır. Başlangıçta bu, ortam değişkenleri işlevi @env() ile yapıldı. 1.6 sürümünden itibaren, DAB @akv() işleviyle Azure Key Vault desteği ekleniyor.

@akv() ne yapar?

Azure Key Vault'ta depolanan bir gizliye doğrudan yapılandırma dosyasındaki JSON'da başvurabilirsiniz.

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

Yapılandırma yükleme zamanında DAB, yer tutucuyu çözümler ve tıpkı @env('VAR_NAME')'in çalışma şeklinde olduğu gibi, onu gizli sır değeriyle değiştirir. Gizli anahtar alınamazsa yapılandırma yüklenmesi başarısız olur. Hatalar eksik gizli anahtarlar veya yetkilendirme hatalarını içerir.

Yapılandırma yapısı

azure-key-vault Bölümü yapılandırmanızın kök düzeyinde ekleyin:

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

Özellikler

Mülkiyet	Gerekli	Türü	Description
endpoint	Key Vault kullanılıyorsa Evet	String	Tam Key Vault uç nokta URL'si
retry-policy	Hayı	object	Key Vault çağrılırken yeniden deneme davranışını geçersiz kılar

Yeniden deneme ilkesi nesnesi

Veri Alanı	Varsayılan	Notes
mode	exponential	İzin verilen değerler: fixed veya exponential
max-count	3	0'dan büyük olmalıdır
delay-seconds	1	0'dan büyük olmalıdır
max-delay-seconds	60	Üstel geri alma için tavan 0'dan büyük olmalıdır
network-timeout-seconds	60	0'dan büyük olmalıdır

İlke modlarını yeniden deneme

Mode	Davranış
fixed	delay-seconds süreyle sabit olarak bekler, denemeler arasında max-count'ye kadar.
exponential	max-delay-seconds veya max-count'e ulaşılana kadar gecikmeyi iki katına çıkarır

Yerel geliştirme: .akv dosyaları

Azure Key Vault olmadan geliştirme için gizli bilgileri simüle etmek amacıyla bir .akv dosyası kullanın. Satır başına biçim: name=value

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

Uyarı

Geliştirme için yerel bir .akv dosya sağlarsanız, bu dosyanın kayıtları Azure Key Vault'a ağ çağrısı yapmadan 'gizli-adı' @akv( aramalarını karşılamak için kullanılır.

Yönerge -leri:

• Kaynak denetiminden uzak tutun .akv
• Gizli adlar, @akv('name') içinde kullanılan adlarla eşleşmelidir.

CLI ile Azure Key Vault ayarlarını ekleme

CLI'yi kullanarak Key Vault ayarlarını yapılandırabilirsiniz:

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

Doğrulama:

• Uç nokta olmadan yeniden deneme ilkesi alanları doğrulama hatasına neden oluyor
• İsteğe bağlı yeniden deneme parametreleri pozitif tamsayılar olmalıdır

Yapılandırmada @akv() kullanımı

Temel değiştirme

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

@env() ile karıştırılır

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

Uyarı

Başlangıçta, @env() değişiklikleri @akv() değişikliklerinden önce yapılır.

Saklı yordam parametreleri

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

Sorun giderme

Semptom	Steps
Gizli bilgi bulunamadı	Adı, kasada varlığı ve kimlik izinlerini doğrulama
Geçersiz yeniden deneme değeri	Varsayılanları kullanmak için pozitif bir tamsayı kullanın veya kaldırın
Yapılandırma güncelleştirmesi başarısız oluyor	Doğrulama hataları için günlükleri kontrol et
@akv() değiştirilmedi	Uç noktayı, gizli adını ve gizli çözümlemenin etkinleştirildiğini onaylayın.
Key Vault'tan 401/403	Kimlik ataması ve izinlerini denetleme

Tam örnek yapılandırma

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

Örnek .akv dosya:

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

Önemli

Gizli bilgileri içeren dosyaları .akv göndermeyin. |

Hızlı referans

Ürün	Özet
Sözdizimi	@akv('secret-name')
Uç nokta gerekli	Yes
Benzetimi dosyası	.akv ile name=value çizgili
ile karıştırma	Supported.

İnceleme

Azure Key Vault'tan gizlileri çözmek için @akv() kullanın. Güvenilirlik için yeniden deneme ilkelerini yapılandırın ve geliştirme aşamasında .akv dosyalarını kullanarak gizli bilgileri simüle edin. Bu, tutarlı geliştirme ve üretim iş akışlarını desteklerken hassas değerleri yapılandırma dosyalarının dışında tutar.