Povežite in odklopite Dataverse od Git repozitorija z uporabo kode

Uporabite API-je ConnectToGit in DisconnectFromGit za programsko integracijo vašega Microsoft Dataverse okolja z Git nadzorom izvorne kode. S temi API-ji lahko povežete posamezne rešitve ali celotna okolja s podprtimi shrambami Git in upravljate te povezave s kodo.

Zahteve

Pred uporabo teh API-jev se prepričajte, da imate:

  • Dostop do okolja Microsoft Dataverse
  • Dovoljenja sistemskega skrbnika
  • Dostop za branje in pisanje v Git repozitorij

ConnectToGit API

Vzpostavi povezavo med rešitvijo ali okoljem Dataverse in Git repozitorijem. S to povezavo lahko upravljate nadzor izvorne kode za svoje Dataverse komponente.

Parametri

API ConnectToGit sprejema naslednje parametre:

Parameter Tip Zahtevano Description
GitFolder Niz Da Ime mape, na katero želite povezati svojo rešitev ali okolje.
Branch Niz Da Ime podružnice, na katero se želite povezati.
ConnectionType Integer Ne Določa, na kaj se priključiti. Glej parameter ConnectionType.
GitProvider Integer Ne Git ponudnik. Glej parameter GitProvider.
Organization Niz Ne Ime organizacije, s katero želite vzpostaviti povezavo.
Project Niz Ne Ime projekta, s katerim se želiš povezati.
Repository Niz Ne Ime repozitorija, na katerega se želite povezati.
RootFolder Niz Ne Ime korenske mape, kjer se nahajajo vse vaše rešitve v obsegu rešitve.
SolutionUniqueName Niz Ne Edinstveno ime rešitve, ki jo želite povezati z gitom.
UpstreamBranch Niz Ne Ime zgornje veje, na katero se želite povezati. Privzeto se nastavi na privzeto vejo repozitorija.
GitHubConnectionId Niz Ne ID povezave za povezavo power platform GitHub povezavo. Zahtevano, če GitProvider ni 1 podanega .GitHubPAT Ni mogoče uporabiti, če je za okolje Dataverse omogočena podpora za navidezno omrežje (VNET).
GitHubPAT Niz Ne GitHub žeton za osebni dostop z dostopom do ciljnega skladišča. Zahtevano, če GitProvider ni 1 podanega .GitHubConnectionId Zahtevano, če je za okolje Dataverse omogočena podpora za navidezno omrežje (VNET).
GitHubAppConfigId Niz Ne Sklic na zapis GitHub programa. Zahtevano, ko GitProvider je .1 Uporabite obliko zapisa githubappconfigs(<recordId>).

Parameter ConnectionType

Parameter določa, ConnectionType ali se povezati s celotnim okoljem Dataverse ali z določeno rešiljo.

Vrednost Oznaka Description
0 Rešitev Poveže določeno rešitev Dataverse z Gitom.
1 Okolje Povezuje celotno okolje Dataverse z Gitom.

Parameter GitProvider

Uporabite GitProvider parameter za določitev vrste ponudnika Gita, ki ga uporabljate, bodisi Azure DevOps ali GitHub.

Vrednost Oznaka Description
0 Azure DevOps Uporaba za repozitorije, gostovane na Azure DevOps
1 GitHub Uporaba za repozitorije, gostovane na GitHubu

DisconnectFromGit API

Odstrani Git povezavo iz rešitve ali okolja Dataverse in onemogoči integracijo upravljanja izvorne različice.

Parameter

API DisconnectFromGit ima le en parameter.

Parameter Tip Zahtevano Description
SolutionUniqueName Niz Ne Edinstveno ime rešitve, ki jo želiš odklopiti od Gita. Izpustite odklop vseh rešitev ali okolja.

Dodatne informacije

Tukaj je nekaj možnosti vrednosti parametrov, ki jih je treba določiti pri klicu DisconnectFromGit.

  • Odklopi eno rešitev: Omogoči SolutionUniqueName odklop določene rešitve.
  • Odklopite vse rešitve: Ne navedite nobenih parametrov za prekinitev vseh povezav na ravni rešitve.
  • Okolje za odklop: Ne navedite nobenih parametrov za prekinitev povezave na ravni okolja.

Primeri

Ti primeri opisujejo scenarije za uporabo vmesnikov ConnectToGitDisconnectFromGit API:

Povežite celotno okolje Dataverse z Azure DevOps repozitorijem

Ta povezava omogoča nadzor izvorne kode za vse konfiguracije in komponente na ravni okolja.

Ne uporabljajte teh parametrov s to povezavo:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Ta primer prikazuje, kako uporabiti dejanje ConnectToGit za povezavo celotnega okolja Dataverse z Azure DevOps repozitorijem.

Zahteva

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

Odziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite se, kako sprožiti dejanja spletnega API-ja

Vzpostavljanje povezave s GitHub skladiščem

Preden z API-jem vzpostavite povezavo s storitvijo GitHub, dokončajte korake za namestitev, da ustvarite program GitHub, ga namestite v ciljno skladišče, uvozite zasebni ključ v Azure Key Vault in ustvarite povezavo power platform GitHub. Če želite več informacij, glejte Vzpostavljanje povezave GitHub.

Ustvarjanje zapisa GitHub programa s spletnim API-jem

Če želite ustvariti zapis, uporabite spletni API githubappconfig Dataverse OData. Pošljite zahtevo post z ID-jem GitHub aplikacije, URI-jem Key Vault in imenom ključa.

