Koble til og koble datavers fra et Git-repositorium ved hjelp av kode

ConnectToGit Bruk API-ene og DisconnectFromGit API-ene til å integrere Microsoft Dataverse-miljøet programmatisk med Git-kildekontrollen. Ved å bruke disse API-ene kan du koble individuelle løsninger eller hele miljøer til støttede Git-repositorier og administrere disse tilkoblingene gjennom kode.

Forutsetninger

Før du bruker disse API-ene, må du kontrollere at du har:

  • Tilgang til et Microsoft Dataverse-miljø
  • Systemansvarligs tillatelser
  • Lese og skrive tilgang til et Git-repositorium

ConnectToGit API

Oppretter en tilkobling mellom en datavers løsning eller et miljø og et Git-repositorium. Ved hjelp av denne tilkoblingen kan du administrere kildekontroll for dataverskomponentene.

Parametere

ConnectToGit API-en godtar følgende parametere:

Parameter Type Obligatorisk Beskrivelse
GitFolder Streng Ja Navnet på mappen du vil binde løsningen eller miljøet til.
Branch Streng Ja Navnet på grenen du vil koble til.
ConnectionType Integer Nei Angir hva du skal koble til. Se ConnectionType-parameteren.
GitProvider Integer Nei Git-leverandøren. Se GitProvider-parameteren.
Organization Streng Nei Navnet på organisasjonen du vil koble til.
Project Streng Nei Navnet på prosjektet du vil koble til.
Repository Streng Nei Navnet på repositoriet du vil koble til.
RootFolder Streng Nei Navnet på rotmappen der alle løsningene ligger i løsningsomfanget.
SolutionUniqueName Streng Nei Det unike navnet på løsningen du vil koble til git.
UpstreamBranch Streng Nei Navnet på oppstrømsgreningen du vil koble til. Angis til standardgrenen for repositorium.
GitHubConnectionId Streng Nei Tilkoblings-ID for Power Platform GitHub tilkobling. Obligatorisk når GitProvider er 1 med mindre du oppgir GitHubPAT. Kan ikke brukes når støtte for virtuelt nettverk (VNET) er aktivert for dataversmiljøet.
GitHubPAT Streng Nei GitHub personlig tilgangstoken med tilgang til målrepositoriet. Obligatorisk når GitProvider er 1 med mindre du oppgir GitHubConnectionId. Obligatorisk når støtte for virtuelt nettverk (VNET) er aktivert for dataversmiljøet.
GitHubAppConfigId Streng Nei Referanse til GitHub appkonfigurasjonsoppføring. Obligatorisk når GitProvider er 1. Bruk formatet githubappconfigs(<recordId>).

ConnectionType-parameter

Parameteren ConnectionType kontrollerer om du vil koble til hele dataversmiljøet eller en bestemt løsning.

Verdi Etikett Beskrivelse
0 Løsning Kobler en bestemt dataversløsning til Git.
1 Miljø Kobler hele dataversmiljøet til Git.

GitProvider-parameter

Bruk parameteren GitProvider til å angi hvilken type Git-leverandør du bruker, enten Azure DevOps eller GitHub.

Verdi Etikett Beskrivelse
0 Azure DevOps Bruk for repositorier som driftes på Azure DevOps
1 GitHub Bruk for repositorier som driftes på GitHub

DisconnectFromGit API

Fjerner Git-tilkoblingen fra en datavers løsning eller et miljø, og deaktiverer kildekontrollintegrering.

Parameter

DisconnectFromGit API-en har bare én parameter.

Parameter Type Obligatorisk Beskrivelse
SolutionUniqueName Streng Nei Det unike navnet på løsningen du vil koble fra Git. Utelate å koble fra alle løsninger eller miljøet.

Tilleggsinformasjon

Her er noen alternativer for parameterverdi du kan angi når du aktiverer DisconnectFromGit.

  • Koble fra én enkelt løsning: Angi SolutionUniqueName at du skal koble fra en bestemt løsning.
  • Koble fra alle løsninger: Gir ingen parametere for å koble fra alle tilkoblinger på løsningsnivå.
  • Frakoblingsmiljø: Gir ingen parametere for å koble fra tilkoblingen på miljønivå.

Eksempler

Eksemplene nedenfor beskriver scenarioer for bruk av ConnectToGit API-er og DisconnectFromGit API-er:

Koble hele dataversmiljøet til et Azure DevOps-repositorium

Denne tilkoblingen aktiverer kildekontroll for alle konfigurasjoner og komponenter på miljønivå.

Ikke bruk disse parameterne med denne tilkoblingen:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Dette eksemplet viser hvordan du bruker Handlingen ConnectToGit til å koble hele dataversmiljøet til et Azure DevOps-repositorium.

Forespørsel

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

Svar

HTTP/1.1 204 No Content
OData-Version: 4.0

Finn ut hvordan du aktiverer web-API-handlinger

Koble til et GitHub repositorium

Før du bruker API-en til å koble til GitHub, må du fullføre konfigurasjonstrinnene for å opprette GitHub-appen, installere den på målrepositoriet, importere den private nøkkelen til Azure Key Vault og opprette Power Platform GitHub-tilkoblingen. Hvis du vil ha mer informasjon, kan du se Koble til GitHub.

Opprette en GitHub App-konfigurasjonspost ved hjelp av web-API-en

Bruk Dataverse OData Web API til å opprette en githubappconfig-post. Send en POST-forespørsel med GitHub appklient-ID, Key Vault URI og nøkkelnavn.

Du kan bruke hvilken som helst HTTP-klient, for eksempel Insomnia, Visual Studio Code REST Client eller curl, til å foreta disse samtalene. Du trenger et bærertoken for godkjenning. Hvis du vil ha mer informasjon, kan du se Bruke Microsoft Dataverse Web API.

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

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

