Connecta i desconnecta Dataverse d'un repositori Git utilitzant codi

Utilitza les ConnectToGit API de AND DisconnectFromGit per integrar programàticament el teu entorn Microsoft Dataverse amb el control de versions de Git. Utilitzant aquestes APIs, pots connectar solucions individuals o entorns sencers a repositoris Git compatibles i gestionar aquestes connexions mitjançant codi.

Requisits previs

Abans d'utilitzar aquestes APIs, assegura't que tens:

  • Accés a un entorn Microsoft Dataverse
  • Permisos d'administrador del sistema
  • Accés de lectura i escriptura a un repositori Git

ConnectToGit API

Crea una connexió entre una solució o entorn Dataverse i un repositori Git. Utilitzant aquesta connexió, pots gestionar el control de versions dels teus components de Dataverse.

Paràmetres

L'API ConnectToGit accepta els següents paràmetres:

Paràmetre Tipus Necessari Descripció
GitFolder String Sí Nom de la carpeta a la qual vols vincular la teva solució o entorn.
Branch String Sí Nom de la sucursal a la qual vols connectar-te.
ConnectionType Enter No Especifica a què s'ha de connectar. Vegeu el paràmetre ConnectionType.
GitProvider Enter No El proveïdor Git. Vegeu el paràmetre GitProvider.
Organization String No Nom de l'organització amb la qual vols connectar-te.
Project String No Nom del projecte al qual vols connectar.
Repository String No Nom del repositori al qual vols connectar-te.
RootFolder String No Nom de la carpeta arrel on resideixen totes les teves solucions dins l'abast de la solució.
SolutionUniqueName String No El nom únic de la solució que vols connectar a git.
UpstreamBranch String No Nom de la branca amunt a la qual vols connectar-te. Per defecte la branca predeterminada del repositori.
GitHubConnectionId String No ID de connexió per a la connexió GitHub de Power Platform. És obligatori quan GitProvider és 1 tret que proporcionis GitHubPAT. No es pot utilitzar quan el suport de xarxa virtual (VNET) està activat per a l'entorn Dataverse.
GitHubPAT String No Token d'accés personal de GitHub amb accés al repositori de destinació. És obligatori quan GitProvider és 1 tret que proporcionis GitHubConnectionId. És necessari quan el suport de xarxa virtual (VNET) està activat per a l'entorn Dataverse.
GitHubAppConfigId String No Referència al registre de configuració de l'aplicació de GitHub. És necessari quan GitProvider és 1. Utilitza el format githubappconfigs(<recordId>).

Paràmetre ConnectionType

El ConnectionType paràmetre controla si s'ha de connectar a tot l'entorn Dataverse o a una solució específica.

Valor Etiqueta Descripció
0 Solució Connecta una solució específica de Dataverse amb Git.
1 Entorn Connecta tot l'entorn Dataverse a Git.

Paràmetre GitProvider

Utilitza el GitProvider paràmetre per especificar el tipus de proveïdor Git que utilitzes, ja sigui Azure DevOps o GitHub.

Valor Etiqueta Descripció
0 Azure DevOps Ús per a repositoris allotjats a Azure DevOps
1 GitHub Ús per a repositoris allotjats a GitHub

DisconnectFromGit API

Elimina la connexió Git d'una solució o entorn Dataverse, i desactiva la integració amb control de versions.

Paràmetre

L'API DisconnectFromGit només té un paràmetre.

Paràmetre Tipus Necessari Descripció
SolutionUniqueName String No El nom únic de la solució que vols desconnectar de Git. Evita desconnectar totes les solucions o l'entorn.

Informació addicional

Aquí tens algunes opcions de valor de paràmetre per especificar quan s'invoca DisconnectFromGit.

  • Desconnectar una solució única: Proporcionar SolutionUniqueName per desconnectar una solució específica.
  • Desconnectar totes les solucions: No proporcionar cap paràmetre per desconnectar totes les connexions a nivell de solució.
  • Desconnectar l'entorn: No proporcionar paràmetres per desconnectar la connexió a nivell d'entorn.

Exemples

Els exemples següents descriuen escenaris per utilitzar les ConnectToGit API de i (i DisconnectFromGit aquests):

Connecta tot el teu entorn Dataverse a un repositori Azure DevOps

Aquesta connexió permet el control de versions per a totes les configuracions i components a nivell d'entorn.

No utilitzis aquests paràmetres amb aquesta connexió:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Aquest exemple mostra com utilitzar l'acció ConnectToGit per connectar tot el teu entorn Dataverse a un repositori Azure DevOps.

Demanar

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

Aprèn a invocar accions de l'API web

Connecta't a un repositori de GitHub

Abans d'utilitzar l'API per connectar-te a GitHub, completa els passos de configuració per crear l'aplicació GitHub, instal·la-la al repositori objectiu, importa la seva clau privada a Azure Key Vault i crea la connexió Power Platform GitHub. Per a més informació, vegeu Connect to GitHub.

Crea un registre de configuració de l'aplicació GitHub utilitzant l'API web

Utilitza l'API web Dataverse OData per crear un githubappconfig registre. Envia una sol·licitud POST amb l'ID del client de l'aplicació GitHub, l'URI de Key Vault i el nom de la clau.

