Partilhar via

Automatizar a integração Git com um Principal de Serviço no Azure DevOps

A Integração Fabric Git é a base para organizações que implementam pipelines totalmente automatizados de CI/CD, permitindo a movimentação fluida de ativos entre ambientes de Desenvolvimento, Teste e Produção.

Atualmente, o Fabric Git Integration suporta dois principais fornecedores Git:

  • Azure DevOps
  • GitHub

Este artigo centra-se na capacidade Service Principal para Azure DevOps. Esta integração permite que o utilizador do Fabric realize operações git usando um principal de serviço.

Azure DevOps: Autenticação - automática e configurada

Por defeito, cada espaço de trabalho do Fabric não está ligado a nenhum repositório Git. Um espaço de trabalho Fabric tem duas formas diferentes de autenticar num repositório git. Estes processos são chamados:

  • Credencial Git automática
  • Credencial configurada

Credencial automática do git

Quando um utilizador administrador quer ligar um espaço de trabalho a um repositório Azure DevOps (ADO), o utilizador deve primeiro iniciar sessão a partir das definições do espaço de trabalho, e o sistema identifica então quais as organizações ADO a que o utilizador pode aceder dentro do tenant Fabric atual, permitindo ao utilizador avançar com a configuração.

Uma vez estabelecida a ligação inicial, qualquer utilizador adicional com pelo menos permissões de contribuinte no mesmo espaço de trabalho não precisa de repetir o processo de ligação. Em vez disso, o sistema tenta autenticar o segundo utilizador com o repositório ADO configurado. Se o utilizador não tiver as permissões necessárias, o painel de controlo de origem da Integração Fabric Git exibe um indicador vermelho.

Este processo de autenticação simplificado é conhecido como "Credencial Automática Git".

Credencial configurada

Com credencial configurada, pode criar programaticamente uma ligação cloud Azure DevOps usando um principal de serviço.

A ligação Azure DevOps suporta dois métodos de autenticação:

  • OAuth 2.0
  • Principal de Serviço

Ambos os métodos incluem suporte para cenários multitenant (cross-tenant), proporcionando flexibilidade às organizações em vários ambientes.

Qualquer outro utilizador com pelo menos permissões de Contribuidor no mesmo espaço de trabalho não precisa de repetir o processo de ligação. Antes do suporte ao principal de serviço, o sistema tentava autenticar utilizadores secundários apenas através da autenticação automática.

Se a autenticação automática falhar, o sistema também tenta ligar-se usando qualquer Credencial Configurada a que o utilizador tenha acesso, garantindo uma experiência mais fluida e reduzindo passos redundantes de configuração.

Como funciona

Para ligar um espaço de trabalho Fabric a um fornecedor Git externo usando um Service Principal, a integração com Git deve usar uma ligação Fabric cloud do tipo Azure DevOps – Controlo de Versão.

Esta ligação à cloud pode ser criada de duas formas através do portal:

Em ambos os casos, a ligação é criada sob a identidade do utilizador iniciado sessão.

Se um Principal de Serviço precisar de usar esta ligação, o utilizador tem de o fazer

  • partilhar a ligação com o principal do serviço
  • criar uma nova ligação usando a API REST de Conexões, passando as credenciais do Principal de Serviço.

Os passos abaixo descrevem como usar a API para criar a ligação à cloud usando um principal de serviço.

Pré-requisitos

Para completar os passos descrevidos, precisa das seguintes permissões:

Ligue um novo espaço de trabalho ao Azure DevOps usando o Service Principal

Para ligar um espaço de trabalho Fabric ao Azure DevOps usando o Service Principal programaticamente, é necessário seguir os seguintes passos:

  1. Gerar token de acesso ao Service Principal: Autentica com o Microsoft Fabric usando um Service Principal.
  2. Create Azure DevOps cloud connection: Cria um novo recurso de ligação no Microsoft Fabric que armazena as credenciais e configuração do repositório DevOps do Azure.
  3. Ligue o workspace ao git: Liga um espaço de trabalho específico do Fabric ao repositório Azure DevOps usando a ligação criada no passo 2.
  4. Inicializar Ligação: Inicializa a ligação Git.

1. Gerar token de acesso de Service Principal

Os exemplos seguintes mostram como gerar o token de acesso principal do serviço.

