Povežite i odspojite Dataverse s Git repozitorijem koristeći kod

Koristite ConnectToGit i DisconnectFromGit API-je za programatsku integraciju vašeg Microsoft Dataverse okruženja s Git kontrolom izvornog koda. Pomoću tih API-ja možete povezati pojedinačna rješenja ili čitava okruženja s podržanim spremištima servisa Git i upravljati tim vezama putem koda.

Preduvjeti

Prije korištenja ovih API-ja, pobrinite se da imate:

  • Pristup Microsoft Dataverse okruženju
  • Dozvole sistemskog administratora
  • Pristup za čitanje i pisanje u Git repozitorij

ConnectToGit API

Stvara vezu između Dataverse rješenja ili okruženja i Git repozitorija. Korištenjem ove veze možete upravljati kontrolom izvornog koda za svoje Dataverse komponente.

Parametri

API ConnectToGit prihvaća sljedeće parametre:

Parametar Vrsta Obavezno Opis
GitFolder Niz Da Naziv mape na koju želite povezati svoje rješenje ili okruženje.
Branch Niz Da Naziv poslovnice na koju se želite povezati.
ConnectionType Cjelobrojna Ne Specificira na što se spojiti. Vidi parametar ConnectionType.
GitProvider Cjelobrojna Ne Git pružatelj. Vidi GitProvider parametar.
Organization Niz Ne Naziv organizacije s kojom se želite povezati.
Project Niz Ne Naziv projekta na koji se želite povezati.
Repository Niz Ne Naziv repozitorija na koji se želite povezati.
RootFolder Niz Ne Naziv korijenske mape u kojoj se nalaze sva vaša rješenja u opsegu rješenja.
SolutionUniqueName Niz Ne Jedinstveno ime rješenja koje želite povezati na git.
UpstreamBranch Niz Ne Naziv uzvodne grane na koju se želite povezati. Zadani je na zadani ogranak repozitorija.
GitHubConnectionId Niz Ne ID veze za vezu dodatka Power Platform GitHub vezu. Obavezno kada GitProvider jest, 1 osim ako navedite GitHubPAT. Nije moguće koristiti kada je za okruženje Dataverse omogućena podrška za virtualnu mrežu (VNET).
GitHubPAT Niz Ne GitHub pristupni token s pristupom ciljnom spremištu. Obavezno kada GitProvider jest, 1 osim ako navedite GitHubConnectionId. Obavezno kada je za okruženje Dataverse omogućena podrška za virtualnu mrežu (VNET).
GitHubAppConfigId Niz Ne Referenca na zapis GitHub konfiguracije aplikacije. Potrebno kada GitProvider je .1 Koristite oblik githubappconfigs(<recordId>).

Parametar ConnectionType

Parametar ConnectionType kontrolira hoće li se povezati s cijelim Dataverse okruženjem ili s određenim rješenjem.

Vrijednost Oznaka Opis
0 Rješenje Povezuje specifično Dataverse rješenje s Gitom.
1 Okruženje Povezuje cijelo Dataverse okruženje s Gitom.

GitProvider parametar

Koristite parametar GitProvider za određivanje vrste Git providera koji koristite, bilo Azure DevOps ili GitHub.

Vrijednost Oznaka Opis
0 Azure DevOps Upotreba za repozitorije hostane na Azure DevOps
1 GitHub Upotreba za repozitorije smještene na GitHubu

DisconnectFromGit API

Uklanja Git vezu iz Dataverse rješenja ili okruženja i onemogućuje integraciju kontrole izvornog koda.

Parametar

API DisconnectFromGit ima samo jedan parametar.

Parametar Vrsta Obavezno Opis
SolutionUniqueName Niz Ne Jedinstveni naziv rješenja koje želite isključiti iz Gita. Izostavite isključivanje svih rješenja ili okruženja.

Dodatne informacije

Evo nekoliko opcija vrijednosti parametara koje treba specificirati prilikom pozivanja DisconnectFromGit.

  • Isključite jedno rješenje: Omogućite SolutionUniqueName odspajanje određenog rješenja.
  • Isključite sva rješenja: Ne dajte nikakve parametre za prekid svih veza na razini rješenja.
  • Okruženje za prekidanje: Ne dajte nikakve parametre za prekid veze na razini okoline.

Primjeri

U sljedećim se primjerima opisuju scenariji korištenja ConnectToGitDisconnectFromGit API-ja i API-ja:

Povežite cijelo svoje Dataverse okruženje s Azure DevOps repozitorijem

Ova veza omogućuje kontrolu izvornog koda za sve konfiguracije i komponente na razini okoliša.

Nemojte koristiti ove parametre s ovom vezom:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Ovaj primjer pokazuje kako koristiti ConnectToGit akciju za povezivanje cijelog vašeg Dataverse okruženja s Azure DevOps repozitorijem.

Zahtjev

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

Odaziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite kako pokrenuti Web API akcije

Povezivanje s GitHub spremišta

Prije nego što se pomoću API-ja povežete s programom GitHub, dovršite korake postavljanja da biste stvorili aplikaciju za GitHub, instalirali je u ciljno spremište, uvezli njegov privatni ključ u Azure Key Vault i stvorili vezu servisa Power Platform GitHub. Dodatne informacije potražite u članku Povezivanje s GitHub.

Stvaranje zapisa GitHub aplikacije pomoću WEB API-ja

Pomoću OData web API-ja za Dataverse stvorite githubappconfig zapis. Pošaljite POST zahtjev s ID-jem GitHub aplikacije App, Key Vault URI-jem i nazivom ključa.

Da biste upućili te pozive, možete koristiti bilo koji HTTP klijent, npr. nesanicu, Visual Studio Code REST Client ili curl. Za provjeru autentičnosti potreban vam je token nositelja. Dodatne informacije potražite u članku Korištenje Microsoft Dataverse Web API.

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

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

Važno

Obratite pozornost na ID zapisa vraćen u zaglavlju odgovora. Ta vam je vrijednost potrebna da biste prepoznali upravljani identitet, konfigurirali RBAC i pozivali ConnectToGit. ID zapisa koristi oblik kao što je 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Nakon stvaranja zapisa konfiguracije GitHub App dodijelite ulogu Key Vault Crypto User upravljanom identitetu Dataverse kao što je opisano u članku Konfiguriranje Key Vault kontrole pristupa utemeljene na ulogama (RBAC) na temelju uloga.

Pozivanje API-ja connectToGit

Kada stvorite zapis i githubappconfig konfigurirate RBAC Key Vault pomoću Dataverse Web API-ja uspostavite vezu kontrole izvora pozivanjem ConnectToGit akcije.

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

Važno

Ogranak već mora postojati u spremištu. Po potrebi ga GitHub u pregledniku. Vrijednost GitHubAppConfigId mora koristiti oblik githubappconfigs(<recordId>).

Snimka zaslona tijela HTTP zahtjeva za API ConnectToGit s GitHub parametara.

Ako primite uspješan odgovor, okruženje je povezano s GitHub.

Povezivanje s GitHub pomoću komponente PowerShell

U sljedećem primjeru komponente PowerShell stvara se zapis o konfiguraciji aplikacije GitHub, čeka da se upravljani identitet Dataverse pojavi u sustavu Microsoft Entra ID, dodjeljuje ulogu Key Vault kriptografa za kriptovalute identitetu i ConnectToGit poziva akciju. Ako već imate zapis o konfiguraciji GitHub aplikacije, GitHubAppConfigId navedite kako biste preskočili konfiguraciju i Key Vault korake dodjele uloga.

Instalirajte i uvezite Az.Accountsmodule komponente Az.Resources , Az.KeyVaulti PowerShell prije pokretanja primjera. Prijavite se pomoću Connect-AzAccount računa koji ima pristup okruženju Dataverse i dozvolu za dodjelu uloga Key Vault podataka.

Ako je u okruženju Dataverse omogućena podrška za virtualnu mrežu (VNET), navedite GitHubPAT. GitHub veze ne mogu se koristiti s podrškom za virtualnu mrežu.

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

Isključite cijelo svoje Dataverse okruženje od Git kontrole izvornog koda

Ova radnja uklanja Git vezu na razini okoline. Nemojte koristiti parametar SolutionUniqueName za ovu operaciju. Dataverse automatski identificira i uklanja Git vezu na razini okoliša.

Ovaj primjer pokazuje kako koristiti akciju DisconnectFromGit za odvajanje cijelog Dataverse okruženja od Git kontrole izvornog koda.

Zahtjev

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

Odaziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite kako pokrenuti Web API akcije

Povežite prvo rješenje s Git repozitorijem

Ova veza uspostavlja strukturu veze repozitorija i mapa za upravljanje izvornim kodom na razini rješenja do prvog rješenja u okruženju.

Potrebno je uključiti vrijednosti za te parametre kako biste odredili rješenje:

  • RootFolder
  • SolutionUniqueName

Ovaj primjer pokazuje kako koristiti akciju ConnectToGit za povezivanje prvog rješenja s Git repozitorijem.

Zahtjev

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

Odaziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite kako pokrenuti Web API akcije

Povežite dodatna rješenja u isti Git repozitorij nakon što spojite početno rješenje

Nakon što spojite prvo rješenje, potrebni su vam samo parametri specifični za rješenje. Nasljeđujete detalje veze repozitorija od početne veze.

Postavite samo ove parametre:

  • SolutionUniqueName
  • Branch
  • GitFolder

Važno

Prvo morate spojiti prvo rješenje prije nego što ovo proradi. Pogledajte Povežite prvo rješenje s Git repozitorijem.

Ovaj primjer pokazuje kako koristiti akciju ConnectToGit za povezivanje sljedećih rješenja s Git repozitorijem.

Zahtjev

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

Odaziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite kako pokrenuti Web API akcije

Isključite određeno rješenje od Git source controla, dok ostala rješenja ostaju povezana

Koristite ovaj pristup kako biste uklonili kontrolu izvornog koda za jedno rješenje bez utjecaja na druga.

Ovaj primjer pokazuje kako koristiti akciju DisconnectFromGit za uklanjanje kontrole izvornog koda za jedno rješenje bez utjecaja na ostala.

Zahtjev

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

Odaziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite kako pokrenuti Web API akcije

Rukovanje pogreškama

Ni the ConnectToGit ni API ne DisconnectFromGit vraćaju vrijednost kada se uspješno dovrši. Kada API zakaže, vraća grešku.

Uobičajeni scenariji pogrešaka uključuju:

  • Nevažeće vjerodajnice: Pobrinite se da imate valjanu autentifikaciju kod Git pružatelja.
  • Repozitorij nije pronađen: Provjerite nazive organizacije, projekata i repozitorija.
  • Dozvola odbijena: Provjerite da vaš Dataverse račun ima dozvole za upravljanje kontrolom izvornog koda.
  • Rješenje nije pronađeno: Provjerite SolutionUniqueName postoji li u vašem okruženju.
  • Grana ne postoji: Potvrdite da navedena grana postoji u repozitoriju.

Podrška i dodatni resursi

Za više informacija o integraciji kontrole izvornog koda s Dataverseom, pogledajte: