Conexión y desconexión de Dataverse desde un repositorio de Git mediante código

Use las ConnectToGit API y DisconnectFromGit para integrar mediante programación el entorno de Microsoft Dataverse con el control de código fuente de Git. Mediante estas API, puede conectar soluciones individuales o entornos completos a repositorios de Git compatibles y administrar esas conexiones a través del código.

Prerrequisitos

Antes de usar estas API, asegúrese de que tiene:

  • Acceso a un entorno de Microsoft Dataverse
  • Permisos de administrador del sistema
  • Acceso de lectura y escritura a un repositorio de Git

ConnectToGit API

Crea una conexión entre una solución o un entorno de Dataverse y un repositorio de Git. Mediante esta conexión, puede administrar el control de código fuente para los componentes de Dataverse.

Parámetros

La ConnectToGit API acepta los parámetros siguientes:

Parámetro Tipo Obligatorio Descripción
GitFolder Cuerda Nombre de la carpeta a la que desea enlazar la solución o el entorno.
Branch Cuerda Nombre de la rama a la que desea conectarse.
ConnectionType Entero No Especifica a qué conectarse. Consulte Parámetro ConnectionType.
GitProvider Entero No Proveedor de Git. Consulte el parámetro GitProvider.
Organization Cuerda No Nombre de la organización a la que desea conectarse.
Project Cuerda No Nombre del proyecto al que desea conectarse.
Repository Cuerda No Nombre del repositorio al que desea conectarse.
RootFolder Cuerda No Nombre de la carpeta raíz donde residen todas las soluciones en el ámbito de la solución.
SolutionUniqueName Cuerda No Nombre único de la solución que desea conectar a Git.
UpstreamBranch Cuerda No Nombre de la rama ascendente a la que desea conectarse. El valor por defecto es la rama predeterminada del repositorio.
GitHubConnectionId Cuerda No Identificador de conexión para la conexión GitHub de Power Platform. Obligatorio cuando GitProvider es 1 a menos que proporcione GitHubPAT. No se puede usar cuando la compatibilidad con la red virtual (VNET) está habilitada para el entorno de Dataverse.
GitHubPAT Cuerda No token de acceso personal de GitHub con acceso al repositorio de destino. Obligatorio cuando GitProvider es 1 a menos que proporcione GitHubConnectionId. Se requiere cuando la compatibilidad con la red virtual (VNET) está habilitada para el entorno de Dataverse.
GitHubAppConfigId Cuerda No Referencia al registro de configuración de la aplicación de GitHub. Obligatorio cuando GitProvider es 1. Use el formato githubappconfigs(<recordId>).

Parámetro de ConnectionType

El ConnectionType parámetro controla si se va a conectar a todo el entorno de Dataverse o a una solución específica.

Value Etiqueta Descripción
0 Solución Conecta una solución específica de Dataverse a Git.
1 Ambiente Conecta todo el entorno de Dataverse a Git.

Parámetro GitProvider

Use el GitProvider parámetro para especificar el tipo de proveedor de Git que usa, ya sea Azure DevOps o GitHub.

Value Etiqueta Descripción
0 Azure DevOps Uso de repositorios hospedados en Azure DevOps
1 GitHub Uso para repositorios hospedados en GitHub

DesconectarDeGit API

Quita la conexión de Git de una solución o entorno de Dataverse y deshabilita la integración del control de código fuente.

Parámetro

La DisconnectFromGit API solo tiene un parámetro.

Parámetro Tipo Obligatorio Descripción
SolutionUniqueName Cuerda No Nombre único de la solución que desea desconectar de Git. Omita para desconectar todas las soluciones o el entorno.

Información adicional

Estas son algunas opciones de valor de parámetro que se deben especificar al invocar DisconnectFromGit.

  • Desconectar solución única: proporcione SolutionUniqueName para desconectar una solución específica.
  • Desconectar todas las soluciones: no proporcione ningún parámetro para desconectar todas las conexiones de nivel de solución.
  • Desconectar entorno: No proporcione ningún parámetro para desconectar la conexión a nivel de entorno.

Examples

En los ejemplos siguientes se describen escenarios para usar las ConnectToGit API y DisconnectFromGit :

Conexión de todo el entorno de Dataverse a un repositorio de Azure DevOps

Esta conexión habilita el control de código fuente para todas las configuraciones y componentes de nivel de entorno.

No use estos parámetros con esta conexión:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

En este ejemplo se muestra cómo usar la acción ConnectToGit para conectar todo el entorno de Dataverse a un repositorio de Azure DevOps.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprenda a invocar acciones de API web

Conexión a un repositorio de GitHub

Antes de usar la API para conectarse a GitHub, complete los pasos de configuración para crear la aplicación GitHub, instalarla en el repositorio de destino, importar su clave privada en Azure Key Vault y crear la conexión de Power Platform GitHub. Para obtener más información, consulte Conexión a GitHub.

Creación de un registro de configuración de aplicación GitHub mediante la API web

Use la API web de OData de Dataverse para crear un githubappconfig registro. Envíe una solicitud POST con el identificador de cliente de la aplicación de GitHub, Key Vault URI y el nombre de clave.

