Ansluta och koppla från Dataverse från en Git-lagringsplats med hjälp av kod

Använd API:erna ConnectToGit och DisconnectFromGit för att programmatiskt integrera din Microsoft Dataverse-miljö med Git-källkontroll. Genom att använda dessa API:er kan du ansluta enskilda lösningar eller hela miljöer till Git-lagringsplatser som stöds och hantera dessa anslutningar via kod.

Förutsättningar

Kontrollera att du har följande innan du använder dessa API:er:

• Åtkomst till en Microsoft Dataverse-miljö
• Systemadministratörsbehörigheter
• Läs- och skrivåtkomst till en Git-lagringsplats

ConnectToGit API

Skapar en anslutning mellan en Dataverse-lösning eller -miljö och en Git-lagringsplats. Genom att använda den här anslutningen kan du hantera källkontroll för dina Dataverse-komponenter.

Parameters

ConnectToGit API:et accepterar följande parametrar:

Parametern ConnectionType

Parametern ConnectionType styr om du vill ansluta till hela Dataverse-miljön eller en specifik lösning.

GitProvider-parameter

Använd parametern GitProvider för att ange vilken typ av Git-provider du använder, antingen Azure DevOps eller GitHub.

Frånkoppla från Git API

Tar bort Git-anslutningen från en Dataverse-lösning eller -miljö och inaktiverar källkontrollintegrering.

Parameter

API:et DisconnectFromGit har bara en parameter.

Ytterligare information

Här följer några parametervärdealternativ som du kan ange när du anropar DisconnectFromGit.

• Koppla från en enskild lösning: Tillhandahåll SolutionUniqueName för att koppla från en specifik lösning.
• Koppla från alla lösningar: Ange inga parametrar för att koppla från alla anslutningar på lösningsnivå.
• Frånkopplingsmiljö: Ange inga parametrar för att koppla från anslutningen på miljönivå.

Examples

I följande exempel beskrivs scenarier för användning av API:erna ConnectToGit och DisconnectFromGit :

• Ansluta hela Dataverse-miljön till en Azure DevOps-lagringsplats
• Ansluta till en GitHub lagringsplats
• Ansluta till en GitHub lagringsplats med hjälp av PowerShell
• Koppla bort hela Dataverse-miljön från Git-källkontrollen
• Ansluta den första lösningen till en Git-lagringsplats
• Ansluta extra lösningar till samma Git-lagringsplats när du har anslutit den första lösningen
• Koppla från en specifik lösning från Git-källkontrollen samtidigt som andra lösningar är anslutna

Ansluta hela Dataverse-miljön till en Azure DevOps-lagringsplats

Den här anslutningen möjliggör källkontroll för alla konfigurationer och komponenter på miljönivå.

Använd inte dessa parametrar med den här anslutningen:

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

Ansluta till en GitHub lagringsplats

Innan du använder API:et för att ansluta till GitHub slutför du installationsstegen för att skapa GitHub-appen, installerar den på mållagringsplatsen, importerar dess privata nyckel till Azure Key Vault och skapar Power Platform-GitHub-anslutningen. Mer information finns i Ansluta till GitHub.

Skapa en GitHub appkonfigurationspost med hjälp av webb-API:et

Använd Dataverse OData-webb-API:et för att skapa en githubappconfig post. Skicka en POST-begäran med klient-ID för GitHub App, Key Vault URI och nyckelnamn.

Du kan använda alla HTTP-klienter, till exempel Insomnia, Visual Studio Code REST Client eller curl, för att göra dessa anrop. Du behöver en ägartoken för autentisering. Mer information finns i Använda webb-API:et för Microsoft Dataverse.

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

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

När du har skapat GitHub App-konfigurationsposten tilldelar du rollen Key Vault Kryptoanvändare till den hanterade Dataverse-identiteten enligt beskrivningen i Konfigurera Key Vault rollbaserad åtkomstkontroll (RBAC).

Anropa ConnectToGit-API:et

När du har skapat githubappconfig-posten och konfigurerat Key Vault RBAC använder du Dataverse Web API för att upprätta anslutningen till källkontrollen genom att anropa åtgärden 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>)"
}

Om du får ett lyckat svar är miljön ansluten till GitHub.

Ansluta till en GitHub lagringsplats med hjälp av PowerShell

Följande PowerShell-exempel skapar konfigurationsposten för GitHub Appen, väntar på att den Dataverse-hanterade identiteten ska visas i Microsoft Entra ID, tilldelar den hanterade identiteten rollen Key Vault Crypto User och anropar åtgärden ConnectToGit. Om du redan har en konfigurationspost för GitHub-appen anger du GitHubAppConfigId för att hoppa över stegen för konfiguration och rolltilldelning i Key Vault.

Installera och importera modulerna Az.Accounts, Az.KeyVaultoch Az.Resources PowerShell innan du kör exemplet. Logga in med Connect-AzAccount med ett konto som har åtkomst till Dataverse-miljön och behörighet att tilldela Key Vault-roller.

Om stöd för virtuellt nätverk (VNET) är aktiverat för Dataverse-miljön anger du GitHubPAT. GitHub anslutningar kan inte användas med stöd för virtuella nätverk.

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

Koppla bort hela Dataverse-miljön från Git-källkontrollen

Den här åtgärden tar bort Git-anslutningen på miljönivå. Använd inte parametern SolutionUniqueName för den här åtgärden. Dataverse identifierar och tar automatiskt bort Git-anslutningen på miljönivå.

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

}

Ansluta den första lösningen till en Git-lagringsplats

Den här anslutningen etablerar länken till lagringsplatsen och mappstrukturen för källkontroll på lösningsnivå för den första lösningen i en miljö.

Du måste inkludera värden för dessa parametrar för att ange lösningen:

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

Ansluta extra lösningar till samma Git-lagringsplats när du har anslutit den första lösningen

När du har anslutit den första lösningen behöver du bara de lösningsspecifika parametrarna. Du ärver lagringsplatsens anslutningsinformation från den första anslutningen.

Ange endast följande parametrar:

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

Koppla från en specifik lösning från Git-källkontrollen samtidigt som andra lösningar är anslutna

Använd den här metoden för att ta bort källkontroll för en lösning utan att påverka andra.

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

Felhantering

Varken ConnectToGit-API:et eller DisconnectFromGit-API:et returnerar ett värde när det har slutförts framgångsrikt. När ett API misslyckas returneras ett fel.

Vanliga felscenarier är:

• Ogiltiga autentiseringsuppgifter: Kontrollera att du har giltig autentisering till Git-providern.
• Det går inte att hitta lagringsplatsen: Verifiera namn på organisation, projekt och lagringsplats.
• Behörighet nekad: Kontrollera att ditt Dataverse-konto har behörighet att hantera källkontroll.
• Det går inte att hitta lösningen: Kontrollera att den SolutionUniqueName finns i din miljö.
• Grenen finns inte: Bekräfta att den angivna grenen finns på lagringsplatsen.

Support och ytterligare resurser

Mer information om källkontrollintegrering med Dataverse finns i:

• Översikt över Git-integrering i Power Platform
• ConnectToGit-åtgärd
• DisconnectFromGit-åtgärd
• CommitToGit-åtgärd
• RefreshChangesFromGit-kommando
• Åtgärden PullChangesFromGit