Verbinden und Trennen von Dataverse aus einem Git-Repository mithilfe von Code

Verwenden Sie die ConnectToGit- und DisconnectFromGit-APIs, um Ihre Microsoft Dataverse-Umgebung programmatisch in die Git-Quellverwaltung zu integrieren. Mithilfe dieser APIs können Sie einzelne Lösungen oder ganze Umgebungen mit unterstützten Git-Repositorys verbinden und diese Verbindungen über Code verwalten.

Voraussetzungen

Stellen Sie vor der Verwendung dieser APIs folgendes sicher:

• Zugriff auf eine Microsoft Dataverse-Umgebung
• Systemadministratorberechtigungen
• Lese- und Schreibzugriff auf ein Git-Repository

ConnectToGit-API

Erstellt eine Verbindung zwischen einer Dataverse-Lösung oder -Umgebung und einem Git-Repository. Mithilfe dieser Verbindung können Sie die Quellcodeverwaltung für Ihre Dataverse-Komponenten verwalten.

Parameters

Die ConnectToGit API akzeptiert die folgenden Parameter:

Verbindungstyp-Parameter

Der ConnectionType Parameter steuert, ob eine Verbindung mit der gesamten Dataverse-Umgebung oder einer bestimmten Lösung hergestellt werden soll.

GitProvider-Parameter

Verwenden Sie den GitProvider Parameter, um den Typ des verwendeten Git-Anbieters anzugeben, entweder Azure DevOps oder GitHub.

DisconnectFromGit-API

Entfernt die Git-Verbindung aus einer Dataverse-Lösung oder -Umgebung und deaktiviert die Integration der Quellcodeverwaltung.

Parameter

Die DisconnectFromGit API verfügt nur über einen Parameter.

Zusätzliche Informationen

Hier sind einige Parameterwertoptionen, die beim Aufrufen DisconnectFromGitangegeben werden sollen.

• Trennen einer einzelnen Lösung: Verwenden Sie SolutionUniqueName, um eine spezifische Lösung zu trennen.
• Trennen Sie alle Lösungen: Stellen Sie keine Parameter bereit, um alle Verbindungen auf Lösungsebene zu trennen.
• Umgebung trennen: Geben Sie keine Parameter an, um die Verbindung auf Umgebungsebene zu trennen.

Beispiele

Die folgenden Beispiele beschreiben Szenarien für die Verwendung der ConnectToGit und DisconnectFromGit APIs:

• Verbinden Ihrer gesamten Dataverse-Umgebung mit einem Azure DevOps-Repository
• Herstellen einer Verbindung mit einem GitHub Repository
• Herstellen einer Verbindung mit einem GitHub-Repository mithilfe von PowerShell
• Trennen Sie Ihre gesamte Dataverse-Umgebung von der Git-Versionsverwaltung
• Verbinden der ersten Lösung mit einem Git-Repository
• Verbinden zusätzlicher Lösungen mit dem gleichen Git-Repository, nachdem Sie die erste Lösung verbunden haben
• Trennen einer bestimmten Lösung aus der Git-Quellcodeverwaltung, während andere Lösungen verbunden bleiben

Verbinden Ihrer gesamten Dataverse-Umgebung mit einem Azure DevOps-Repository

Diese Verbindung ermöglicht die Quellcodeverwaltung für alle Konfigurationen und Komponenten auf Umgebungsebene.

Verwenden Sie diese Parameter nicht mit dieser Verbindung:

• 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);
}

Herstellen einer Verbindung mit einem GitHub Repository

Bevor Sie die API zum Herstellen einer Verbindung mit GitHub verwenden, führen Sie die Setupschritte zum Erstellen der GitHub App aus, installieren Sie sie im Ziel-Repository, importieren Sie den privaten Schlüssel in Azure Key Vault, und erstellen Sie die Verbindung mit Power Platform GitHub. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit GitHub.

Erstellen eines GitHub App-Konfigurationsdatensatzes mithilfe der Web-API

Verwenden Sie die Dataverse OData-Web-API, um einen githubappconfig Datensatz zu erstellen. Senden Sie eine POST-Anforderung mit der GitHub App-Client-ID, Key Vault URI und dem Schlüsselnamen.

Sie können einen beliebigen HTTP-Client wie Insomnia, Visual Studio Code REST Client oder curl verwenden, um diese Aufrufe auszuführen. Sie benötigen ein Bearertoken für die Authentifizierung. Weitere Informationen finden Sie unter Verwenden der Microsoft Dataverse Web-API.

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

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

Nachdem Sie den GitHub App-Konfigurationsdatensatz erstellt haben, weisen Sie der verwalteten Dataverse-Identität die rolle Key Vault Crypto User zu, wie unter Configure Key Vault role-based access control (RBAC) beschrieben.

Aufrufen der ConnectToGit-API

Nachdem Sie den githubappconfig Datensatz erstellt und Key Vault RBAC konfiguriert haben, verwenden Sie die Dataverse-Web-API, um die Quellcodeverwaltungsverbindung herzustellen, indem Sie die ConnectToGit Aktion aufrufen.

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

Wenn Sie eine erfolgreiche Antwort erhalten, ist die Umgebung mit GitHub verbunden.

Herstellen einer Verbindung mit einem GitHub-Repository mithilfe von PowerShell

Im folgenden PowerShell-Beispiel wird der GitHub App-Konfigurationsdatensatz erstellt, wartet, bis die verwaltete Dataverse-Identität in Microsoft Entra ID angezeigt wird, weist die Key Vault Kryptobenutzerrolle der verwalteten Identität zu und ruft die ConnectToGit Aktion auf. Wenn Sie bereits über einen Konfigurationsdatensatz für die GitHub-App verfügen, geben Sie GitHubAppConfigId an, um die Konfiguration und die Schritte zur Rollenzuweisung für Key Vault zu überspringen.

Installieren und importieren Sie die PowerShell-Module Az.Accounts, Az.KeyVault und Az.Resources, bevor Sie das Beispiel ausführen. Melden Sie sich mit Connect-AzAccount einem Konto an, das Zugriff auf die Dataverse-Umgebung hat und über die Berechtigung zum Zuweisen von Key Vault-Rollen verfügt.

Wenn für die Dataverse-Umgebung die Unterstützung für virtuelle Netzwerke (VNET) aktiviert ist, geben Sie GitHubPAT an. GitHub Verbindungen können nicht mit unterstützung für virtuelle Netzwerke verwendet werden.

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

Trennen Sie die gesamte Dataverse-Umgebung von der Git-Quellcodeverwaltung.

Diese Aktion entfernt die Git-Verbindung auf Umgebungsebene. Verwenden Sie den SolutionUniqueName Parameter für diesen Vorgang nicht. Dataverse identifiziert und entfernt automatisch die Git-Verbindung auf Umgebungsebene.

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);

}

Verbinden der ersten Lösung mit einem Git-Repository

Diese Verbindung stellt die Repositoryverknüpfung und ordnerstruktur für die Quellcodeverwaltung auf Lösungsebene mit der ersten Lösung in einer Umgebung her.

Sie müssen Werte für diese Parameter einschließen, um die Lösung anzugeben:

• 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);
}

Verbinden zusätzlicher Lösungen mit dem gleichen Git-Repository, nachdem Sie die erste Lösung verbunden haben

Nachdem Sie die erste Lösung verbunden haben, benötigen Sie nur die lösungsspezifischen Parameter. Sie erben die Repository-Verbindungsdetails von der ersten Verbindung.

Legen Sie nur diese Parameter fest:

• 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);
}

Trennen einer bestimmten Lösung aus der Git-Quellcodeverwaltung, während andere Lösungen verbunden bleiben

Verwenden Sie diesen Ansatz, um die Quellcodeverwaltung für eine Lösung zu entfernen, ohne andere zu beeinträchtigen.

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

Fehlerbehandlung

Weder die ConnectToGit-API noch die DisconnectFromGit-API gibt einen Wert zurück, wenn sie erfolgreich abgeschlossen wird. Wenn eine API fehlschlägt, wird ein Fehler zurückgegeben.

Häufige Fehlerszenarien sind:

• Ungültige Anmeldeinformationen: Stellen Sie sicher, dass Sie über eine gültige Authentifizierung für den Git-Anbieter verfügen.
• Repository nicht gefunden: Überprüfen Sie die Namen der Organisation, des Projekts und des Repositorys.
• Berechtigung verweigert: Stellen Sie sicher, dass Ihr Dataverse-Konto über Berechtigungen für die Quellcodeverwaltung verfügt.
• Lösung nicht gefunden: Überprüfen Sie, ob die SolutionUniqueName In Ihrer Umgebung vorhanden ist.
• Branch ist nicht vorhanden: Bestätigen Sie, dass die angegebene Verzweigung im Repository vorhanden ist.

Support und zusätzliche Ressourcen

Weitere Informationen zur Integration der Quellcodeverwaltung in Dataverse finden Sie unter:

• Übersicht über die Git-Integration in Power Platform
• ConnectToGit-Aktion
• DisconnectFromGit-Aktion
• CommitToGit-Aktion
• RefreshChangesFromGit-Aktion
• PullChangesFromGit-Aktion