Za opravljanje teh klicev lahko uporabite katerega koli odjemalca HTTP, na primer Nespečnost, Visual Studio Code REST Client ali curl. Za preverjanje pristnosti potrebujete žeton za bearer. Če želite več informacij, glejte Uporaba Microsoft Dataverse spletnega API-ja.

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

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

Pomembno

Upoštevajte ID zapisa, ki je bil vrnjen v glavi odgovora. To vrednost potrebujete, če želite identificirati upravljano identiteto, konfigurirati RBAC in poklicati ConnectToGit. ID zapisa uporablja obliko zapisa, kot je 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Ko ustvarite zapis GitHub app configuration, assign the Key Vault Crypto User role to the Dataverse managed identity as described in Configure Key Vault role-based access control (RBAC).

Priklic API-ja ConnectToGit

Ko ustvarite zapis githubappconfig in konfigurirate Key Vault RBAC, s spletnim API-jem Dataverse vzpostavite povezavo za nadzor vira tako, da pokličete ConnectToGit dejanje.

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

Pomembno

Veja mora že obstajati v skladišču. Po potrebi ga GitHub ustvarite v mapi » «. Vrednost GitHubAppConfigId mora uporabiti obliko zapisa githubappconfigs(<recordId>).

Posnetek zaslona telesa zahteve HTTP za API ConnectToGit s GitHub strežnika.

Če prejmete uspešen odgovor, je okolje povezano z GitHub.

Povezovanje s skladiščem GitHub z ogrodjem PowerShell

Ta primer ogrodja PowerShell ustvari zapis konfiguracije aplikacije GitHub, počaka, da se upravljana identiteta Dataverse prikaže v storitvi Microsoft Entra ID, upravljani identiteti dodeli vlogo uporabnika kriptografijeConnectToGit Key Vault in priklica dejanje. Če že imate zapis konfiguracije GitHub aplikacije, navedite, GitHubAppConfigId da preskočite konfiguracijo in Key Vault koraki dodelitve vloge.

Preden zaženete primer Az.Accounts, namestite Az.KeyVaultin uvozite Az.Resources module , in PowerShell. Vpišite se Connect-AzAccount z računom, ki ima dostop do okolja Dataverse in dovoljenje za dodelitev Key Vault vlog.

Če je podpora za navidezno omrežje (VNET) omogočena za okolje Dataverse, zagotovite GitHubPAT. GitHub povezave ni mogoče uporabiti s podporo za navidezno omrežje.

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

Odklopite celotno okolje Dataverse od Git nadzora izvorne kode

Ta ukrep odstrani povezavo z Git na ravni okolja. Za to operacijo ne uporabljajte parametra SolutionUniqueName . Dataverse samodejno prepozna in odstrani Git povezavo na ravni okolja.

Ta primer prikazuje, kako uporabiti dejanje DisconnectFromGit za odklop celotnega okolja Dataverse od nadzora izvorne kode Gita.

Zahteva

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

Odziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite se, kako sprožiti dejanja spletnega API-ja

Prvo rešitev povežite z Git repozitorijem

Ta povezava vzpostavi povezavo repozitorija in strukturo map za nadzor izvorne kode na ravni rešitve do prve rešitve v okolju.

Za določitev rešitve morate vključiti vrednosti za te parametre:

  • RootFolder
  • SolutionUniqueName

Ta primer prikazuje, kako uporabiti dejanje ConnectToGit za povezavo prve rešitve z Git repozitorijem.

Zahteva

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

Odziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite se, kako sprožiti dejanja spletnega API-ja

Po priključitvi začetne rešitve povežite dodatne rešitve v isti Git repozitorij

Ko povežete prvo rešitev, potrebujete le parametre, specifične za rešitev. Podatke o povezavi repozitorija podedujete iz začetne povezave.

Nastavite le te parametre:

  • SolutionUniqueName
  • Branch
  • GitFolder

Pomembno

Najprej morate povezati prvo rešitev, preden deluje. Glej Poveži prvo rešitev z Git repozitorijem.

Ta primer prikazuje, kako uporabiti dejanje ConnectToGit za povezavo naslednjih rešitev z Git repozitorijem.

Zahteva

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

Odziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite se, kako sprožiti dejanja spletnega API-ja

Odklopite določeno rešitev od Git upravljanja izvorne kodne datoteke, medtem ko druge rešitve ohranite povezane

Uporabite ta pristop za odstranitev nadzora izvorne kode za eno rešitev, ne da bi vplivali na druge.

Ta primer prikazuje, kako uporabiti dejanje DisconnectFromGit za odstranitev nadzora izvorne kode za eno rešitev, ne da bi vplival na druge.

Zahteva

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

Odziv

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučite se, kako sprožiti dejanja spletnega API-ja

Obravnavanje napak

Niti the ConnectToGit niti API ne vrneta DisconnectFromGit vrednosti, ko se uspešno zaključi. Ko API odpove, vrne napako.

Pogosti primeri napak vključujejo:

  • Neveljavne poverilnice: Preverite, ali imate veljavno avtentikacijo pri ponudniku Gita.
  • Repozitorij ni najden: Preverite imena organizacije, projektov in repozitorijev.
  • Dovoljenje zavrnjeno: Poskrbite, da ima vaš račun Dataverse dovoljenja za upravljanje nadzora izvorne kode.
  • Rešitev ni našla: Preverite, ali obstaja SolutionUniqueName v vašem okolju.
  • Veja ne obstaja: Potrdite, da določena veja obstaja v repozitoriju.

Podpora in dodatni viri

Za več informacij o integraciji upravljanja kodo z Dataverse glejte: