Guia de configuração da implementação
O ALM Accelerator for Power Platform utiliza ficheiros de configuração no formato JSON para automatizar a implementação das suas soluções. Definem referências de ligação, variáveis de ambiente e permissões, a partilha de aplicações de tela e a atualização da propriedade de componentes de solução, como fluxos do Power Automate quando as soluções são implementadas em ambientes a jusante.
Os ficheiros de configuração neste artigo permitem-lhe configurar itens específicos do ambiente no qual uma solução está a ser implementada. Os ficheiros de configuração de que necessita e, consequentemente, os passos que tem de seguir neste artigo, dependem dos componentes que os pipelines da sua solução implementam. Por exemplo, se a sua solução contiver apenas tabelas do Dataverse, aplicações condicionadas por modelo e nenhuma configuração ou dados por ambiente for necessária, pode ignorar alguns destes passos.
Fornecemos ficheiros de configuração de exemplo nas definições de implementação e definições de implementação personalizadas do ALMAcceleratorSampleSolution.
Antes de começar
Este artigo é um guia passo a passo para configurar manualmente os ficheiros de configuração da implementação. Fornece detalhes sobre, e contexto para, as ações que são realizadas pela aplicação ALM Accelerator e pipelines como referência para administradores que queiram conhecer as especificidades de cada passo no processo.
No entanto, recomendamos que configure definições de implementação na aplicação ALM Accelerator.
Criar um ficheiro JSON de definições de implementação
Quando o ficheiro customDeploymentSettings.json é armazenado na raiz do diretório de configuração, a mesma configuração aplica-se a todos os ambientes. Assumindo que está a usar tarefas de pipeline de transformação de ficheiros ou de substituição de token para informações específicas sobre ambientes específicos, pode especificar os valores por ambiente nas suas variáveis de pipeline.
No entanto, também pode criar ficheiros customDeploymentSettings.json específicos de ambiente. Armazene-os em subdiretórios do diretório de configuração, chamado de acordo com os ambientes. O nome do diretório tem de corresponder à variável EnvironmentName que criou quando configurou o seu pipeline para os ambientes de validação, teste e produção. Se não existirem definições de implementação JSON e de diretório específicas do ambiente, os pipelines revertem para a configuração na raiz do diretório de configuração.
Também pode criar ficheiros de configuração específicos de utilizador, como o diretório JohannaDev, na imagem anterior. Os programadores podem utilizá-los para escolher uma configuração específica quando importam soluções não geridas a partir do controlo de origem.
O ficheiro JSON de definições da implementação configura referências de ligaçã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 a amostra de código JSON anterior para um novo ficheiro chamado deploymentSettings.json.
Guarde o ficheiro na pasta de configuração no Git.
Criar um JSON de referência de ligação
A propriedade ConnectionReferences no ficheiro customDeploymentConfiguration.json define referências de ligação na solução após esta ser importada para um ambiente. ConnectionReferences Também habilite fluxos depois que a solução for importada, com base no proprietário da conexão especificada na variável.
Crie as ligações manualmente nos ambientes de destino.
Copie os IDs para as ligações.
Obtenha o nome lógico da referência de ligação a partir do componente de referência de ligação na sua solução.
Obtenha o ID da ligação a partir do URL da ligação depois de o criar. Por exemplo, se o URL for "https://.../connections/shared_commondataservice/9f66d1d455f3474ebf24e4fa2c04cea2/details", o ID da ligação é 9f66d1d455f3474ebf24e4fa2c04cea2.
Edite o ficheiro customDeploymentSettings.json e cole os IDs na propriedade
ConnectionReferences, como no seguinte código de exemplo:"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 utilizar a extensão Substituir Tokens e adicionar tokens à sua configuração, como no exemplo anterior, abra o pipeline para a sua solução e, em seguida, selecione Editar>Variáveis.
No ecrã Variáveis de Pipeline, crie a ligação <connection_reference_logicalname>. Neste exemplo, a variável de pipeline é chamada
connection.cat_CDS_Current.Defina o valor para o ID de ligação que encontrou anteriormente.
Para se certificar de que o valor não é guardado como texto simples, selecione Manter este valor secreto.
Onde aplicável, repita estes passos para cada solução e pipeline que criar.
Criar JSON de variável de ambiente no ficheiro de configuração da implementação
A propriedade EnvironmentVariables no ficheiro customDeploymentConfiguration.json define variáveis de ambiente do Dataverse na solução após esta ser importada para um ambiente.
Importante
Quando soluções controladas pela origem são exportadas, os valores de variáveis de ambiente são exportados com a solução. Isto pode ser apresentar um risco de segurança se as variáveis de ambiente contiverem informações confidenciais. Recomendamos que não guarde informação confidenciais em variáveis de ambiente. Uma forma de se certificar de que os valores de variáveis de ambiente não são controlados pela origem, é criar uma solução especificamente para valores de variáveis de ambiente nos seus ambientes de desenvolvimento e definir o respetivo valor nessa solução. Isto impede que os valores sejam exportados com a solução e que sejam armazenados no controlo de origem.
Copie o nome do esquema da variável de ambiente a partir do componente de variável de ambiente na sua solução.
Edite o ficheiro customDeploymentSettings.json e cole o nome na propriedade
EnvironmentVariables, como no seguinte código de exemplo:{ "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 utilizar a extensão Substituir Tokens e adicionar tokens à sua configuração, como no exemplo anterior, abra o pipeline para a sua solução e, em seguida, selecione Editar>Variáveis.
No ecrã Variáveis de Pipeline, crie uma variável de pipeline para cada token na sua configuração; por exemplo, variable.cat_TextEnvironmentVariable.
Defina o valor para o valor da variável de ambiente para esse ambiente.
Para se certificar de que o valor não é guardado como texto simples, selecione Manter este valor secreto.
Onde aplicável, repita estes passos para cada solução e pipeline que criar.
Criar um ficheiro JSON de definições de implementação personalizado
O ficheiro JSON de definições de implementação personalizado contém definições que ativam fluxos em nome de um utilizador, especifica a propriedade dos fluxos, partilha aplicações de tela com grupos do Microsoft Entra e cria equipas de grupo do Dataverse após a implementaçã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 a amostra de código JSON anterior para um novo ficheiro chamado customDeploymentSettings.json.
Guarde o ficheiro na pasta de configuração no Git.
Criar JSON de variável de ambiente predefinido no ficheiro de configuração da implementação personalizado
A propriedade DefaultEnvironmentVariables em customDeploymentConfiguration.json é utilizada no pipeline de exportação para definir variáveis de ambiente predefinido do Dataverse na sua solução quando esta é exportada e armazenada no controlo de origens.
Nota
As predefinições de variáveis de ambiente só se aplicam se o pipeline de exportação estiver configurado com a variável do pipeline VerifyDefaultEnvironmentVariableValues = True.
Copie o nome do esquema da variável de ambiente a partir do componente de variável de ambiente na sua solução.
Edite o ficheiro customDeploymentSettings.json e cole o nome na propriedade
DefaultEnvironmentVariables, como no seguinte código de exemplo:{ "DefaultEnvironmentVariables": [ [ "cat_TextEnvironmentVariable", "#{defaultvariable.cat_TextEnvironmentVariable}#" ], [ "cat_DecimalEnvironmentVariable", "#{defaultvariable.cat_DecimalEnvironmentVariable}#" ], [ "cat_jsonEnvironmentVariable", "{\"name\":\"#{defaultvariable.cat_jsonEnvironmentVariable.name}#\"}" ] ] }Se utilizar a extensão Substituir Tokens e adicionar tokens à sua configuração, como no exemplo anterior, abra o pipeline para a sua solução e, em seguida, selecione Editar>Variáveis.
No ecrã Variáveis de Pipeline, crie uma variável de pipeline para cada token na sua configuração; por exemplo, defaultvariable.cat_TextEnvironmentVariable.
Onde aplicável, repita estes passos para cada solução e pipeline que criar.
Criar JSON de configuração de tela do grupo do Microsoft Entra
A propriedade AadGroupCanvasConfiguration no ficheiro customDeploymentConfiguration.json partilha aplicações de tela na sua solução com grupos do Microsoft Entra específicos após a solução ser importada para um ambiente.
Copie os IDs para a aplicação de tela e grupo do Microsoft Entra.
Obtenha o nome do esquema da aplicação de tela a partir do componente de aplicação de tela na sua solução.
Obtenha o ID do grupo do Microsoft Entra na página Grupo no portal do Azure.
Edite o ficheiro customDeploymentSettings.json e cole os IDs na propriedade
AadGroupCanvasConfiguration, como no seguinte código de exemplo:{ "AadGroupCanvasConfiguration": [ { "aadGroupId": "#{canvasshare.aadGroupId}#", "canvasNameInSolution": "cat_devopskitsamplecanvasapp_c7ec5", "roleName": "#{canvasshare.roleName}#" } ] }O
roleNamepode serCanView,CanViewWithShareeCanEdit.Se utilizar a extensão Substituir Tokens e adicionar tokens à sua configuração, como no exemplo anterior, abra o pipeline para a sua solução e, em seguida, selecione Editar>Variáveis.
No ecrã 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 o ID do grupo do Microsoft Entra com o qual a aplicação tem de ser partilhada para esse ambiente específico.
Para se certificar de que o valor não é guardado como texto simples, selecione Manter este valor secreto.
Onde aplicável, repita estes passos para cada solução e pipeline que criar.
Criar JSON de configuração de equipa e grupo do Microsoft Entra
A propriedade AadGroupTeamConfiguration no ficheiro customDeploymentConfiguration.json mapeia equipas e funções do Dataverse para grupos do Microsoft Entra na sua solução após esta ser importada para um ambiente.
Os direitos de acesso têm de ser adicionadas à sua solução se não forem criadas manualmente no ambiente de destino. Uma ou mais funções podem ser aplicadas a uma equipa. As funções fornecem permissões aos componentes da solução requeridos pelos utilizadores no grupo.
O nome da equipa do Dataverse pode ser de uma equipa existente ou de uma nova equipa a ser criada no Dataverse e mapeada para um grupo do Microsoft Entra depois de a solução ser importada.
As funções do Dataverse podem ser qualquer direito de acesso no Dataverse que seria aplicado à equipa depois de a solução ser importada. As funções têm de ter privilégios para os recursos que a solução requer, tais como tabelas e processos.
Obtenha o ID do grupo do Microsoft Entra na página Grupo no portal do Azure, como na secção anterior.
Edite o ficheiro customDeploymentSettings.json e cole o JSON na propriedade
AadGroupTeamConfiguration, como no seguinte código de exemplo:{ "AadGroupTeamConfiguration": [ { "aadGroupTeamName": "alm-accelerator-sample-solution", "aadSecurityGroupId": "#{team.aadSecurityGroupId}#", "dataverseSecurityRoleNames": [ "ALM Accelerator Sample Role" ] } ] }Se utilizar a extensão Substituir Tokens e adicionar tokens à sua configuração, como no exemplo anterior, abra o pipeline para a sua solução e, em seguida, selecione Editar>Variáveis.
No ecrã 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 o ID do grupo do Microsoft Entra a associar à equipa no Dataverse.
Para se certificar de que o valor não é guardado como texto simples, selecione Manter este valor secreto.
Onde aplicável, repita estes passos para cada solução e pipeline que criar.
Criar JSON de propriedade de componente da solução
A propriedade SolutionComponentOwnershipConfiguration no ficheiro customDeploymentConfiguration.json atribua a propriedade de componentes da solução aos utilizadores do Dataverse após a solução ser importada para um ambiente. A atribuição da propriedade é útil para componentes, como fluxos que, por predefinição, são propriedade do utilizador principal de serviço depois de a solução ser importada pelo pipeline e as organizações querem reatribuí-los depois de serem importados.
A propriedade SolutionComponentOwnershipConfiguration é também permite ativar fluxos que não têm nenhuma referência de ligação. O fluxo é ativado pelo utilizador especificado quando não existirem referências de ligação para ativar o fluxo.
Nota
O atual pipeline apenas implementa a capacidade de definir a propriedade dos fluxos.
O código de tipo do componente da solução baseia-se nos tipos de componentes especificados na referência API Web solutioncomponent EntityType. Por exemplo, um fluxo do Power Automate é o tipo de componente 29. O tipo de componente tem de ser especificado como um valor de número inteiro, sem aspas.
Obtenha nome exclusivo de um componente de fluxo do Power Automate a partir da solução descompactada.
Os fluxos não requerem nomes exclusivos quando são criados. O único verdadeiro identificador exclusivo para um fluxo é o ID interno que o sistema lhe atribui numa solução.
Obtenha o endereço de e-mail do proprietário a partir do registo do utilizador no Dataverse ou Microsoft 365.
Edite o ficheiro customDeploymentSettings.json e cole o JSON na propriedade
AadGroupTeamConfiguration, como no seguinte código de exemplo:{ "SolutionComponentOwnershipConfiguration": [ { "solutionComponentType": 29, "solutionComponentUniqueName": "00000000-0000-0000-0000-00000000000", "ownerEmail": "#{owner.ownerEmail}#" }, { "solutionComponentType": 29, "solutionComponentUniqueName": "00000000-0000-0000-0000-00000000000", "ownerEmail": "#{owner.ownerEmail}#" } ] }Se utilizar a extensão Substituir Tokens e adicionar tokens à sua configuração, como no exemplo anterior, abra o pipeline para a sua solução e, em seguida, selecione Editar>Variáveis.
No ecrã Variáveis de Pipeline, crie uma variável de pipeline para cada token na sua configuração; por exemplo
owner.ownerEmail.Defina o valor para o endereço de e-mail do proprietário do componente.
Para se certificar de que o valor não é guardado como texto simples, selecione Manter este valor secreto.
Onde aplicável, repita estes passos para cada solução e pipeline que criar.
Importar dados do seu pipeline
Poderá querer importar dados configuração ou de propagação para o seu ambiente do Dataverse inicialmente, depois de implementar a sua solução para o ambiente de destino. Os pipelines são configurados para importar dados utilizando a ferramenta Migração da Configuração disponível através do NuGet. Saiba mais sobre como gerenciar dados de configuração.
Quando os dados de configuração são armazenado na raiz do diretório de configuração, os mesmos dados de configuração aplicam-se a todos os ambientes. Pode criar ficheiros de dados de configuração específicos do ambiente. Armazene-os em subdiretórios do diretório de configuração, chamado de acordo com os ambientes. O nome do diretório tem de corresponder à variável EnvironmentName que criou quando configurou o seu pipeline para os ambientes de validação, teste e produção. Se não existirem dados de configuração e de diretório específicos do ambiente, os pipelines revertem para os dados de configuração na raiz do diretório de configuração.
Clone o repositório do Azure DevOps onde a sua solução deverá ser controlada pela origem e onde criou o seu YAML de pipeline de solução para o seu computador local.
Se ainda não o fez, crie um diretório chamado configuração na pasta de configuração na pasta da sua solução.
Instale a ferramenta Migração da Configuração. Siga as instruções em Transferir ferramentas a partir do NuGet.
Abra a ferramenta Migração da Configuração, selecione Criar esquema e, em seguida, selecione Continuar.
Inicie sessão no inquilino a partir do qual pretende exportar os seus dados de configuração.
Selecione o seu ambiente.
Selecione as tabelas e colunas que pretende exportar.
Selecione Guardar e Exportar. Guarde os dados no caminho do diretório config\ConfigurationMigrationData no seu repositório do Azure DevOps local na pasta da solução para a qual os dados devem ser importados.
Nota
O pipeline procura por esta pasta específica para importar os dados após a sua solução ser importada. Certifique-se de que o nome da pasta e a localização dela são exatamente como indicados aqui.
Quando lhe for pedido para exportar os dados, selecione Sim.
Escolha o mesmo local para os seus dados exportados, selecione Guardar e, em seguida, selecione Exportar Dados.
Quando a exportação estiver concluída, deszipe os ficheiros do ficheiro data.zip para o diretório ConfigurationMigrationData. Elimine os ficheiros data.zip e SampleData.xml.
Consolide as alterações com os seus dados para Azure DevOps.