curl --request GET \ 
--url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \ 
--header 'content-type: multipart/form-data' \ 
--form grant_type=client_credentials \ 
--form client_id=<client-id> \ 
--form 'client_secret=<client-secret>' \ 
--form scope=https://api.fabric.microsoft.com/.default

Observação

Copie o access_token da resposta para passos posteriores.

2. Criar ligação cloud Azure DevOps

Cria um novo recurso de ligação no Microsoft Fabric que armazena as credenciais e configuração do repositório DevOps do Azure.

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/connections \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 

"displayName": "<name of the connection>", 
"connectivityType": "ShareableCloud", 
"connectionDetails": { 
"creationMethod": "AzureDevOpsSourceControl.Contents", 
"type": "AzureDevOpsSourceControl", 
"parameters": [ 

{ 
"dataType": "Text", 
"name": "url", 
"value": "https://dev.azure.com/<ado org name>/<project name>/_git/<repo name>/"}]}, 
"credentialDetails": { 
"credentials": { 
"credentialType": "ServicePrincipal", 
"tenantId": "<tenant-id>", 
"servicePrincipalClientId": "<client-id>", 
"servicePrincipalSecret": "<client-secret>"}}}'

Observação

Guarde o ID da resposta. É usado nos passos seguintes.

3. Ligar o espaço de trabalho ao git

Liga um espaço de trabalho específico do Fabric ao repositório Azure DevOps usando a ligação criada no passo 2.

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/connect \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 
"gitProviderDetails": { 
"organizationName": "<ado org name>", 
"projectName": "<project name>", 
"gitProviderType": "AzureDevOps", 
"repositoryName": "<repo name>", 
"branchName": "<branch name>", 
"directoryName": "<folder name – must exist before OR empty>" 
}, 
"myGitCredentials": { 
"source": "ConfiguredConnection", 
"connectionId": "<step 2 – the new connection id>"}}'

4. Inicializar Ligação

Inicie a Ligação, leia mais aqui.

Observação

Substitua <> pelos seus valores, preste atenção ao parâmetro initializationStrategy. Se o espaço de trabalho conectado já tiver itens, pode considerar usar "preferWorkspace".

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/initializeConnection \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{"initializationStrategy": "PreferRemote"}'

Se o repositório /workspace não estiver vazio, a resposta devolve o parâmetro requiredAction (que se baseia na sua estratégia de inicialização), use update-from-git OU commit-to-git, conforme o workspaceHead e o remoteCommitHash da resposta, para finalizar o processo.

Conectar um Espaço de Trabalho Existente para Utilizar um Principal de Serviço

Se o seu espaço de trabalho já estiver ligado ao Azure DevOps usando uma identidade de utilizador, mas quiser realizar operações de API REST em Fabric Git com um Service Principal, siga estes passos:

  1. Adicionar o Principal de Serviço como Administrador do Espaço de Trabalho.
  2. Conceder o acesso do Principal de Serviço à Conexão à Cloud do Azure DevOps. Tem duas opções:
  • Partilhe uma ligação existente: Inicie sessão com um utilizador que tenha acesso à ligação cloud ADO relevante e partilhe-a com o Service Principal através de Gerir Utilizadores.
  • Crie uma nova ligação: Repita os Passos 1 e 2 da secção anterior para criar uma nova ligação à cloud usando credenciais do Service Principal.
  1. Verificar acesso - Ligue à API de Conexões GET para confirmar que o Principal de Serviço pode aceder à ligação cloud necessária aqui:
curl --request GET \ 
--url https://api.fabric.microsoft.com/v1/connections \ 
--header 'authorization: Bearer <step 2: access-token>'

Obtenha o valor id da conexão relevante na resposta.

  1. Atualizar credencial Git: Gerar um token de acesso (passo 1 da secção anterior) e chamar a API Update My Git Credential, leia mais aqui (substitua <> pelos seus valores):
curl --request PATCH \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/myGitCredentials \ 
--header 'authorization: Bearer <step 2: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 
"source": "ConfiguredConnection", 
"connectionId": "<step 3: connection id>"}'

Após estes passos, o Service Principal está totalmente configurado e pronto para executar operações da API REST do Fabric Git.

Conteúdo relacionado

  • Last updated on