Conecta e desconecta Dataverse dun repositorio Git usando código

Usa as ConnectToGit APIs e DisconnectFromGit para integrar programáticamente o teu entorno Microsoft Dataverse co control de versións de Git. Ao usar estas APIs, podes conectar solucións individuais ou contornos enteiros a repositorios Git soportados e xestionar esas conexións mediante código.

Requisitos previos

Antes de usar estas APIs, asegúrate de ter:

  • Acceso a un entorno Microsoft Dataverse
  • Permisos de administrador do sistema
  • Acceso de lectura e escritura a un repositorio Git

ConnectToGit API

Crea unha conexión entre unha solución ou entorno Dataverse e un repositorio Git. Usando esta conexión, podes xestionar o control de versións dos teus compoñentes de Dataverse.

Parámetros

A ConnectToGit API acepta os seguintes parámetros:

Parámetro Tipo Necesario Descripción
GitFolder String Si Nome da carpeta á que queres vincular a túa solución ou ambiente.
Branch String Si Nome da sucursal á que queres conectar.
ConnectionType Enteiro Non Especifica a que conectar. Ver parámetro ConnectionType.
GitProvider Enteiro Non O provedor Git. Ver parámetro GitProvider.
Organization String Non Nome da organización coa que queres conectarte.
Project String Non Nome do proxecto ao que queres conectar.
Repository String Non Nome do repositorio ao que queres conectarte.
RootFolder String Non Nome da carpeta raíz onde residen todas as túas solucións no ámbito da solución.
SolutionUniqueName String Non O nome único da solución que queres conectar con git.
UpstreamBranch String Non Nome da ramificación río arriba á que queres conectar. Por defecto a rama predeterminada do repositorio.
GitHubConnectionId String Non ID de conexión para a conexión Power Platform GitHub. É obrigatorio cando GitProvider é 1 a menos que proporciones GitHubPAT. Non se pode usar cando o soporte para rede virtual (VNET) está activado para o entorno Dataverse.
GitHubPAT String Non Token de acceso persoal de GitHub con acceso ao repositorio obxectivo. É obrigatorio cando GitProvider é 1 a menos que proporciones GitHubConnectionId. É necesario cando se habilita o soporte para redes virtuais (VNET) no entorno Dataverse.
GitHubAppConfigId String Non Referencia ao rexistro de configuración da aplicación GitHub. Requirido cando GitProvider é 1. Usa o formato githubappconfigs(<recordId>).

Parámetro ConnectionType

O ConnectionType parámetro controla se conectar a todo o entorno Dataverse ou a unha solución específica.

Valor Etiqueta Descripción
0 Solución Conecta unha solución específica de Dataverse con Git.
1 Ambiente Conecta todo o entorno Dataverse con Git.

Parámetro GitProvider

Usa o GitProvider parámetro para especificar o tipo de provedor Git que estás a usar, xa sexa Azure DevOps ou GitHub.

Valor Etiqueta Descripción
0 Azure DevOps Use para repositorios aloxados en Azure DevOps
1 GitHub Uso para repositorios aloxados en GitHub

DisconnectFromGit API

Elimina a conexión Git dunha solución ou entorno Dataverse e desactiva a integración do control de versión.

Parámetro

A DisconnectFromGit API só ten un parámetro.

Parámetro Tipo Necesario Descripción
SolutionUniqueName String Non O nome único da solución que queres desconectar de Git. Evita desconectar todas as solucións ou o medio ambiente.

Información adicional

Aquí tes algunhas opcións de valor de parámetro para especificar ao invocar DisconnectFromGit.

  • Desconectar unha solución única: Proporcionar SolutionUniqueName para desconectar unha solución específica.
  • Desconecte todas as solucións: Non proporcione parámetros para desconectar todas as conexións a nivel de solución.
  • Desconectar o ambiente: Non proporcionar parámetros para desconectar a conexión a nivel de ambiente.

Exemplos

Os seguintes exemplos describen escenarios para o uso das ConnectToGit APIs de e DisconnectFromGit :

Conecta todo o teu entorno Dataverse a un repositorio Azure DevOps

Esta conexión permite o control de versións para todas as configuracións e compoñentes a nivel de ambiente.

Non uses estes parámetros con esta conexión:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Este exemplo mostra como usar a acción ConnectToGit para conectar todo o teu entorno Dataverse a un repositorio Azure DevOps.

Solicitude

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"
}

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprende a invocar accións da API web

Conéctate a un repositorio de GitHub

Antes de usar a API para conectarte a GitHub, completa os pasos de configuración para crear a aplicación GitHub, instálaa no repositorio destino, importa a súa clave privada en Azure Key Vault e crea a conexión Power Platform GitHub. Para máis información, véxase Conectar a GitHub.

Crea un rexistro de configuración de GitHub App usando a API web

Usa a API web de Dataverse OData para crear un githubappconfig rexistro. Envía unha solicitude POST co ID do cliente da aplicación GitHub, o URI de Key Vault e o nome da clave.

