Use referências de Configuração de Aplicações para o Serviço de Aplicações do Azure e as Funções do Azure

Este artigo mostra como trabalhar com dados de configuração no Serviço de Aplicativo do Azure ou em aplicativos do Azure Functions sem fazer alterações de código. A Configuração de Aplicativo do Azure é um serviço do Azure que você pode usar para gerenciar centralmente a configuração do aplicativo. Também é uma ferramenta eficaz para auditar seus valores de configuração ao longo do tempo ou entre versões.

Conceder ao aplicativo acesso à App Configuration

Para começar a usar referências de Configuração de Aplicativo no Serviço de Aplicativo, primeiro crie uma loja de Configuração de Aplicativo. Em seguida, você concede permissões ao seu aplicativo para acessar os pares chave/valor de configuração que estão na loja.

1. Para criar uma loja de Configuração de Aplicações, conclua o guia rápido de início de Configuração de Aplicações.

2. Crie uma identidade gerenciada para seu aplicativo.

   As referências de Configuração do Aplicativo usam a identidade atribuída pelo sistema do aplicativo por padrão, mas você pode especificar uma identidade atribuída pelo usuário.

3. Conceda à identidade o conjunto correto de permissões de acesso à App Configuration Store. Atualize as atribuições de função para sua loja. Atribua a função Leitor de Dados de Configuração do Aplicativo a essa identidade, abrangendo o recurso.

Aceder à App Configuration Store com uma identidade atribuída pelo utilizador

Em alguns casos, os aplicativos podem precisar fazer referência à configuração ao criá-los, mas uma identidade atribuída ao sistema ainda não está disponível. Nesse cenário, você pode criar uma identidade atribuída pelo usuário para a App Configuration Store com antecedência.

Depois de conceder permissões à identidade atribuída pelo usuário, conclua estas etapas:

1. Atribua a identidade ao seu aplicativo.

2. Configure a aplicação para usar esta identidade para operações de referência de Configuração da Aplicação definindo a propriedade keyVaultReferenceIdentity como a ID de recurso da identidade atribuída ao utilizador. Embora a propriedade tenha keyVault no nome, a identidade também se aplica às referências de Configuração do Aplicativo. Aqui está o código:

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

Essa configuração se aplica a todas as referências no aplicativo.

Conceda ao seu aplicativo acesso a cofres de chaves referenciados

Além de armazenar valores de configuração brutos, a Configuração do Aplicativo tem seu próprio formato para armazenar referências do Cofre da Chave do Azure. Se o valor de uma referência de Configuração de Aplicativo for uma referência do Cofre de Chaves na Loja de Configuração de Aplicativos, seu aplicativo também deverá ter permissões para acessar o cofre de chaves especificado na referência.

Para conceder ao seu aplicativo acesso a um cofre de chaves:

1. Identifique a identidade que você usou para a referência de Configuração do Aplicativo. Você deve conceder acesso ao cofre com a mesma identidade.

2. Crie uma política de acesso no Cofre da Chave para essa identidade. Ative a permissão Obter segredo no âmbito desta política. Não configure o aplicativo autorizado ou as applicationId configurações porque elas não são compatíveis 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ído por um valor conforme descrito na tabela a seguir:

Aqui está um exemplo de uma referência completa que inclui Label:

@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeyLabel)​

Aqui está um exemplo que não inclui Label:

@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)​

Qualquer alteração de configuração na aplicação que resulte numa reinicialização do site causa uma reobtenção imediata de todos os pares chave/valor referenciados na Loja de Configuração do Aplicativo.

Obter configurações de aplicação a partir da Configuração de Aplicações

Você pode usar referências de Configuração do Aplicativo como valores para as configurações do aplicativo para que possa manter os dados de configuração na Configuração do Aplicativo em vez de nas definições de configuração do site. As configurações do aplicativo e os pares chave/valor da Configuração do Aplicativo são criptografados com segurança em repouso. Se você precisar de recursos centralizados de gerenciamento de configuração, adicione dados de configuração à 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 de configuração por meio de sua chave, como de costume. Não são necessárias alterações de código.

Considerações para montar arquivos do Azure

As aplicações podem usar a definição da aplicação WEBSITE_CONTENTAZUREFILECONNECTIONSTRING para montar os Ficheiros do Azure como sistema de ficheiros. Essa configuração tem verificações de validação adicionais para garantir que o aplicativo possa ser iniciado corretamente. A plataforma depende de ter uma partilha de conteúdo nos Ficheiros do Azure e assume um nome padrão, a menos que um seja especificado na WEBSITE_CONTENTSHARE configuração. Para quaisquer solicitações que modifiquem essas configurações, a plataforma tenta validar se o compartilhamento de conteúdo existe. Se o compartilhamento não existir, a plataforma tentará criá-lo. 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 de Aplicativo para essa configuração, essa verificação de validação falhará por padrão porque a conexão em si não pode ser resolvida enquanto a plataforma processa a solicitação de entrada. Para evitar esse problema, você pode ignorar a validação definindo WEBSITE_SKIP_CONTENTSHARE_VALIDATION como 1. Essa configuração ignora todas as verificações e o compartilhamento de conteúdo não é criado automaticamente. Você deve garantir que o compartilhamento seja criado com antecedência.

Quando você cria um site, a montagem do compartilhamento de conteúdo pode falhar se as permissões de identidade gerenciada não forem propagadas ou se a integração de rede virtual não estiver 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. Para obter mais informações, consulte a implantação do Azure Resource Manager na próxima seção. O Serviço de Aplicativo usa apenas um sistema de arquivos padrão até que os Arquivos do Azure sejam configurados e os arquivos não sejam copiados. 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

Se você automatizar implantações de recursos usando modelos do Azure Resource Manager (ARM), talvez seja necessário sequenciar suas dependências em uma ordem específica para que as referências de Configuração de Aplicativo funcionem. Nesse cenário, você deve definir as configurações do aplicativo como seu próprio recurso em vez de usar uma siteConfig propriedade na definição de site. O site deve ser definido primeiro para que a identidade atribuída ao sistema seja criada com o site. A identidade gerenciada é então usada na política de acesso.

Aqui está um modelo de exemplo para um aplicativo de função que tem 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"
            }
        }
    ]
}

Solucionar problemas de referências de configuração de aplicativos

Se uma referência não for resolvida corretamente, o valor de referência será usado. Uma variável de ambiente que usa a sintaxe @Microsoft.AppConfiguration(...) é criada. A referência pode causar um erro porque o aplicativo estava esperando um valor de configuração.

Esse erro é mais comumente o resultado de uma configuração incorreta da política de acesso à Configuração do Aplicativo. Mas também pode ocorrer se houver um erro de sintaxe na referência ou se o par de chave/valor de configuração não existir no repositório.

Conteúdo relacionado

• Referenciar segredos do Key Vault a partir do Serviço de Aplicação