Viktig!

Legg merke til post-ID-en som returneres i svaroverskriften. Du trenger denne verdien for å identifisere den administrerte identiteten, konfigurere RBAC og ringe ConnectToGit. Oppførings-ID-en bruker et format slik som 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Når du har opprettet GitHub appkonfigurasjonsoppføringen, tilordner du rollen Key Vault crypto-bruker til den dataverseadministrerte identiteten som beskrevet i Konfigurer Key Vault rollebasert tilgangskontroll (RBAC).

Kall ConnectToGit-API-en

Når du har opprettet githubappconfig posten og konfigurert Key Vault RBAC, bruker du Dataverse Web API-en til å opprette kildekontrolltilkoblingen ConnectToGit ved å kalle handlingen.

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

Viktig!

Grenen må allerede finnes i repositoriet. Opprett det i GitHub først om nødvendig. Verdien GitHubAppConfigId må bruke formatet githubappconfigs(<recordId>).

Skjermbilde av en HTTP-forespørselstekst for ConnectToGit-API-en med GitHub parametere.

Hvis du får et vellykket svar, er miljøet koblet til GitHub.

Koble til et GitHub-repositorium ved hjelp av PowerShell

Det følgende PowerShell-eksemplet oppretter GitHub appkonfigurasjonsoppføringen, venter på at den dataverseadministrerte identiteten vises i Microsoft Entra ID, tilordner rollen Key Vault Crypto-bruker til den administrerte identiteten og kaller ConnectToGit handlingen. Hvis du allerede har en konfigurasjonsoppføring for GitHub App, oppgir du GitHubAppConfigId for å hoppe over konfigurasjonen og trinnene for rolletilordning i Key Vault.

Installer og importer modulene Az.Accounts, Az.KeyVaultog Az.Resources PowerShell før du kjører eksemplet. Logg på med Connect-AzAccount en konto som har tilgang til dataversmiljøet og tillatelse til å tilordne Key Vault roller.

Hvis støtte for virtuelt nettverk (VNET) er aktivert for dataversmiljøet, kan du angi GitHubPAT. GitHub tilkoblinger kan ikke brukes med støtte for virtuelt nettverk.

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

Koble fra hele Dataverse-miljøet fra Git-versjonskontroll

Denne handlingen fjerner git-tilkoblingen på miljønivå. Ikke bruk parameteren SolutionUniqueName for denne operasjonen. Datavers identifiserer og fjerner automatisk Git-tilkoblingen på miljønivå.

Dette eksemplet viser hvordan du bruker handlingen DisconnectFromGit til å koble hele dataversmiljøet fra Git-kildekontrollen.

Forespørsel

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

Svar

HTTP/1.1 204 No Content
OData-Version: 4.0

Finn ut hvordan du aktiverer web-API-handlinger

Koble den første løsningen til et Git-repositorium

Denne tilkoblingen etablerer repositoriumkoblingen og mappestrukturen for kildekontroll på løsningsnivå til den første løsningen i et miljø.

Du må inkludere verdier for disse parameterne for å angi løsningen:

  • RootFolder
  • SolutionUniqueName

Dette eksemplet viser hvordan du bruker handlingen ConnectToGit til å koble den første løsningen til et Git-repositorium.

Forespørsel

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

Svar

HTTP/1.1 204 No Content
OData-Version: 4.0

Finn ut hvordan du aktiverer web-API-handlinger

Koble ekstra løsninger til samme Git-repositorium etter at du har koblet til den opprinnelige løsningen

Når du har koblet til den første løsningen, trenger du bare de løsningsspesifikke parameterne. Du arver tilkoblingsdetaljene for repositoriet fra den første tilkoblingen.

Angi bare disse parameterne:

  • SolutionUniqueName
  • Branch
  • GitFolder

Viktig!

Du må først koble til den første løsningen før dette fungerer. Se Koble den første løsningen til et Git-repositorium.

Dette eksemplet viser hvordan du bruker handlingen ConnectToGit til å koble etterfølgende løsninger til et Git-repositorium.

Forespørsel

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

Svar

HTTP/1.1 204 No Content
OData-Version: 4.0

Finn ut hvordan du aktiverer web-API-handlinger

Koble fra en bestemt løsning fra Git-kildekontrollen samtidig som andre løsninger er tilkoblet

Bruk denne fremgangsmåten til å fjerne kildekontroll for én løsning uten å påvirke andre.

Dette eksemplet viser hvordan du bruker handlingen DisconnectFromGit til å fjerne kildekontroll for én løsning uten å påvirke andre.

Forespørsel

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

Svar

HTTP/1.1 204 No Content
OData-Version: 4.0

Finn ut hvordan du aktiverer web-API-handlinger

Feilbehandling

Verken ConnectToGit eller DisconnectFromGit API-en returnerer en verdi når de er fullført. Når en API mislykkes, returnerer den en feil.

Vanlige feilscenarioer inkluderer:

  • Ugyldig legitimasjon: Kontroller at du har gyldig godkjenning til Git-leverandøren.
  • Finner ikke repositorium: Kontroller organisasjonen, prosjektet og repositoriumnavnene.
  • Ingen tillatelse: Kontroller at Dataverse-kontoen har tillatelser for kildekontrolladministrasjon.
  • Finner ikke løsningen: Kontroller at det SolutionUniqueName finnes i miljøet.
  • Grenen finnes ikke: Bekreft at den angitte grenen finnes i repositoriet.

Støtte og tilleggsressurser

Hvis du vil ha mer informasjon om kildekontrollintegrering med Datavers, kan du se:

  • Last updated on