Ligue e desligue o Dataverse de um repositório Git usando código

Utilize as APIs ConnectToGit e DisconnectFromGit para integrar programaticamente o seu ambiente do Microsoft Dataverse com o controlo de código fonte do Git. Ao usar estas APIs, pode ligar soluções individuais ou ambientes inteiros a repositórios Git suportados e gerir essas ligações através de código.

Pré-requisitos

Antes de usar estas APIs, certifique-se de que tem:

• Acesso a um ambiente Microsoft Dataverse
• Permissões de administrador do sistema
• Acesso de leitura e escrita a um repositório Git

ConnectToGit API

Cria uma ligação entre uma solução ou ambiente Dataverse e um repositório Git. Ao usar esta ligação, pode gerir o controlo de código-fonte dos seus componentes Dataverse.

Parâmetros

A ConnectToGit API aceita os seguintes parâmetros:

Parâmetro ConnectionType

O ConnectionType parâmetro controla se se deve ligar a todo o ambiente Dataverse ou a uma solução específica.

Parâmetro GitProvider

Use o GitProvider parâmetro para especificar o tipo de fornecedor Git que está a usar, seja Azure DevOps ou GitHub.

API DisconnectFromGit

Remove a ligação Git de uma solução ou ambiente Dataverse e desativa a integração com controlo de versão.

Parâmetro

A DisconnectFromGit API tem apenas um parâmetro.

Informações adicionais

Aqui estão algumas opções de valor de parâmetro para especificar ao invocar DisconnectFromGit.

• Desligar uma solução única: Fornecer SolutionUniqueName para desligar uma solução específica.
• Desligue todas as soluções: Não forneça parâmetros para desligar todas as ligações ao nível da solução.
• Desligar ambiente: Não forneça parâmetros para desligar a ligação ao nível do ambiente.

Exemplos

Os exemplos seguintes descrevem cenários para utilizar as APIs ConnectToGit e DisconnectFromGit:

• Ligue todo o seu ambiente Dataverse a um repositório Azure DevOps
• Liga-te a um repositório do GitHub
• Liga-te a um repositório do GitHub usando o PowerShell
• Desligar todo o seu ambiente do Dataverse do controlo de código fonte do Git
• Ligue a primeira solução a um repositório Git
• Liga soluções extra ao mesmo repositório Git depois de ligares a solução inicial
• Desligue uma solução específica do controlo de versões Git enquanto mantém as outras soluções ligadas

Ligue todo o seu ambiente Dataverse a um repositório Azure DevOps

Esta ligação permite a gestão de código-fonte para todas as configurações e componentes ao nível do ambiente.

Não uses estes parâmetros com esta ligação:

• RootFolder
• SolutionUniqueName
• UpstreamBranch

POST [Organization URI]/api/data/v9.2/ConnectToGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
   "GitFolder": "yourGitfolderName",
   "Branch": "yourBranchName",
   "ConnectionType": 1,
   "GitProvider": 0,
   "Organization": "yourOrganizationName",
   "Project": "yourProjectName",
   "Repository": "yourRepositoryName"
}

HTTP/1.1 204 No Content
OData-Version: 4.0

private const int GitProviderAzureDevOps = 0;
private const int GitProviderGitHub = 1;
private const int ConnectionTypeEnvironment = 1;

static void ConnectDataverseEnvironment(
    IOrganizationService service,
    string gitFolderName,
    string branchName,
    string organizationName,
    string projectName,
    string repositoryName,
    OptionSetValue? gitProvider = null)
{
    // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
    ArgumentException.ThrowIfNullOrWhiteSpace(organizationName);
    ArgumentException.ThrowIfNullOrWhiteSpace(projectName);
    ArgumentException.ThrowIfNullOrWhiteSpace(repositoryName);

    // Default to Azure Dev Ops
    gitProvider ??= new OptionSetValue(GitProviderAzureDevOps);

    ParameterCollection parameters = new()
    {
        { "GitFolder", gitFolderName },
        { "Branch", branchName },
        { "ConnectionType", new OptionSetValue(ConnectionTypeEnvironment) },
        { "GitProvider", gitProvider },
        { "Organization", organizationName },
        { "Project", projectName },
        { "Repository", repositoryName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "ConnectToGit",
        Parameters = parameters
    };

     service.Execute(request);
}

Liga-te a um repositório do GitHub

Antes de usar a API para se ligar ao GitHub, complete os passos de configuração para criar a aplicação GitHub, instale-a no repositório alvo, importe a chave privada para o Azure Key Vault e crie a ligação Power Platform ao GitHub. Para mais informações, consulte Ligar ao GitHub.

Crie um registo de configuração da aplicação GitHub usando a API Web

Utilize a API Web OData do Dataverse para criar um registo githubappconfig. Envie um pedido POST com o ID do cliente da aplicação GitHub, URI do Key Vault e nome da chave.

Pode usar qualquer cliente HTTP, como Insomnia, Visual Studio Code REST Client ou curl, para fazer estas chamadas. Precisas de um token portador para autenticação. Para mais informações, consulte Usar a API Web da Microsoft Dataverse.

POST {{DataverseOrgUrl}}/api/data/v9.2/githubappconfigs
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "githubappid": "Iv23liBWoH9sf7xDrRe6",
    "keyvaulturi": "{{KeyVaultUri}}",
    "keyname": "demoGitHubKey"
}

