Använd @akv() för att ersätta hemligheter i Azure Key Vault i Data API Builder

Med Data API Builder (DAB) kan du hålla hemligheter, till exempel databasanslutningssträngar, borta från körningskonfigurationsfilen genom att ersätta dem vid inläsningen. Ursprungligen gjordes detta med @env() funktionen för miljövariabler. Från och med version 1.6 lägger DAB till stöd för Azure Key Vault via @akv() funktionen.

Vad @akv() gör

Du kan referera till en hemlighet som lagras i Azure Key Vault direkt i JSON-konfigurationen:

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

Vid inläsning av konfigurationen löser DAB platshållaren och ersätter den med hemlighetens värde, liknande @env('VAR_NAME'). Om hemligheten inte kan hämtas misslyckas konfigurationsinläsningen. Fel inkluderar saknade hemligheter eller auktoriseringsfel.

Konfigurationsstruktur

Lägg till avsnittet azure-key-vault på rotnivån för konfigurationen:

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

Egenskaper

Återförsöks-princip-objekt

Återförsökspolicy-lägen

Lokal utveckling: .akv-filer

För utveckling utan ett Azure Key Vault använder du en .akv fil för att simulera hemligheter. Formatet är name=value per rad:

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

Riktlinjer:

• Håll .akv borta från källkontroll
• Hemliga namn måste matcha namnen som används i @akv('name')

Lägga till Azure Key Vault-inställningar med CLI

Du kan konfigurera Key Vault-inställningar med hjälp av 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

Validering:

• Omprövningsprincipfält utan slutpunkt orsakar valideringsfel
• Valfria återförsöksparametrar måste vara positiva heltal

Använda @akv() i konfigurationen

Grundläggande substitution

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

Blandat med @env()

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

Parametrar för lagrad procedur

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

Felsökning

Fullständig exempelkonfiguration

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

Exempelfil .akv :

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

Snabbreferens

Review

Använd @akv() för att lösa hemligheter från Azure Key Vault. Konfigurera återförsöksprinciper för tillförlitlighet och använd .akv filer för att simulera hemligheter under utveckling. Detta håller känsliga värden borta från konfigurationsfiler och stöder konsekventa arbetsflöden för utveckling och produktion.