Usar referências de Configuração de Aplicativo para o Serviço de Aplicativo e o Azure Functions
Este tópico mostra como trabalhar com dados de configuração no seu Serviço de Aplicativo ou aplicativo Azure Functions sem exigir nenhuma alteração de código. A Configuração de Aplicativo do Azure é um serviço para gerenciar centralmente a configuração do aplicativo. Além disso, é uma ferramenta de auditoria eficaz para seus valores de configuração ao longo do tempo ou versões.
Concedendo ao seu aplicativo acesso à Configuração do Aplicativo
Para começar a usar referências de Configuração de Aplicativo no Serviço de Aplicativo, primeiro você precisará de uma loja de Configuração de Aplicativo e fornecer permissão ao seu aplicativo para acessar os valores de chave de configuração na loja.
Crie uma loja de Configuração de Aplicativo seguindo o início rápido de Configuração de Aplicativo.
Crie uma identidade gerenciada para seu aplicativo.
As referências de Configuração do Aplicativo usarão a identidade atribuída ao sistema do aplicativo por padrão, mas você pode especificar uma identidade atribuída pelo usuário.
Habilite a identidade recém-criada para ter o conjunto certo de permissões de acesso na App Configuration Store. Atualize as atribuições de função para sua loja. Você estará atribuindo
App Configuration Data Readerfunção a essa identidade, com escopo sobre o recurso.
Aceder à App Configuration Store com uma identidade atribuída pelo utilizador
Alguns aplicativos podem precisar fazer referência à configuração no momento da criação, quando uma identidade atribuída ao sistema ainda não estaria disponível. Nesses casos, uma identidade atribuída ao usuário pode ser criada e ter acesso à App Configuration Store, com antecedência. Siga estas etapas para criar uma identidade atribuída pelo usuário para a App Configuration Store.
Depois de conceder permissões para a identidade atribuída pelo usuário, siga estas etapas:
Atribua a identidade ao seu aplicativo, se ainda não o fez.
Configure o aplicativo para usar essa identidade para operações de referência de Configuração do Aplicativo definindo a
keyVaultReferenceIdentitypropriedade como a ID do recurso da identidade atribuída pelo usuário. Embora a propriedade tenha keyVault no nome, a identidade também se aplicará às referências de Configuração do Aplicativo.userAssignedIdentityResourceId=$(az identity show -g MyResourceGroupName -n MyUserAssignedIdentityName --query id -o tsv) appResourceId=$(az webapp show -g MyResourceGroupName -n MyAppName --query id -o tsv) az rest --method PATCH --uri "${appResourceId}?api-version=2021-01-01" --body "{'properties':{'keyVaultReferenceIdentity':'${userAssignedIdentityResourceId}'}}"
Esta configuração será aplicada a todas as referências deste aplicativo.
Conceder ao seu aplicativo acesso a cofres de chaves referenciados
Além de armazenar valores brutos de configuração, a Configuração de Aplicativo do Azure tem seu próprio formato para armazenar referências do Cofre de Chaves. Se o valor de uma referência de Configuração de Aplicativo for uma referência de Cofre de Chaves na App Configuration Store, seu aplicativo também precisará ter permissão para acessar o cofre de chaves que está sendo especificado.
Nota
O conceito de referências do Cofre da Chave de Configuração do Aplicativo do Azure não deve ser confundido com o conceito de referências do Serviço de Aplicativo e do Cofre da Chave do Azure Functions. Seu aplicativo pode usar qualquer combinação destes, mas há algumas diferenças importantes a serem observadas. Se o seu cofre precisar ser restrito à rede ou se você precisar que o aplicativo atualize periodicamente para as versões mais recentes, considere usar a abordagem direta do Serviço de Aplicativo e do Azure Functions em vez de usar uma referência de Configuração do Aplicativo.
Identifique a identidade que você usou para a referência de Configuração do Aplicativo. O acesso ao cofre deve ser concedido com essa mesma identidade.
Crie uma política de acesso no Cofre da Chave para essa identidade. Habilite a permissão secreta "Obter" nesta política. Não configure o "aplicativo autorizado" ou
applicationIdas configurações, pois isso não é compatível com uma identidade gerenciada.
Sintaxe de referência
Uma referência de Configuração de Aplicativo tem o formato @Microsoft.AppConfiguration({referenceString}), onde {referenceString} é substituída por abaixo:
| Partes da cadeia de caracteres de referência | Description |
|---|---|
| Parâmetro de avaliação = ponto final; | Endpoint é a parte necessária da cadeia de caracteres de referência. O valor para Endpoint deve ter a url do seu recurso de Configuração de Aplicativo. |
| Chave=keyName; | Key forma a parte necessária da cadeia de caracteres de referência. Valor para Chave deve ser o nome da Chave que você deseja atribuir à configuração do aplicativo. |
| Rótulo=rótulo | A parte Label é opcional na cadeia de referência. Label deve ser o valor de Label para a chave especificada em Key |
Por exemplo, uma referência completa com Label seria semelhante à seguinte,
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeysLabel)
Em alternativa, sem qualquer Label:
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
Qualquer alteração de configuração no aplicativo que resulte em uma reinicialização do site causa uma rebusca imediata de todos os valores de chave referenciados na App Configuration Store.
Nota
Atualmente, não há suporte para a atualização/rebusca automática desses valores quando os valores-chave foram atualizados na Configuração do aplicativo.
Configurações do aplicativo de origem da configuração do aplicativo
As referências de Configuração do Aplicativo podem ser usadas como valores para Configurações do Aplicativo, permitindo que você mantenha os dados de configuração na Configuração do Aplicativo em vez da configuração do site. As Configurações do Aplicativo e os valores de chave da Configuração do Aplicativo são criptografados com segurança em repouso. Se você precisar de recursos centralizados de gerenciamento de configuração, os dados de configuração devem ir para a Configuração do aplicativo.
Para usar uma referência de Configuração de Aplicativo para uma configuração de aplicativo, defina a referência como o valor da configuração. Seu aplicativo pode fazer referência ao valor Configuration por meio de sua chave, como de costume. Não são necessárias alterações de código.
Gorjeta
A maioria das configurações de aplicativo que usam referências de Configuração de Aplicativo deve ser marcada como configurações de slot, pois você deve ter lojas ou rótulos separados para cada ambiente.
Considerações para a montagem de arquivos do Azure
Os aplicativos podem usar a configuração do WEBSITE_CONTENTAZUREFILECONNECTIONSTRING aplicativo para montar Arquivos do Azure como o sistema de arquivos. Essa configuração tem verificações de validação adicionais para garantir que o aplicativo possa ser iniciado corretamente. A plataforma depende de ter um compartilhamento de conteúdo nos Arquivos do Azure e assume um nome padrão, a menos que seja especificado por meio da WEBSITE_CONTENTSHARE configuração. Para quaisquer solicitações que modifiquem essas configurações, a plataforma tentará validar se esse compartilhamento de conteúdo existe, e tentará criá-lo se não. Se não for possível localizar ou criar o compartilhamento de conteúdo, a solicitação será bloqueada.
Se você usar referências de Configuração do Aplicativo para essa configuração, essa verificação de validação falhará por padrão, pois a conexão em si não poderá ser resolvida durante o processamento da solicitação de entrada. Para evitar esse problema, você pode ignorar a validação definindo WEBSITE_SKIP_CONTENTSHARE_VALIDATION como "1". Essa configuração ignorará todas as verificações e o compartilhamento de conteúdo não será criado para você. Você deve garantir que ele seja criado com antecedência.
Atenção
Se você pular a validação e a cadeia de conexão ou o compartilhamento de conteúdo forem inválidos, o aplicativo não poderá ser iniciado corretamente e só servirá erros HTTP 500.
Como parte da criação do site, também é possível que a tentativa de montagem do compartilhamento de conteúdo falhe devido às permissões de identidade gerenciadas não serem propagadas ou à integração de rede virtual não estar sendo configurada. Você pode adiar a configuração dos Arquivos do Azure até mais tarde no modelo de implantação para acomodar a configuração necessária. Consulte Implantação do Azure Resource Manager para saber mais. O Serviço de Aplicativo usará um sistema de arquivos padrão até que os Arquivos do Azure sejam configurados e os arquivos não sejam copiados, portanto, certifique-se de que nenhuma tentativa de implantação ocorra durante o período intermediário antes que os Arquivos do Azure sejam montados.
Implementação do Azure Resource Manager
Ao automatizar implantações de recursos por meio de modelos do Azure Resource Manager, talvez seja necessário sequenciar suas dependências em uma ordem específica para fazer esse recurso funcionar. É importante notar que você precisará definir as configurações do aplicativo como seu próprio recurso, em vez de usar uma siteConfig propriedade na definição do site. Isso ocorre porque o site precisa ser definido primeiro para que a identidade atribuída ao sistema seja criada com ele e possa ser usada na política de acesso.
Abaixo está um exemplo de pseudomodelo para um aplicativo de função com referências de Configuração de Aplicativo:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"roleNameGuid": {
"type": "string",
"defaultValue": "[newGuid()]",
"metadata": {
"description": "A new GUID used to identify the role assignment"
}
}
},
"variables": {
"functionAppName": "DemoMBFunc",
"appConfigStoreName": "DemoMBAppConfig",
"resourcesRegion": "West US2",
"appConfigSku": "standard",
"FontNameKey": "FontName",
"FontColorKey": "FontColor",
"myLabel": "Test",
"App Configuration Data Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '516239f1-63e1-4d78-a4de-a74fb236a071')]"
},
"resources": [
{
"type": "Microsoft.Web/sites",
"name": "[variables('functionAppName')]",
"apiVersion": "2021-03-01",
"location": "[variables('resourcesRegion')]",
"identity": {
"type": "SystemAssigned"
},
//...
"resources": [
{
"type": "config",
"name": "appsettings",
"apiVersion": "2021-03-01",
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"WEBSITE_FONTNAME": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontNameKey'),'; Label=',variables('myLabel'), ')')]",
"WEBSITE_FONTCOLOR": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontColorKey'),'; Label=',variables('myLabel'), ')')]",
"WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
//...
}
},
{
"type": "sourcecontrols",
"name": "web",
"apiVersion": "2021-03-01",
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
"[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
]
}
]
},
{
"type": "Microsoft.AppConfiguration/configurationStores",
"name": "[variables('appConfigStoreName')]",
"apiVersion": "2019-10-01",
"location": "[variables('resourcesRegion')]",
"sku": {
"name": "[variables('appConfigSku')]"
},
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
],
"properties": {
},
"resources": [
{
"type": "keyValues",
"name": "[variables('FontNameKey')]",
"apiVersion": "2021-10-01-preview",
//...
"dependsOn": [
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"value": "Calibri",
"contentType": "application/json"
}
},
{
"type": "keyValues",
"name": "[variables('FontColorKey')]",
"apiVersion": "2021-10-01-preview",
//...
"dependsOn": [
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"value": "Blue",
"contentType": "application/json"
}
}
]
},
{
"scope": "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]",
"type": "Microsoft.Authorization/roleAssignments",
"apiVersion": "2020-04-01-preview",
"name": "[parameters('roleNameGuid')]",
"properties": {
"roleDefinitionId": "[variables('App Configuration Data Reader')]",
"principalId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.principalId]",
"principalType": "ServicePrincipal"
}
}
]
}
Nota
Neste exemplo, a implantação do controle do código-fonte depende das configurações do aplicativo. Normalmente, esse é um comportamento inseguro, pois a atualização da configuração do aplicativo se comporta de forma assíncrona. No entanto, como incluímos a configuração do WEBSITE_ENABLE_SYNC_UPDATE_SITE aplicativo, a atualização é síncrona. Isso significa que a implantação do controle do código-fonte só começará depois que as configurações do aplicativo tiverem sido totalmente atualizadas. Para obter mais configurações de aplicativo, consulte Variáveis de ambiente e configurações de aplicativo no Serviço de Aplicativo do Azure.
Solução de problemas de referências de configuração do aplicativo
Se uma referência não for resolvida corretamente, o valor de referência será usado. Para as configurações do aplicativo, seria criada uma variável de ambiente cujo valor tem a @Microsoft.AppConfiguration(...) sintaxe. Isso pode causar um erro, pois o aplicativo estava esperando um valor de configuração em vez disso.
Mais comumente, esse erro pode ser devido a uma configuração incorreta da política de acesso à Configuração do Aplicativo. No entanto, também pode ser devido a um erro de sintaxe na referência ou ao valor da chave de configuração não existente no armazenamento.