Podes usar calquera cliente HTTP, como Insomnia, Visual Studio Code REST Client ou curl, para facer estas chamadas. Necesitas un token portador para autenticación. Para máis información, véxase Usar a API Web de Microsoft Dataverse.

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

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

Importante

Nota o ID do rexistro devolto na cabeceira de resposta. Necesitas este valor para identificar a identidade xestionada, configurar RBAC e chamar ConnectToGita . O ID do rexistro usa un formato como 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Despois de crear o rexistro de configuración da aplicación GitHub, asigna o rol de usuario Key Vault Crypto á identidade xestionada de Dataverse tal e como se describe no control de acceso baseado en roles (RBAC) de Configure Key Vault.

Chama á API de ConnectToGit

Despois de crear o githubappconfig rexistro e configurar Key Vault RBAC, usa a API web de Dataverse para establecer a conexión de control de versións chamando á ConnectToGit acción.

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>)"
}

Importante

A rama debe existir xa no repositorio. Créao primeiro en GitHub se é necesario. O GitHubAppConfigId valor debe usar o formato githubappconfigs(<recordId>).

Captura de pantalla do corpo dunha petición HTTP para a API de ConnectToGit con parámetros de GitHub.

Se recibes unha resposta exitosa, o entorno conéctase a GitHub.

Conéctate a un repositorio de GitHub usando PowerShell

O seguinte exemplo de PowerShell crea o rexistro de configuración da aplicación GitHub, espera a que apareza a identidade xestionada Dataverse no Microsoft Entra ID, asigna o rol de usuario Key Vault Crypto á identidade xestionada e chama á ConnectToGit acción. Se xa tes un rexistro de configuración de GitHub App, proporciona GitHubAppConfigId para saltar os pasos de configuración e asignación de roles de Key Vault.

Instala e importa os módulos Az.Accounts, Az.KeyVault, e Az.Resources PowerShell antes de executar o exemplo. Inicia Connect-AzAccount sesión usando unha conta que teña acceso ao entorno Dataverse e permiso para asignar roles de Key Vault.

Se o soporte para rede virtual (VNET) está habilitado para o entorno Dataverse, proporciona GitHubPAT. As conexións de GitHub non se poden usar con soporte para 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."

Desconecta todo o teu entorno Dataverse do control de versións de Git

Esta acción elimina a conexión Git a nivel de ambiente. Non uses o SolutionUniqueName parámetro para esta operación. Dataverse identifica e elimina automaticamente a conexión Git a nivel de ambiente.

Este exemplo mostra como usar a acción DisconnectFromGit para desconectar todo o teu entorno Dataverse do control de versións de Git.

Solicitude

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

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprende a invocar accións da API web

Conecta a primeira solución a un repositorio Git

Esta conexión establece a estrutura de ligazóns e carpetas do repositorio para o control de versión a nivel de solución para a primeira solución nun entorno.

Necesitas incluír valores para estes parámetros para especificar a solución:

  • RootFolder
  • SolutionUniqueName

Este exemplo mostra como usar a acción ConnectToGit para conectar a primeira solución a un repositorio Git.

Solicitude

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"
}

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprende a invocar accións da API web

Conecta solucións extra ao mesmo repositorio Git despois de conectar a solución inicial

Despois de conectar a primeira solución, só necesitas os parámetros específicos da solución. Herdas os detalles da conexión do repositorio desde a conexión inicial.

Establece só estes parámetros:

  • SolutionUniqueName
  • Branch
  • GitFolder

Importante

Primeiro debes conectar a primeira solución antes de que isto funcione. Ver Conectar a primeira solución a un repositorio Git.

Este exemplo mostra como usar a acción ConnectToGit para conectar solucións posteriores a un repositorio Git.

Solicitude

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"
}

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprende a invocar accións da API web

Desconecta unha solución específica do control de código Git mantendo outras solucións conectadas

Usa este enfoque para eliminar o control de versións dunha solución sen afectar ás outras.

Este exemplo mostra como usar a acción DisconnectFromGit para eliminar o control de versións dunha solución sen afectar a outras.

Solicitude

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"
}

Resposta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprende a invocar accións da API web

Manexo de erros

Nin a ConnectToGit API DisconnectFromGit nin a API devolven valor cando se completa con éxito. Cando unha API falla, devolve un erro.

Os escenarios de erro máis comúns inclúen:

  • Credenciais inválidas: Asegúrate de ter unha autenticación válida co provedor Git.
  • Repositorio non atopado: Verifica os nomes da organización, proxecto e repositorio.
  • Permiso denegado: Asegúrate de que a túa conta de Dataverse teña permisos de xestión de control de versión.
  • Solución non atopada: Verifica que SolutionUniqueName existe no teu entorno.
  • A rama non existe: Confirme que a rama especificada existe no repositorio.

Apoio e recursos adicionais

Para máis información sobre a integración do control de versións con Dataverse, véxase: