Usar @akv() para substituição de segredos no Azure Key Vault no Construtor de API de Dados.

O Construtor de API de Dados (DAB) permite manter segredos, como cadeias de conexão de banco de dados, fora do arquivo de configuração de tempo de execução, substituindo-os durante o carregamento. Originalmente, isso era feito com a @env() função para variáveis de ambiente. A partir da versão 1.6, o DAB adiciona suporte ao Azure Key Vault por meio da @akv() função.

O que @akv() faz

Você pode referenciar um segredo armazenado no Azure Key Vault diretamente no JSON de configuração:

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

No momento do carregamento da configuração, o DAB resolve o espaço reservado e o substitui pelo valor do secreto, semelhante a como @env('VAR_NAME') funciona. Se o segredo não puder ser recuperado, o carregamento de configuração falhará. Os erros incluem segredos ausentes ou falhas de autorização.

Estrutura de configuração

Adicione a azure-key-vault seção no nível raiz da configuração:

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

Propriedades

Objeto de política de repetição

Modos de política de repetição

Desenvolvimento local: arquivos .akv

Para desenvolvimento sem um Azure Key Vault, use um .akv arquivo para simular segredos. O formato é name=value por linha:

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

Diretrizes:

• Mantenha .akv fora do controle de versão
• Os nomes de segredo devem corresponder aos nomes usados em @akv('name')

Adicionando configurações do Azure Key Vault com a CLI

Você pode definir as configurações do Key Vault usando a 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

Validação:

• Campos de política de repetição sem um ponto de extremidade causam falha de validação
• Parâmetros de repetição opcionais devem ser inteiros positivos

Usando @akv() na configuração

Substituição básica

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

Misturado com @env()

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

Parâmetros de procedimento armazenado

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

Resolução de problemas

Configuração de exemplo completo

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

Exemplo de arquivo .akv:

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

Referência rápida

Review

Use @akv() para resolver segredos do Azure Key Vault. Configure políticas de repetição para confiabilidade e use .akv arquivos para simular segredos no desenvolvimento. Isso mantém os valores confidenciais fora dos arquivos de configuração, ao mesmo tempo em que dá suporte a fluxos de trabalho de produção e desenvolvimento consistentes.