Guia de configuração da implantação
O ALM Accelerator for Power Platform usa arquivos de configuração em formato JSON para automatizar a implantação das soluções. Ele define referências de conexão, variáveis de ambiente e permissões, além de compartilhar aplicativos de tela e atualizar a propriedade de componentes da solução, como fluxos do Power Automate quando as soluções são implantadas em ambientes downstream.
Os arquivos de configuração neste artigo permitem configurar itens específicos do ambiente no qual uma solução está sendo implantada. Os arquivos de configuração necessários e, portanto, as etapas que você precisa seguir neste artigo, dependem dos componentes que seus pipelines de solução implantam. Por exemplo, se sua solução contém apenas tabelas, colunas e aplicativos baseados em modelo do Dataverse, e nenhuma configuração ou dados por ambiente são necessários, você pode ignorar algumas dessas etapas.
Demos um exemplo de arquivos de configuração nas configurações de implantação e configurações de implantação personalizadas do ALMAcceleratorSampleSolution.
Antes de começar
Este artigo é um guia passo a passo para configurar os arquivos de configuração de implantação manualmente. Ele dá detalhes e contexto para as ações que são executadas pelo aplicativo e pipelines ALM Accelerator e funciona como referência para administradores que desejam conhecer detalhes de cada etapa do processo.
Porém, recomendamos que você defina configurações de implantação no aplicativo ALM Accelerator.
Criar um arquivo JSON de configurações de implantação
Quando o arquivo customDeploymentSettings.json é armazenado na raiz do diretório config, a mesma configuração de se aplica a todos os ambientes. Supondo que você esteja usando tarefas de pipeline de transformação de arquivo ou de substituição de token para informações específicas do ambiente em particular, você poderá especificar valores por ambiente em variáveis de pipeline.
No entanto, você também pode criar arquivos customDeploymentSettings.json específicos do ambiente. Armazene-os em subdiretórios do diretório de configuração, nomeado para seus ambientes. O nome do diretório deve corresponder à variável EnvironmentName criada ao configurar o pipeline para ambientes de validação, teste e produção. Se não houver nenhuma configuração de implantação específica do ambiente JSON e diretório, os pipelines serão revertidos para a configuração na raiz do diretório config.
Você também pode criar arquivos de configuração específicos do usuário, como o diretório JohannaDev na imagem anterior. Os desenvolvedores podem usá-los para escolher uma configuração específica ao importar soluções não gerenciadas do controle do código-fonte.
O arquivo JSON de configurações de implantação configura referências de conexão e variáveis de ambiente.
{
"EnvironmentVariables": [
{
"SchemaName": "cat_shared_sharepointonline_97456712308a4e65aae18bafcd84c81f",
"Value": "#{environmentvariable.cat_shared_sharepointonline_97456712308a4e65aae18bafcd84c81f}#"
},
{
"SchemaName": "cat_shared_sharepointonline_21f63b2d26f043fb85a5c32fc0c65924",
"Value": "#{environmentvariable.cat_shared_sharepointonline_21f63b2d26f043fb85a5c32fc0c65924}#"
},
{
"SchemaName": "cat_TextEnvironmentVariable",
"Value": "#{environmentvariable.cat_TextEnvironmentVariable}#"
},
{
"SchemaName": "cat_ConnectorBaseUrl",
"Value": "#{environmentvariable.cat_ConnectorBaseUrl}#"
},
{
"SchemaName": "cat_DecimalEnvironmentVariable",
"Value": "#{environmentvariable.cat_DecimalEnvironmentVariable}#"
},
{
"SchemaName": "cat_JsonEnvironmentVariable",
"Value": "#{environmentvariable.cat_JsonEnvironmentVariable}#"
},
{
"SchemaName": "cat_ConnectorHostUrl",
"Value": "#{environmentvariable.cat_ConnectorHostUrl}#"
}
],
"ConnectionReferences": [
{
"LogicalName": "new_sharedsharepointonline_b49bb",
"ConnectionId": "#{connectionreference.new_sharedsharepointonline_b49bb}#",
"ConnectorId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline"
},
{
"LogicalName": "cat_CDS_Current",
"ConnectionId": "#{connectionreference.cat_CDS_Current}#",
"ConnectorId": "/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps"
}
]
}
Copie o exemplo de código JSON anterior em um novo arquivo chamado deploymentSettings.json.
Salve o arquivo na pasta config no Git.
Criar uma referência de conexão JSON
A propriedade ConnectionReferences no arquivo customDeploymentConfiguration.json define referências de conexão em sua solução depois que a solução é importada para um ambiente. ConnectionReferences também habilita fluxos após a importação da solução, com base no proprietário da conexão especificado na variável.
Crie as conexões manualmente nos ambientes de destino.
Copie os IDs para as conexões.
Obtém o nome lógico para a referência de conexão do componente de referência de conexão na solução.
Obtém a ID da conexão do URL da conexão depois que você a cria. Por exemplo, se o URL for 'https://.../connections/shared_commondataservice/9f66d1d455f3474ebf24e4fa2c04cea2/details', a ID da conexão será 9f66d1d455f3474ebf24e4fa2c04cea2.
Edite o arquivo customDeploymentSettings.json e cole os IDs na propriedade
ConnectionReferences, conforme o código de exemplo a seguir:"ConnectionReferences": [ { "LogicalName": "new_sharedsharepointonline_b49bb", "ConnectionId": "#{connectionreference.new_sharedsharepointonline_b49bb}#", "ConnectorId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline" }, { "LogicalName": "cat_CDS_Current", "ConnectionId": "#{connectionreference.cat_CDS_Current}#", "ConnectorId": "/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps" } ]Se você usa a extensão Substituir Tokens e adiciona tokens em sua configuração como no exemplo anterior, abra o pipeline para a solução e selecione Editar>Variáveis.
Na tela Variáveis de pipeline, crie a conexão <connection_reference_logicalname>. Neste exemplo, a variável de pipeline se chama
connection.cat_CDS_Current.Defina o valor para a ID da conexão encontrada antes.
Para garantir que o valor não seja salvo como texto sem formatação, selecione Manter esse valor secreto.
Quando aplicável, repita essas etapas para cada solução e pipeline que você criar.
Crie a variável de ambiente JSON no arquivo de configuração de implantação
A propriedade EnvironmentVariables no arquivo customDeploymentConfiguration.json define variáveis de ambiente do Dataverse em sua solução depois que a solução é importada para um ambiente.
Importante
Ao exportar soluções com controle de código-fonte, os valores da variável de ambiente são exportados com a solução. Isso pode representar um risco de segurança se as variáveis de ambiente contêm informações confidenciais. Recomendamos que você não armazene informações confidenciais em variáveis de ambiente. Um modo de garantir que os valores da variável de ambiente não sejam controlados pela origem é criar uma solução especificamente para valores de variáveis de ambiente em ambientes de desenvolvimento e definir o valor delas nessa solução. Isso impede que os valores sejam exportados com a solução e armazenados no controle do código-fonte.
Copie o nome do esquema para a variável de ambiente do componente da variável de ambiente na solução.
Edite o arquivo customDeploymentSettings.json e cole o nome na propriedade
EnvironmentVariables, conforme o código de exemplo a seguir:{ "EnvironmentVariables": [ { "SchemaName": "cat_TextEnvironmentVariable", "Value": "#{variable.cat_TextEnvironmentVariable}#" }, { "SchemaName": "cat_DecimalEnvironmentVariable", "Value": "#{variable.cat_DecimalEnvironmentVariable}#" }, { "SchemaName": "cat_JsonEnvironmentVariable", "Value": "{\"name\":\"#{variable.cat_JsonEnvironmentVariable.name}#\"}" } ] }Se você usa a extensão Substituir Tokens e adiciona tokens em sua configuração como no exemplo anterior, abra o pipeline para a solução e selecione Editar>Variáveis.
Na tela Variáveis de pipeline, crie uma variável de pipeline para cada token em sua configuração; por exemplo, variable.cat_TextEnvironmentVariable.
Defina o valor da variável de ambiente para o ambiente em questão.
Para garantir que o valor não seja salvo como texto sem formatação, selecione Manter esse valor secreto.
Quando aplicável, repita essas etapas para cada solução e pipeline que você criar.
Criar um arquivo JSON de configurações de implantação personalizado
Esse arquivo JSON de configurações de implantação personalizado contém configurações que ativam fluxos em nome de um usuário, especificam a propriedade de fluxos, compartilham aplicativos de tela com grupos do Microsoft Entra e criam equipes de grupo do Dataverse após a implantação.
{
"ActivateFlowConfiguration": [
{
"solutionComponentName": "DevOpsKitSampleFlow",
"solutionComponentUniqueName": "0a43b549-50ed-ea11-a815-000d3af3a7c4",
"activateAsUser": "#{activateflow.activateas.DevOpsKitSampleFlow}#"
},
{
"solutionComponentName": "CallMeFromCanvasApp",
"solutionComponentUniqueName": "71cc728c-2487-eb11-a812-000d3a8fe6a3",
"activateAsUser": "#{activateflow.activateas.CallMeFromCanvasApp}#"
},
{
"solutionComponentName": "GetEnvironmentVariables",
"solutionComponentUniqueName": "d2f7f0e2-a1a9-eb11-b1ac-000d3a53c3c2",
"activateAsUser": "#{activateflow.activateas.GetEnvironmentVariables}#"
}
],
"SolutionComponentOwnershipConfiguration": [
{
"solutionComponentType": 29,
"solutionComponentName": "DevOpsKitSampleFlow",
"solutionComponentUniqueName": "0a43b549-50ed-ea11-a815-000d3af3a7c4",
"ownerEmail": "#{owner.ownerEmail.DevOpsKitSampleFlow}#"
},
{
"solutionComponentType": 29,
"solutionComponentName": "CallMeFromCanvasApp",
"solutionComponentUniqueName": "71cc728c-2487-eb11-a812-000d3a8fe6a3",
"ownerEmail": "#{owner.ownerEmail.CallMeFromCanvasApp}#"
},
{
"solutionComponentType": 29,
"solutionComponentName": "GetEnvironmentVariables",
"solutionComponentUniqueName": "d2f7f0e2-a1a9-eb11-b1ac-000d3a53c3c2",
"ownerEmail": "#{owner.ownerEmail.GetEnvironmentVariables}#"
}
],
"AadGroupCanvasConfiguration": [
{
"aadGroupId": "#{canvasshare.aadGroupId.DevOpsKitSampleCanvasApp}#",
"canvasNameInSolution": "cat_devopskitsamplecanvasapp_c7ec5",
"canvasDisplayName": "DevOpsKitSampleCanvasApp",
"roleName": "#{canvasshare.roleName.DevOpsKitSampleCanvasApp}#"
}
],
"AadGroupTeamConfiguration": [
{
"aadGroupTeamName": "Sample Group Team Name",
"aadSecurityGroupId": "#{team.samplegroupteamname.aadSecurityGroupId}#",
"dataverseSecurityRoleNames": [
"#{team.samplegroupteamname.role}#"
]
}
]
}
Copie o exemplo de código JSON anterior em um novo arquivo chamado customDeploymentSettings.json.
Salve o arquivo na pasta config no Git.
Crie a variável de ambiente JSON padrão no arquivo de configuração de implantação personalizado
A propriedade DefaultEnvironmentVariables em customDeploymentConfiguration.json é usada no pipeline de exportação para definir variáveis de ambiente padrão do Dataverse na sua solução quando a solução é exportada e armazenada no controle do código-fonte.
Nota
As configurações de variáveis de ambiente padrão só serão aplicadas se o pipeline de exportação estiver configurado com a variável de pipeline VerifyDefaultEnvironmentVariableValues = True.
Copie o nome do esquema para a variável de ambiente do componente da variável de ambiente na solução.
Edite o arquivo customDeploymentSettings.json e cole o nome na propriedade
DefaultEnvironmentVariables, conforme o código de exemplo a seguir:{ "DefaultEnvironmentVariables": [ [ "cat_TextEnvironmentVariable", "#{defaultvariable.cat_TextEnvironmentVariable}#" ], [ "cat_DecimalEnvironmentVariable", "#{defaultvariable.cat_DecimalEnvironmentVariable}#" ], [ "cat_jsonEnvironmentVariable", "{\"name\":\"#{defaultvariable.cat_jsonEnvironmentVariable.name}#\"}" ] ] }Se você usa a extensão Substituir Tokens e adiciona tokens em sua configuração como no exemplo anterior, abra o pipeline para a solução e selecione Editar>Variáveis.
Na tela Variáveis de Pipeline, crie uma variável de pipeline para cada token em sua configuração; por exemplo, defaultvariable.cat_TextEnvironmentVariable.
Quando aplicável, repita essas etapas para cada solução e pipeline que você criar.
Crie o JSON de configuração da tela do grupo do Microsoft Entra
A propriedade AadGroupCanvasConfiguration no arquivo customDeploymentConfiguration.json compartilha os aplicativos de tela na sua solução com grupos específicos do Microsoft Entra depois que a solução é importada para um ambiente.
Copie os IDs para o aplicativo de tela e o grupo do Microsoft Entra.
Obtenha o nome do esquema para o aplicativo de tela do componente do aplicativo de tela na solução.
Obtenha a ID do grupo do Microsoft Entra na página Grupo no portal do Azure.
Edite o arquivo customDeploymentSettings.json e cole os IDs na propriedade
AadGroupCanvasConfiguration, conforme o código de exemplo a seguir:{ "AadGroupCanvasConfiguration": [ { "aadGroupId": "#{canvasshare.aadGroupId}#", "canvasNameInSolution": "cat_devopskitsamplecanvasapp_c7ec5", "roleName": "#{canvasshare.roleName}#" } ] }O
roleNamepode serCanView,CanViewWithShareeCanEdit.Se você usa a extensão Substituir Tokens e adiciona tokens em sua configuração como no exemplo anterior, abra o pipeline para a solução e selecione Editar>Variáveis.
Na tela Variáveis de Pipeline, crie uma variável de pipeline para cada token na sua configuração; por exemplo,
canvasshare.aadGroupId.Defina o valor para a ID de grupo do Microsoft Entra com o qual o aplicativo deve ser compartilhado para esse ambiente específico.
Para garantir que o valor não seja salvo como texto sem formatação, selecione Manter esse valor secreto.
Quando aplicável, repita essas etapas para cada solução e pipeline que você criar.
Crie o JSON de configuração do grupo e da equipe do Microsoft Entra
A propriedade AadGroupTeamConfiguration no arquivo customDeploymentConfiguration.json mapeia equipes e funções do Dataverse para grupos do Microsoft Entra na sua solução depois que a solução é importada para um ambiente.
Direitos de acesso deverão ser adicionados à sua solução se não forem criados manualmente no ambiente de destino. Uma ou mais funções podem ser aplicadas a uma equipe. As funções fornecem permissões aos componentes da solução exigidos pelos usuários do grupo.
O nome da equipe do Dataverse pode ser qualquer equipe existente ou uma nova equipe a ser criada no Dataverse e mapeada para um grupo do Microsoft Entra após a solução ser importada.
As funções do Dataverse podem ser um direito de acesso no Dataverse que seria aplicado à equipe após a importação da solução. As funções devem ter privilégios para os recursos exigidos pela solução, como tabelas e processos.
Obtenha a ID do grupo do Microsoft Entra na página Grupo no portal do Azure. na seção anterior.
Edite o arquivo customDeploymentSettings.json e cole o JSON na propriedade
AadGroupTeamConfiguration, conforme o código de exemplo a seguir:{ "AadGroupTeamConfiguration": [ { "aadGroupTeamName": "alm-accelerator-sample-solution", "aadSecurityGroupId": "#{team.aadSecurityGroupId}#", "dataverseSecurityRoleNames": [ "ALM Accelerator Sample Role" ] } ] }Se você usa a extensão Substituir Tokens e adiciona tokens em sua configuração como no exemplo anterior, abra o pipeline para a solução e selecione Editar>Variáveis.
Na tela Variáveis de Pipeline, crie uma variável de pipeline para cada token na sua configuração; por exemplo,
team.aadSecurityGroupId.Defina o valor para a ID do grupo do Microsoft Entra a ser associado à equipe no Dataverse.
Para garantir que o valor não seja salvo como texto sem formatação, selecione Manter esse valor secreto.
Quando aplicável, repita essas etapas para cada solução e pipeline que você criar.
Criar JSON de propriedade do componente da solução
A propriedade SolutionComponentOwnershipConfiguration no arquivo customDeploymentConfiguration.json atribui a propriedade de componentes da solução a usuários do Dataverse depois que a solução é importada para um ambiente. É útil atribuir propriedade para componentes como fluxos que, por padrão, são de propriedade do usuário da entidade de serviço depois de a solução ser importada pelo pipeline, e as organizações querem reatribuí-los após a importação.
A propriedade SolutionComponentOwnershipConfiguration também habilita fluxos que não têm nenhuma referência de conexão. O fluxo é habilitado pelo usuário especificado quando não há referências de conexão para habilitar o fluxo.
Observação
O pipeline atual implementa apenas a capacidade de definir a propriedade de fluxos.
O código do tipo de componente da solução se baseia nos tipos de componentes especificados na referência de API Web solutioncomponent EntityType. Por exemplo, um fluxo do Power Automate é um componente do tipo 29. O tipo de componente deve ser especificado como um valor inteiro, sem aspas.
Obtenha o nome exclusivo do componente do fluxo do Power Automate da solução descompactada.
Os fluxos não exigem nomes exclusivos quando são criados. O único identificador exclusivo verdadeiro para um fluxo é a ID interna que o sistema atribui em uma solução.
Obtenha o endereço de email do proprietário do registro do usuário no Dataverse ou no Microsoft 365.
Edite o arquivo customDeploymentSettings.json e cole o JSON na propriedade
AadGroupTeamConfiguration, conforme o código de exemplo a seguir:{ "SolutionComponentOwnershipConfiguration": [ { "solutionComponentType": 29, "solutionComponentUniqueName": "00000000-0000-0000-0000-00000000000", "ownerEmail": "#{owner.ownerEmail}#" }, { "solutionComponentType": 29, "solutionComponentUniqueName": "00000000-0000-0000-0000-00000000000", "ownerEmail": "#{owner.ownerEmail}#" } ] }Se você usa a extensão Substituir Tokens e adiciona tokens em sua configuração como no exemplo anterior, abra o pipeline para a solução e selecione Editar>Variáveis.
Na tela Variáveis de Pipeline, crie uma variável de pipeline para cada token na sua configuração; por exemplo,
owner.ownerEmail.Defina o valor como o endereço de email do proprietário do componente.
Para garantir que o valor não seja salvo como texto sem formatação, selecione Manter esse valor secreto.
Quando aplicável, repita essas etapas para cada solução e pipeline que você criar.
Importar dados do seu pipeline
Você talvez queira importar dados de configuração ou semente para seu ambiente do Dataverse depois de implantar a solução no ambiente de destino. Os pipelines são configurados para importar dados usando ferramenta de Migração da configuração, disponível por meio do NuGet. Saiba mais sobre como gerenciar dados de configuração.
Quando os dados de configuração são armazenados na raiz do diretório config, os mesmos dados de configuração são implantados em todos os ambientes. Você pode criar arquivos de dados de configuração específicos do ambiente. Armazene-os em subdiretórios do diretório de configuração, nomeado para seus ambientes. O nome do diretório deve corresponder à variável EnvironmentName criada ao configurar o pipeline para ambientes de validação, teste e produção. Se não existirem dados de configuração e diretório específicos do ambiente, os pipelines serão revertidos para os dados de configuração na raiz do diretório config.
Clone o repositório do Azure DevOps onde sua solução deve ter controle do código-fonte e em que você criou o pipeline de solução YAML para a máquina local.
Se você ainda não fez isso, crie um diretório chamado config na pasta config na pasta da solução.
Instale a ferramenta Migração de Configuração. Siga as instruções em Baixar ferramentas do NuGet.
Abra a ferramenta Migração de Configuração, selecione Criar esquema e, depois, Continuar.
Entre no locatário do qual você deseja exportar dados de configuração.
Selecione seu ambiente.
Selecione as tabelas e as colunas que deseja exportar.
Selecione Salvar e exportar. Salve os dados no caminho do diretório config\ConfigurationMigrationData no repositório local do Azure DevOps na pasta para a solução para a qual os dados devem ser importados.
Observação
O pipeline procura essa pasta específica para importar os dados depois que a solução é importada. O nome da pasta e sua localização devem ser exatamente os fornecidos aqui.
Quando solicitado a exportar os dados, selecione Sim.
Escolha o mesmo local para dados exportados, selecione Salvar e então Exportar Dados.
Quando a exportação for concluída, descompacte os arquivos do arquivo data.zip no diretório ConfigurationMigrationData. Exclua os arquivos data.zip e SampleData.xml.
Confirme as alterações com seus dados no Azure DevOps.