Puede usar cualquier cliente HTTP, como Insomnio, Visual Studio Code cliente REST o curl, para realizar estas llamadas. Necesita un token de portador para la autenticación. Para obtener más información, consulte Uso de la 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

Anote el identificador de registro devuelto en el encabezado de respuesta. Necesita este valor para identificar la identidad administrada, configurar RBAC y llamar a ConnectToGit. El identificador de registro usa un formato como 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Después de crear el registro de configuración de la aplicación de GitHub, asigne el rol Usuario de cifrado de Key Vault a la identidad administrada de Dataverse, tal como se describe en Configurar el control de acceso basado en rol (RBAC) de Key Vault.

Llamar a la API ConnectToGit

Después de crear el registro githubappconfig y configurar Key Vault RBAC, use la API web de Dataverse para establecer la conexión al control de código fuente llamando a la acción 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>)"
}

Importante

La rama ya debe existir en el repositorio. Créelo en GitHub primero si es necesario. El GitHubAppConfigId valor debe usar el formato githubappconfigs(<recordId>).

Captura de pantalla del cuerpo de una solicitud HTTP para connectToGit API con parámetros de GitHub.

Si recibe una respuesta correcta, el entorno se conecta a GitHub.

Conexión a un repositorio de GitHub mediante PowerShell

En el siguiente ejemplo de PowerShell se crea el registro de configuración de la aplicación de GitHub, se espera a que la identidad administrada de Dataverse aparezca en Microsoft Entra ID, se asigna el rol Usuario de criptografía de Key Vault a la identidad administrada y se invoca la acción ConnectToGit. Si ya tiene un registro de configuración de GitHub App, proporcione GitHubAppConfigId para omitir los pasos de configuración y asignación de roles de Key Vault.

Instale e importe los módulos de PowerShell Az.Accounts, Az.KeyVault y Az.Resources antes de ejecutar el ejemplo. Inicie sesión con Connect-AzAccount con una cuenta que tenga acceso al entorno de Dataverse y permisos para asignar roles de Key Vault.

Si la compatibilidad con la red virtual (VNET) está habilitada para el entorno de Dataverse, proporcione GitHubPAT. Las conexiones de GitHub no se pueden usar con compatibilidad con redes virtuales.

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

Desconecte todo el entorno de Dataverse del control de código fuente de Git.

Esta acción elimina la conexión de Git a nivel de entorno. No use el SolutionUniqueName parámetro para esta operación. Dataverse identifica y elimina automáticamente la conexión Git a nivel de entorno.

En este ejemplo se muestra cómo usar la acción DisconnectFromGit para desconectar todo el entorno de Dataverse del control de código fuente de Git.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprenda a invocar acciones de API web

Conexión de la primera solución a un repositorio de Git

Esta conexión establece el vínculo del repositorio y la estructura de carpetas para el control de código fuente a nivel de solución en la primera solución de un entorno.

Debe incluir valores para estos parámetros para especificar la solución:

  • RootFolder
  • SolutionUniqueName

En este ejemplo se muestra cómo usar la acción ConnectToGit para conectar la primera solución a un repositorio de Git.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprenda a invocar acciones de API web

Conexión de soluciones adicionales al mismo repositorio de Git después de conectar la solución inicial

Después de conectar la primera solución, solo necesita los parámetros específicos de la solución. Hereda los detalles de conexión al repositorio de la conexión inicial.

Establezca solo estos parámetros:

  • SolutionUniqueName
  • Branch
  • GitFolder

Importante

Debe conectar primero la solución inicial para que esto funcione. Consulte Conexión de la primera solución a un repositorio de Git.

En este ejemplo se muestra cómo usar la acción ConnectToGit para conectar soluciones posteriores a un repositorio de Git.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprenda a invocar acciones de API web

Desconecte una solución específica del control de código fuente de Git mientras mantiene conectadas otras soluciones

Use este enfoque para quitar el control de código fuente de una solución sin afectar a otros usuarios.

En este ejemplo se muestra cómo usar la acción DisconnectFromGit para quitar el control de código fuente de una solución sin afectar a otros.

Solicitud

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

Respuesta

HTTP/1.1 204 No Content
OData-Version: 4.0

Aprenda a invocar acciones de API web

Control de errores

Ni la API ConnectToGit ni la API DisconnectFromGit devuelven un valor cuando se completa correctamente. Cuando se produce un error en una API, devuelve un error.

Las situaciones de error más comunes son:

  • Credenciales no válidas: asegúrese de que tiene autenticación válida en el proveedor de Git.
  • Repositorio no encontrado: compruebe los nombres de organización, proyecto y repositorio.
  • Permiso denegado: asegúrese de que la cuenta de Dataverse tiene permisos de administración de control de código fuente.
  • Solución no encontrada: compruebe que SolutionUniqueName existe en su entorno.
  • La rama no existe: confirme que la rama especificada existe en el repositorio.

Soporte técnico y recursos adicionales

Para obtener más información sobre la integración del control de código fuente con Dataverse, consulte: