Opret forbindelse til og frakoble Dataverse fra et Git-lager ved hjælp af kode

ConnectToGit Brug API'erne og DisconnectFromGit til programmeringsmæssigt at integrere dit Microsoft Dataverse-miljø med Git-kildekontrol. Ved hjælp af disse API'er kan du forbinde individuelle løsninger eller hele miljøer med understøttede Git-lagre og administrere disse forbindelser via kode.

Forudsætninger

Før du bruger disse API'er, skal du sikre dig, at du har:

• Adgang til et Microsoft Dataverse-miljø
• Systemadministratortilladelser
• Læse- og skriveadgang til et Git-lager

ConnectToGit API

Opretter en forbindelse mellem en Dataverse-løsning eller et miljø og et Git-lager. Ved hjælp af denne forbindelse kan du administrere kildestyring for dine Dataverse-komponenter.

Parametre

ConnectToGit API'en accepterer følgende parametre:

Parameteren ConnectionType

Parameteren ConnectionType styrer, om der skal oprettes forbindelse til hele Dataverse-miljøet eller en bestemt løsning.

GitProvider-parameter

GitProvider Brug parameteren til at angive den type Git-provider, du bruger, enten Azure DevOps eller GitHub.

DisconnectFromGit API

Fjerner Git-forbindelsen fra en Dataverse-løsning eller et datamiljø og deaktiverer integration af versionsstyring.

Parameter

API'en DisconnectFromGit har kun én parameter.

Flere oplysninger

Her er et par parameterværdiindstillinger, der skal angives, når der aktiveres DisconnectFromGit.

• Afbryd forbindelsen til en enkelt løsning: Angiv SolutionUniqueName for at afbryde forbindelsen til en bestemt løsning.
• Afbryd forbindelsen til alle løsninger: Angiv ingen parametre for at afbryde forbindelsen til alle forbindelser på løsningsniveau.
• Afbryd forbindelsen til miljøet: Angiv ingen parametre for at afbryde forbindelsen på miljøniveau.

Eksempler

I følgende eksempler beskrives scenarier for brug af ConnectToGit API'er og DisconnectFromGit :

• Forbind hele dit Dataverse-miljø til et Azure DevOps-lager
• Opret forbindelse til et GitHub lager
• Opret forbindelse til et GitHub lager ved hjælp af PowerShell
• Afbryd hele dit Dataverse-miljø fra Git-kildekontrol
• Forbind den første løsning til et Git-lager
• Forbind ekstra løsninger til det samme Git-lager, når du har oprettet forbindelse til den indledende løsning
• Afbryd forbindelsen mellem en bestemt løsning og Git-kildestyringen, samtidig med at andre løsninger er tilsluttet

Forbind hele dit Dataverse-miljø til et Azure DevOps-lager

Denne forbindelse muliggør kildestyring for alle konfigurationer og komponenter på miljøniveau.

Brug ikke disse parametre med denne forbindelse:

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

Opret forbindelse til et GitHub lager

Før du bruger API'en til at oprette forbindelse til GitHub, skal du fuldføre konfigurationstrinnene for at oprette GitHub-appen, installere den på mållageret, importere dens private nøgle til Azure Key Vault og oprette Power Platform-GitHub-forbindelsen. Du kan få flere oplysninger under Opret forbindelse til GitHub.

Opret en GitHub appkonfigurationspost ved hjælp af web-API'en

Brug Dataverse OData Web API til at oprette en githubappconfig post. Send en POST-anmodning med GitHub App-klient-id, Key Vault URI og nøglenavn.

Du kan bruge en vilkårlig HTTP-klient, f.eks. Insomnia, Visual Studio Code REST Client eller curl, til at foretage disse anmodninger. Du skal bruge et ihændehavertoken til godkendelse. Du kan få flere oplysninger under Brug Microsoft Dataverse Web-API' en.

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

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

Når du har oprettet den GitHub appkonfigurationspost, skal du tildele rollen Key Vault Kryptografibruger til den dataverse-administrerede identitet som beskrevet i Konfigurer Key Vault rollebaseret adgangskontrol (RBAC).

Kald ConnectToGit-API'et

Når du har oprettet posten githubappconfig og konfigureret Key Vault RBAC, skal du bruge Dataverse Web API til at oprette forbindelse til kildestyringen ved at kalde handlingenConnectToGit.

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

Hvis du modtager et vellykket svar, er miljøet forbundet med GitHub.

Opret forbindelse til et GitHub lager ved hjælp af PowerShell

Følgende PowerShell-eksempel opretter GitHub appkonfigurationspost, venter på, at den dataverse-administrerede identitet vises i Microsoft Entra ID, tildeler rollen Key Vault Crypto User til den administrerede identitet og kalder handlingenConnectToGit. Hvis du allerede har en konfigurationspost for GitHub-appen, skal du angive GitHubAppConfigId for at springe konfigurations- og rolletildelingstrinnene i Key Vault over.

Installér og importér modulerne Az.Accounts, Az.KeyVaultog Az.Resources PowerShell, før du kører eksemplet. Log på med Connect-AzAccount ved hjælp af en konto, der har adgang til Dataverse-miljøet, og tilladelse til at tildele Key Vault roller.

Hvis understøttelse af virtuelt netværk (VNET) er aktiveret for Dataverse-miljøet, skal du angive GitHubPAT. GitHub forbindelser kan ikke bruges med understøttelse af virtuelle netværk.

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

Afbryd hele dit Dataverse-miljø fra Git-kildekontrol

Denne handling fjerner Git-forbindelsen på miljøniveau. Brug ikke SolutionUniqueName parameteren til denne handling. Dataverse identificerer og fjerner automatisk Git-forbindelsen på miljøniveau.

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

}

Forbind den første løsning til et Git-lager

Denne forbindelse etablerer lagerlinket og mappestrukturen for versionsstyring på løsningsniveau til den første løsning i et miljø.

Du skal inkludere værdier for disse parametre for at angive 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);
}

Forbind ekstra løsninger til det samme Git-lager, når du har oprettet forbindelse til den indledende løsning

Når du har oprettet forbindelse til den første løsning, skal du kun bruge de løsningsspecifikke parametre. Du nedarver oplysningerne om lagerforbindelsen fra den indledende forbindelse.

Angiv kun disse parametre:

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

Afbryd forbindelsen mellem en bestemt løsning og Git-kildestyringen, samtidig med at andre løsninger er tilsluttet

Brug denne fremgangsmåde til at fjerne kildekontrol for én løsning, uden at det påvirker andre.

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

Fejlhåndtering

Hverken API'en ConnectToGitDisconnectFromGit eller returnerer en værdi, når den fuldføres. Når en API mislykkes, returneres der en fejl.

Almindelige fejlscenarier omfatter:

• Ugyldige legitimationsoplysninger: Kontrollér, at du har gyldig godkendelse til Git-udbyderen.
• Lageret blev ikke fundet: Kontrollér navnene på organisationen, projektet og lageret.
• Tilladelse nægtet: Kontrollér, at din Dataverse-konto har tilladelser til administration af kildekontrol.
• Løsningen blev ikke fundet: Kontrollér, at SolutionUniqueName findes i dit miljø.
• Forgreningen findes ikke: Bekræft, at den angivne forgrening findes i lageret.

Support og yderligere ressourcer

Du kan få flere oplysninger om integration af versionsstyring med Dataverse i:

• Oversigt over Git-integration i Power Platform
• ConnectToGit-handling
• DisconnectFromGit-aktion
• CommitToGit-aktion
• RefreshChangesFromGit Action
• PullChangesFromGit-handling