Após criar o registo de configuração da aplicação GitHub, atribui o papel de utilizador Key Vault Crypto à identidade gerida do Dataverse, conforme descrito no controlo de acesso baseado em papéis (RBAC) do Configure Key Vault.

Chamar a API ConnectToGit

Depois de criar o githubappconfig registo e configurar o RBAC do Key Vault, utilize a API Web do Dataverse para estabelecer a ligação ao controlo de código-fonte ao chamar a ação ConnectToGit.

POST {{DataverseOrgUrl}}/api/data/v9.2/ConnectToGit
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "GitProvider": 1,
    "ConnectionType": 1,
    "Organization": "YourGitHubOrg",
    "Repository": "YourRepo",
    "Project": "placeholder",
    "Branch": "yourBranch",
    "UpstreamBranch": "main",
    "GitFolder": "YourFolder",
    "GitHubConnectionId": "<connectionId>",
    "GitHubAppConfigId": "githubappconfigs(<recordId>)"
}

Se receber uma resposta bem-sucedida, o ambiente está ligado ao GitHub.

Liga-te a um repositório do GitHub usando o PowerShell

O exemplo seguinte do PowerShell cria o registo de configuração da aplicação GitHub, espera que a identidade gerida do Dataverse apareça no Microsoft Entra ID, atribui o papel de utilizador Key Vault Crypto à identidade gerida e chama a ConnectToGit ação. Se já tiver um registo de configuração do GitHub App, forneça GitHubAppConfigId para ignorar os passos de configuração e de atribuição de funções no Key Vault.

Instala e importa os módulos Az.Accounts, Az.KeyVault, e Az.Resources PowerShell antes de executares o exemplo. Inicie sessão com Connect-AzAccount usando uma conta que tenha acesso ao ambiente Dataverse e permissão para atribuir funções do Key Vault.

Se o suporte a rede virtual (VNET) estiver ativado para o ambiente Dataverse, forneça GitHubPAT. As ligações ao GitHub não podem ser usadas com suporte a redes virtuais.

[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [string]$DataverseOrgUrl,

    [Parameter(Mandatory)]
    [string]$GitHubOrg,

    [Parameter(Mandatory)]
    [string]$GitHubRepo,

    [Parameter(Mandatory)]
    [string]$Branch,

    [Parameter(Mandatory)]
    [string]$GitFolder,

    [string]$GitHubAppClientId,

    [string]$KeyVaultName,

    [string]$KeyVaultKeyName,

    [string]$GitHubAppConfigId,

    [string]$GitHubConnectionId,

    [string]$GitHubPAT,

    [ValidateSet(0, 1)]
    [int]$ConnectionType = 1,

    [string]$UpstreamBranch,

    [string]$RootFolder,

    [string]$SolutionUniqueName
)

Set-StrictMode -Version 3.0
$ErrorActionPreference = "Stop"

if (($GitHubConnectionId -and $GitHubPAT) -or (-not $GitHubConnectionId -and -not $GitHubPAT)) {
    throw "Specify either -GitHubConnectionId or -GitHubPAT, but not both."
}

if (-not $GitHubAppConfigId) {
    foreach ($name in @('GitHubAppClientId', 'KeyVaultName', 'KeyVaultKeyName')) {
        if ([string]::IsNullOrWhiteSpace((Get-Variable -Name $name -ValueOnly))) {
            throw "Specify -$name when -GitHubAppConfigId is not provided."
        }
    }
}

$dataverseResource = $DataverseOrgUrl.TrimEnd('/')
$tokenResult = Get-AzAccessToken -ResourceUrl $dataverseResource -AsSecureString
$dataverseToken = [System.Net.NetworkCredential]::new('', $tokenResult.Token).Password

function Invoke-DataverseApi {
    param(
        [Parameter(Mandatory)]
        [string]$Method,

        [Parameter(Mandatory)]
        [string]$Endpoint,

        [object]$Body,

        [switch]$ReturnHeaders
    )

    $headers = @{
        Authorization      = "Bearer $dataverseToken"
        "OData-MaxVersion" = "4.0"
        "OData-Version"    = "4.0"
    }

    $request = @{
        Method      = $Method
        Uri         = "$dataverseResource/api/data/v9.2/$Endpoint"
        Headers     = $headers
        ContentType = "application/json; charset=utf-8"
    }

    if ($Body) {
        $request.Body = $Body | ConvertTo-Json -Depth 10
    }

    if ($ReturnHeaders) {
        return (Invoke-WebRequest @request).Headers
    }

    Invoke-RestMethod @request
}

$appConfigRecordId = $GitHubAppConfigId

if (-not $appConfigRecordId) {
    $keyVault = Get-AzKeyVault -VaultName $KeyVaultName
    $keyVaultUri = 'https://' + $KeyVaultName + '.vault.azure.net/'

    $appConfigBody = @{
        githubappid = $GitHubAppClientId
        keyvaulturi = $keyVaultUri
        keyname     = $KeyVaultKeyName
    }

    $responseHeaders = Invoke-DataverseApi `
        -Method POST `
        -Endpoint "githubappconfigs" `
        -Body $appConfigBody `
        -ReturnHeaders

    $entityIdHeader = [string]$responseHeaders["OData-EntityId"]
    if ($entityIdHeader -notmatch '\(([0-9a-f-]+)\)') {
        throw "Could not read the GitHub App configuration record ID from the Dataverse response."
    }

    $appConfigRecordId = $Matches[1]
    $managedIdentityName = "PPMI-githubappconfigmanagedidentity-$appConfigRecordId"

    $servicePrincipal = $null
    for ($attempt = 1; $attempt -le 60; $attempt++) {
        $servicePrincipal = Get-AzADServicePrincipal -DisplayName $managedIdentityName -ErrorAction SilentlyContinue
        if ($servicePrincipal) {
            break
        }

        Start-Sleep -Seconds 1
    }

    if (-not $servicePrincipal) {
        throw "The Dataverse managed identity was not found in Microsoft Entra ID. Check Dataverse System Jobs for GitHub App configuration errors."
    }

    $keyVaultScope = $keyVault.ResourceId
    if (-not $keyVaultScope) {
        $subscriptionId = (Get-AzContext).Subscription.Id
        $keyVaultScope = "/subscriptions/$subscriptionId/resourceGroups/$($keyVault.ResourceGroupName)/providers/Microsoft.KeyVault/vaults/$KeyVaultName"
    }

    $keyVaultCryptoUserRoleId = "12338af0-0e69-4776-bea7-57ae8d297424"
    $existingAssignment = Get-AzRoleAssignment `
        -ObjectId $servicePrincipal.Id `
        -RoleDefinitionId $keyVaultCryptoUserRoleId `
        -Scope $keyVaultScope `
        -ErrorAction SilentlyContinue

    if (-not $existingAssignment) {
        New-AzRoleAssignment `
            -ObjectId $servicePrincipal.Id `
            -RoleDefinitionId $keyVaultCryptoUserRoleId `
            -Scope $keyVaultScope | Out-Null
    }
}

$connectBody = @{
    GitProvider          = 1
    ConnectionType       = $ConnectionType
    Organization         = $GitHubOrg
    Repository           = $GitHubRepo
    Project              = "placeholder"
    Branch               = $Branch
    GitFolder            = $GitFolder
    GitHubAppConfigId    = "githubappconfigs($appConfigRecordId)"
}

if ($GitHubConnectionId) { $connectBody.GitHubConnectionId = $GitHubConnectionId }
if ($GitHubPAT)          { $connectBody.GitHubPAT          = $GitHubPAT }
if ($UpstreamBranch)     { $connectBody.UpstreamBranch     = $UpstreamBranch }
if ($RootFolder)         { $connectBody.RootFolder         = $RootFolder }
if ($SolutionUniqueName) { $connectBody.SolutionUniqueName = $SolutionUniqueName }

Invoke-DataverseApi -Method POST -Endpoint "ConnectToGit" -Body $connectBody
Write-Host "Connected Dataverse Git integration to GitHub."

Desligue o ambiente Dataverse inteiro do controlo de origem Git

Esta ação remove a ligação Git ao nível do ambiente. Não uses o SolutionUniqueName parâmetro para esta operação. O Dataverse identifica e remove automaticamente a ligação Git ao nível do ambiente.

POST [Organization URI]/api/data/v9.2/DisconnectFromGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

HTTP/1.1 204 No Content
OData-Version: 4.0

static void DisconnectDataverseEnvironment(IOrganizationService service) {

   // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);

   OrganizationRequest request = new("DisconnectFromGit");

   service.Execute(request);

}

Ligue a primeira solução a um repositório Git

Esta ligação estabelece a ligação do repositório e da estrutura de pastas para o controlo de código fonte ao nível da solução para a primeira solução num ambiente.

É necessário incluir valores para estes parâmetros para especificar a solução:

• RootFolder
• SolutionUniqueName

POST [Organization URI]/api/data/v9.2/ConnectToGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
   "GitFolder": "yourGitfolderName",
   "Branch": "yourBranchName",
   "ConnectionType": 1,
   "GitProvider": 0,
   "Organization": "yourOrganizationName",
   "Project": "yourProjectName",
   "Repository": "yourRepositoryName",
   "RootFolder": "yourRootFolderName",
   "SolutionUniqueName": "yourSolutionUniqueName"
}

HTTP/1.1 204 No Content
OData-Version: 4.0

private const int ConnectionTypeSolution = 0;

static void ConnectFirstSolution(
    IOrganizationService service,
    string gitFolderName,
    string branchName,
    string organizationName,
    string projectName,
    string repositoryName,
    string rootFolderName,
    string solutionUniqueName,
    OptionSetValue? gitProvider = null)
{
    // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
    ArgumentException.ThrowIfNullOrWhiteSpace(organizationName);
    ArgumentException.ThrowIfNullOrWhiteSpace(projectName);
    ArgumentException.ThrowIfNullOrWhiteSpace(repositoryName);
    ArgumentException.ThrowIfNullOrWhiteSpace(rootFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

    // Default to Azure Dev Ops
    gitProvider ??= new OptionSetValue(GitProviderAzureDevOps);

    ParameterCollection parameters = new()
    {
        { "GitFolder", gitFolderName },
        { "Branch", branchName },
        { "ConnectionType", new OptionSetValue(ConnectionTypeSolution) },
        { "GitProvider", gitProvider },
        { "Organization", organizationName },
        { "Project", projectName },
        { "Repository", repositoryName },
        { "RootFolder", rootFolderName },
        { "SolutionUniqueName", solutionUniqueName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "ConnectToGit",
        Parameters = parameters
    };

    service.Execute(request);
}

Liga soluções extra ao mesmo repositório Git depois de ligares a solução inicial

Depois de conectar a primeira solução, só necessita dos parâmetros específicos dessa solução. Herdas os detalhes da ligação ao repositório da ligação inicial.

Defina apenas estes parâmetros:

• SolutionUniqueName
• Branch
• GitFolder

POST [Organization URI]/api/data/v9.2/ConnectToGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
   "GitFolder": "yourGitfolderName",
   "Branch": "yourBranchName",
   "SolutionUniqueName": "yourSolutionUniqueName"
}

HTTP/1.1 204 No Content
OData-Version: 4.0

static void ConnectExtraSolution(
   IOrganizationService service,
   string gitFolderName,
   string branchName,
   string solutionUniqueName)
{
   // Validate required parameters
   ArgumentNullException.ThrowIfNull(service);
   ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
   ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
   ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

   ParameterCollection parameters = new()
   {
         { "GitFolder", gitFolderName },
         { "Branch", branchName },
         { "SolutionUniqueName", solutionUniqueName }
   };

   OrganizationRequest request = new()
   {
         RequestName = "ConnectToGit",
         Parameters = parameters
   };

   service.Execute(request);
}

Desligue uma solução específica do controlo de versões Git enquanto mantém as outras soluções ligadas

Utilize esta abordagem para remover o controlo de origem de uma única solução sem afetar outras.

POST [Organization URI]/api/data/v9.2/DisconnectFromGit HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
   "SolutionUniqueName": "yourSolutionUniqueName"
}

HTTP/1.1 204 No Content
OData-Version: 4.0

static void DisconnectSolution(IOrganizationService service,
    string solutionUniqueName)
{

   // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

    ParameterCollection parameters = new()
    {
        { "SolutionUniqueName", solutionUniqueName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "DisconnectFromGit",
        Parameters = parameters
    };

    service.Execute(request);
}

Processamento de erros

Nem o ConnectToGit nem a DisconnectFromGit API devolvem um valor quando este é concluído com sucesso. Quando uma API falha, devolve um erro.

Cenários de erros comuns incluem:

• Credenciais inválidas: Certifique-se de que tem autenticação válida junto do fornecedor Git.
• Repositório não encontrado: Verifique os nomes da organização, projeto e repositório.
• Permissão negada: Certifique-se de que a sua conta Dataverse tem permissões de gestão de controlo de versão.
• Solução não encontrada: Verifique se existe SolutionUniqueName no seu ambiente.
• Ramo não existe: Confirme que o ramo especificado existe no repositório.

Apoio e recursos adicionais

Para mais informações sobre a integração do controlo de código-fonte com o Dataverse, consulte:

• Visão geral da integração do Git na Power Platform
• Ação ConnectToGit
• Ação de DisconnectFromGit
• Ação CommitToGit
• Ação RefreshChangesFromGit
• Ação PullChangesFromGit