Pots utilitzar qualsevol client HTTP, com Insomnia, Visual Studio Code REST Client o curl, per fer aquestes trucades. Necessites un testimoni portador per a l'autenticació. Per a més informació, vegeu Utilitza l'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"
}

Important

Fixeu-vos en l'ID de registre retornat a la capçalera de resposta. Necessites aquest valor per identificar la identitat gestionada, configurar RBAC i cridar ConnectToGit. L'ID de registre utilitza un format com 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Després de crear el registre de configuració de l'aplicació GitHub, assigna el rol d'usuari Key Vault Crypto a la identitat gestionada de Dataverse, tal com es descriu a Configure Key Vault basat en el control d'accés basat en rols (RBAC).

Truca a l'API de ConnectToGit

Després de crear el githubappconfig registre i configurar Key Vault RBAC, utilitza l'API web de Dataverse per establir la connexió de control de versions cridant l'acció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>)"
}

Important

La branca ja ha d'existir al repositori. Crea'l primer a GitHub si cal. El GitHubAppConfigId valor ha d'utilitzar el format githubappconfigs(<recordId>).

Captura de pantalla d'un cos de petició HTTP per a l'API ConnectToGit amb paràmetres de GitHub.

Si reps una resposta exitosa, l'entorn està connectat a GitHub.

Connecta't a un repositori de GitHub utilitzant PowerShell

L'exemple següent de PowerShell crea el registre de configuració de l'aplicació GitHub, espera que aparegui la identitat gestionada de Dataverse a Microsoft Entra ID, assigna el rol d'usuari Key Vault Crypto a la identitat gestionada i crida l'accióConnectToGit. Si ja tens un registre de configuració de l'aplicació de GitHub, proporciona GitHubAppConfigId per saltar els passos de configuració i assignació de rols de Key Vault.

Instal·la i importa els Az.Accountsmòduls , Az.KeyVault, i Az.Resources PowerShell abans d'executar l'exemple. Inicia sessió utilitzant Connect-AzAccount un compte que tingui accés a l'entorn Dataverse i permís per assignar rols a Key Vault.

Si el suport per a xarxes virtuals (VNET) està activat per a l'entorn Dataverse, proporciona GitHubPAT. Les connexions a GitHub no es poden utilitzar amb suport de xarxa 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."

Desconnecta tot l'entorn Dataverse del control de versions de Git

Aquesta acció elimina la connexió Git a nivell d'entorn. No utilitzis el SolutionUniqueName paràmetre per a aquesta operació. Dataverse identifica i elimina automàticament la connexió Git a nivell d'entorn.

Aquest exemple mostra com utilitzar l'acció DisconnectFromGit per desconnectar tot l'entorn Dataverse del control de versions de Git.

Demanar

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

Aprèn a invocar accions de l'API web

Connecta la primera solució a un repositori Git

Aquesta connexió estableix l'enllaç del repositori i l'estructura de carpetes per al control de versions a nivell de solució per a la primera solució en un entorn.

Cal incloure valors per a aquests paràmetres per especificar la solució:

  • RootFolder
  • SolutionUniqueName

Aquest exemple mostra com utilitzar l'acció ConnectToGit per connectar la primera solució a un repositori Git.

Demanar

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

Aprèn a invocar accions de l'API web

Connecta solucions addicionals al mateix repositori Git després de connectar la solució inicial

Després de connectar la primera solució, només necessites els paràmetres específics de la solució. S'hereten els detalls de la connexió del repositori de la connexió inicial.

Fixa només aquests paràmetres:

  • SolutionUniqueName
  • Branch
  • GitFolder

Important

Primer has de connectar la primera solució abans que això funcioni. Vegeu Connecta la primera solució a un repositori Git.

Aquest exemple mostra com utilitzar l'acció ConnectToGit per connectar solucions posteriors a un repositori Git.

Demanar

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

Aprèn a invocar accions de l'API web

Desconnecta una solució específica del control de versions de Git mentre mantens les altres solucions connectades

Utilitza aquest enfocament per eliminar el control de versions d'una solució sense afectar les altres.

Aquest exemple mostra com utilitzar l'acció DisconnectFromGit per eliminar el control de versions d'una solució sense afectar les altres.

Demanar

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

Aprèn a invocar accions de l'API web

Gestió d'errors

Ni l'API ConnectToGit ni l'API DisconnectFromGit retornen un valor quan es completa amb èxit. Quan una API falla, retorna un error.

Els escenaris d'error més comuns inclouen:

  • Credencials invàlides: Assegura't de tenir una autenticació vàlida amb el proveïdor Git.
  • Repositori no trobat: Verifica els noms de l'organització, projecte i repositori.
  • Permís denegat: Assegura't que el teu compte de Dataverse tingui permisos de gestió de control de versions.
  • Solució no trobada: Verifica que existeixi SolutionUniqueName al teu entorn.
  • La branca no existeix: Confirma que la branca especificada existeix al repositori.

Suport i recursos addicionals

Per a més informació sobre la integració del control de versions amb Dataverse, vegeu: