Conectar e desconectar o Dataverse de um repositório Git usando código

Use as APIs ConnectToGit e DisconnectFromGit para integrar programaticamente seu ambiente do Microsoft Dataverse ao controle do código-fonte do Git. Usando essas APIs, você pode conectar soluções individuais ou ambientes inteiros a repositórios Git compatíveis e gerenciar essas conexões por meio do código.

Pré-requisitos

Antes de usar essas APIs, verifique se você tem:

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

ConnectToGit API

Cria uma conexão entre uma solução ou ambiente do Dataverse e um repositório Git. Usando essa conexão, você pode gerenciar o controle do código-fonte para seus componentes do Dataverse.

Parâmetros

A ConnectToGit API aceita os seguintes parâmetros:

Parâmetro ConnectionType

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

Parâmetro GitProvider

Use o GitProvider parâmetro para especificar o tipo de provedor Git que você está usando, o Azure DevOps ou o GitHub.

DisconnectFromGit API (Desconectar do Git API)

Remove a conexão Git de uma solução ou ambiente do Dataverse e desabilita a integração do controle do código-fonte.

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.

• Desconectar solução única: forneça SolutionUniqueName para desconectar uma solução específica.
• Desconecte todas as soluções: não forneça parâmetros para desconectar todas as conexões no nível da solução.
• Desconectar o ambiente: não forneça parâmetros para desconectar a conexão no nível do ambiente.

Exemplos

Os exemplos a seguir descrevem cenários de uso das APIs DisconnectFromGit e ConnectToGit:

• Conectar todo o ambiente do Dataverse a um repositório do Azure DevOps
• Conectar-se a um repositório GitHub
• Conectar-se a um repositório GitHub usando o PowerShell
• Desconectar todo o ambiente do Dataverse do controle de origem do Git
• Conectar a primeira solução a um repositório Git
• Conectar soluções extras ao mesmo repositório Git depois de conectar a solução inicial
• Desconectar uma solução específica do controle do código-fonte git mantendo outras soluções conectadas

Conectar todo o ambiente do Dataverse a um repositório do Azure DevOps

Essa conexão permite o controle do código-fonte para todas as configurações e componentes de nível de ambiente.

Não use esses parâmetros com esta conexã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);
}

Conectar-se a um repositório GitHub

Antes de usar a API para se conectar ao GitHub, conclua as etapas de instalação para criar o aplicativo GitHub, instale-o no repositório de destino, importe sua chave privada para Azure Key Vault e crie a conexão GitHub do Power Platform. Para obter mais informações, consulte Conectar-se ao GitHub.

Criar um registro de configuração de aplicativo GitHub usando a API Web

Use a API Web OData do Dataverse para criar um githubappconfig registro. Envie uma solicitação POST com a ID do cliente do aplicativo GitHub, Key Vault URI e o nome da chave.

Você pode usar qualquer cliente HTTP, como Insônia, Visual Studio Code cliente REST ou curl, para fazer essas chamadas. Você precisa de um token de portador para autenticação. Para obter mais informações, consulte Usar a API Web Microsoft Dataverse.

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

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

Depois de criar o registro de configuração do aplicativo GitHub, atribua a função Key Vault Usuário de Criptografia à identidade gerenciada do Dataverse, conforme descrito em Configurar Key Vault RBAC (controle de acesso baseado em função).

Chamar a API ConnectToGit

Depois de criar o registro githubappconfig e configurar o RBAC do Key Vault, use a API Web do Dataverse para estabelecer a conexão com o controle 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 você receber uma resposta bem-sucedida, o ambiente será conectado a GitHub.

Conectar-se a um repositório GitHub usando o PowerShell

O exemplo do PowerShell a seguir cria o registro de configuração do GitHub App, aguarda que a identidade gerenciada do Dataverse apareça em Microsoft Entra ID, atribui a função Key Vault Usuário de Criptografia à identidade gerenciada e chama a açãoConnectToGit. Se você já tiver um registro de configuração de um GitHub App, forneça GitHubAppConfigId para ignorar as etapas de configuração e de atribuição de função do Key Vault.

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

Se o suporte à VNET (rede virtual) estiver habilitado para o ambiente do Dataverse, forneça GitHubPAT. As conexões do GitHub não podem ser usadas com suporte à rede virtual.

[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."

Desconectar todo o ambiente do Dataverse do controle de origem do Git

Essa ação remove a conexão Git no nível do ambiente. Não use o SolutionUniqueName parâmetro para esta operação. O Dataverse identifica e remove automaticamente a conexão Git no 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);

}

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

Essa conexão estabelece o link do repositório e a estrutura de pastas para o controle do código-fonte no nível da solução para a primeira solução em um ambiente.

Você precisa incluir valores para esses 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);
}

Conectar soluções extras ao mesmo repositório Git depois de conectar a solução inicial

Depois de conectar a primeira solução, você só precisará dos parâmetros específicos da solução. Você herda os detalhes da conexão do repositório a partir da conexã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);
}

Desconectar uma solução específica do controle do código-fonte git mantendo outras soluções conectadas

Use essa abordagem para remover o controle do código-fonte de uma 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);
}

Tratamento de erros

Nem a ConnectToGit API nem a DisconnectFromGit API retornam um valor quando são concluídas com êxito. Quando uma API falha, ela retorna um erro.

Cenários de erro comuns incluem:

• Credenciais inválidas: verifique se você tem autenticação válida para o provedor Git.
• Repositório não encontrado: verifique os nomes da organização, do projeto e do repositório.
• Permissão negada: verifique se sua conta do Dataverse tem permissões de gerenciamento de controle do código-fonte.
• Solução não encontrada: verifique se SolutionUniqueName existe em seu ambiente.
• Branch não existe: Confirme se o ramo especificado existe no repositório.

Suporte e recursos adicionais

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

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