"Dataverse" prijungimas ir atjungimas nuo "Git" saugyklos naudojant kodą

Naudokite ConnectToGit ir DisconnectFromGit API, kad programiškai integruotumėte "Microsoft Dataverse" aplinką su "Git" šaltinio valdikliu. Naudodami šias API, galite prijungti atskirus sprendimus arba visas aplinkas prie palaikomų "Git" saugyklų ir valdyti šiuos ryšius naudodami kodą.

Būtinosios sąlygos

Prieš naudodami šias API įsitikinkite, kad turite:

  • Prieiga prie "Microsoft Dataverse" aplinkos
  • Sistemos administratoriaus teisės
  • Skaitymo ir rašymo prieiga prie "Git" saugyklos

ConnectToGit API

Sukuria ryšį tarp "Dataverse" sprendimo arba aplinkos ir "Git" saugyklos. Naudodami šį ryšį galite valdyti savo "Dataverse" komponentų šaltinio valdymą.

Parametrai

API ConnectToGit priima šiuos parametrus:

Parametras Tipas Būtina Aprašą
GitFolder Eilutė Taip Aplanko, su kuriuo norite susieti sprendimą arba aplinką, pavadinimas.
Branch Eilutė Taip Šakos, prie kurios norite prisijungti, pavadinimas.
ConnectionType Sveikasis skaičius Ne Nurodo, prie ko prisijungti. Žiūrėkite parametrą ConnectionType.
GitProvider Sveikasis skaičius Ne Git teikėjas. Žr. parametrą GitProvider.
Organization Eilutė Ne Organizacijos, prie kurios norite prisijungti, pavadinimas.
Project Eilutė Ne Projekto, prie kurio norite prisijungti, pavadinimas.
Repository Eilutė Ne Saugyklos, prie kurios norite prisijungti, pavadinimas.
RootFolder Eilutė Ne Šakninio aplanko, kuriame yra visi jūsų sprendimai sprendimo aprėptyje, pavadinimas.
SolutionUniqueName Eilutė Ne Unikalus sprendimo, kurį norite prijungti prie git, pavadinimas.
UpstreamBranch Eilutė Ne Pradinės šakos, prie kurios norite prisijungti, pavadinimas. Numatytoji saugyklos šaka.
GitHubConnectionId Eilutė Ne "Power Platform" GitHub ryšio ID. Būtina, kai GitProvider nepateikiama 1 , nebent pateikiate GitHubPAT. Negalima naudoti, kai "Dataverse" aplinkoje įgalintas virtualaus tinklo (VNET) palaikymas.
GitHubPAT Eilutė Ne GitHub asmeninės prieigos atpažinimo ženklą su prieiga prie paskirties saugyklos. Būtina, kai GitProvider nepateikiama 1 , nebent pateikiate GitHubConnectionId. Būtina, kai įgalintas "Dataverse" aplinkos virtualaus tinklo (VNET) palaikymas.
GitHubAppConfigId Eilutė Ne Nuoroda į GitHub taikomosios programos konfigūracijos įrašą. Būtina, kai GitProvider yra 1. Naudokite formatą githubappconfigs(<recordId>).

ConnectionType parametras

Parametras ConnectionType kontroliuoja, ar prisijungti prie visos "Dataverse" aplinkos, ar prie konkretaus sprendimo.

Reikšmė Žyma Aprašą
0 Sprendimas Prijungia konkretų "Dataverse" sprendimą prie "Git".
1 Aplinka Sujungia visą "Dataverse" aplinką su "Git".

GitProvider parametras

Naudokite parametrą, GitProvider kad nurodytumėte naudojamo "Git" teikėjo tipą – "Azure DevOps" arba "GitHub".

Reikšmė Žyma Aprašą
0 Azure DevOps Naudokite saugykloms, nuomojamoms "Azure DevOps"
1 GitHub Naudokite "GitHub" talpinamoms saugykloms

DisconnectFromGit API

Pašalina "Git" ryšį iš "Dataverse" sprendimo ar aplinkos ir išjungia šaltinio valdymo integravimą.

Parametras

API DisconnectFromGit turi tik vieną parametrą.

Parametras Tipas Būtina Aprašą
SolutionUniqueName Eilutė Ne Unikalus sprendimo, kurį norite atjungti nuo "Git", pavadinimas. Atjungti visus sprendimus ar aplinką.

Papildoma informacija

Štai keletas parametrų reikšmių parinkčių, kurias reikia nurodyti iškviečiant DisconnectFromGit.

  • Atjungti vieną sprendimą: numatyti SolutionUniqueName atjungti konkretų sprendimą.
  • Atjungti visus sprendimus: nepateikite parametrų, kad atjungtumėte visus sprendimo lygio ryšius.
  • Atjungti aplinką: nepateikite parametrų, kad atjungtumėte aplinkos lygio ryšį.

Pavyzdžiai

Toliau pateiktuose pavyzdžiuose aprašyti naudojimo scenarijai ConnectToGit ir DisconnectFromGit API:

Visos "Dataverse" aplinkos prijungimas prie "Azure DevOps" saugyklos

Šis ryšys įgalina visų aplinkos lygio konfigūracijų ir komponentų šaltinio valdymą.

Nenaudokite šių parametrų su šiuo ryšiu:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Šiame pavyzdyje parodyta, kaip naudoti veiksmą "ConnectToGit ", kad visa "Dataverse" aplinka būtų prijungta prie "Azure DevOps" saugyklos.

Užklausa

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

Response

HTTP/1.1 204 No Content
OData-Version: 4.0

Sužinokite, kaip iškviesti žiniatinklio API veiksmus

Prisijungimas prie GitHub saugyklos

Prieš naudodami API jungdamiesi prie GitHub, atlikite sąrankos veiksmus, kad sukurtumėte GitHub programą, įdiegtumėte ją paskirties saugykloje, importuokite privatų raktą į Azure Key Vault ir sukurkite "Power Platform" GitHub ryšį. Daugiau informacijos žr. Prisijungimas prie GitHub".

GitHub taikomosios programos konfigūracijos įrašo kūrimas naudojant žiniatinklio API

Norėdami sukurti githubappconfig įrašą, naudokite "Dataverse OData" žiniatinklio API. Siųskite POST užklausą naudodami GitHub taikomosios programos kliento ID, Key Vault URI ir rakto pavadinimą.

Šiems skambučiams galite naudoti bet kurį HTTP klientą, pvz., Nemiga, Visual Studio Code REST klientą arba garbanę. Norint autentifikuoti reikia lokio atpažinimo ženklo. Daugiau informacijos ieškokite Microsoft Dataverse žiniatinklio API naudojimas.

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

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

Svarbu

Atkreipkite dėmesį į atsakymo antraštėje grąžintą įrašo ID. Jums reikia šios reikšmės, kad nustatytumėte valdomą tapatybę, sukonfigūruotumėte RBAC ir iškviestumėte ConnectToGit. Įrašo ID naudoja formatą, pvz., 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Sukūrę GitHub taikomosios programos konfigūracijos įrašą, priskirkite Key Vault Crypto vartotojo vaidmenį "Dataverse" valdomai tapatybei, kaip aprašyta skyriuje Key Vault vaidmenimis pagrįsto prieigos valdymo (RBAC) konfigūravimas.

Iškvieskite "ConnectToGit" API

githubappconfig Sukūrę įrašą ir sukonfigūravę Key Vault RBAC, naudokite "Dataverse" žiniatinklio API, kad nustatytumėte šaltinio valdymo ryšį iškviesdami ConnectToGit veiksmą.

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

Svarbu

Šaka turi būti saugykloje. Jei reikia, pirmiausia sukurkite jį GitHub. Reikšmė GitHubAppConfigId turi naudoti formatą githubappconfigs(<recordId>).

Jei gausite sėkmingą atsakymą, aplinka bus prijungta prie GitHub.

Prisijungimas prie GitHub saugyklos naudojant "PowerShell"

Toliau pateiktame "PowerShell" pavyzdyje sukuriamas GitHub taikomosios programos konfigūracijos įrašas, laukiama, kol "Dataverse" valdoma tapatybė bus rodoma Microsoft Entra ID, priskiria Key Vault šifravimo vartotojo vaidmenį valdomai tapatybei ir iškviečia ConnectToGit veiksmą. Jei jau turite GitHub taikomosios programos konfigūravimo įrašą, nurodykite GitHubAppConfigId praleisti konfigūravimo ir Key Vault vaidmens priskyrimo veiksmus.

Įdiekite ir importuokite Az.Accounts, Az.KeyVaultir Az.Resources "PowerShell" modulius prieš paleisdami pavyzdį. Prisijunkite naudodami Connect-AzAccount paskyrą, kuri turi prieigą prie "Dataverse" aplinkos ir teisę priskirti Key Vault vaidmenis.

Jei "Dataverse" aplinkoje įgalintas virtualaus tinklo (VNET) palaikymas, pateikite GitHubPAT. GitHub ryšių negalima naudoti su virtualiojo tinklo palaikymu.

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

Visos "Dataverse" aplinkos atjungimas nuo "Git" šaltinio valdiklio

Šis veiksmas pašalina aplinkos lygio Git ryšį. Nenaudokite parametro SolutionUniqueName šiai operacijai. "Dataverse" automatiškai identifikuoja ir pašalina aplinkos lygio "Git" ryšį.

Šiame pavyzdyje parodyta, kaip naudoti veiksmą DisconnectFromGit , kad atjungtumėte visą "Dataverse" aplinką nuo "Git" šaltinio valdiklio.

Užklausa

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

Response

HTTP/1.1 204 No Content
OData-Version: 4.0

Sužinokite, kaip iškviesti žiniatinklio API veiksmus

Prijunkite pirmąjį sprendimą prie "Git" saugyklos

Šis ryšys sukuria saugyklos saitą ir aplanko struktūrą, skirtą sprendimo lygio šaltinio valdymui su pirmuoju sprendimu aplinkoje.

Norėdami nurodyti sprendimą, turite įtraukti šių parametrų reikšmes:

  • RootFolder
  • SolutionUniqueName

Šiame pavyzdyje parodyta, kaip naudoti veiksmą "ConnectToGit ", kad pirmasis sprendimas būtų prijungtas prie "Git" saugyklos.

Užklausa

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

Response

HTTP/1.1 204 No Content
OData-Version: 4.0

Sužinokite, kaip iškviesti žiniatinklio API veiksmus

Prijungę pradinį sprendimą prijunkite papildomus sprendimus prie tos pačios "Git" saugyklos

Prijungus pirmąjį sprendimą, jums reikia tik konkretaus sprendimo parametrų. Saugyklos ryšio informaciją paveldėsite iš pradinio ryšio.

Nustatykite tik šiuos parametrus:

  • SolutionUniqueName
  • Branch
  • GitFolder

Svarbu

Pirmiausia turite prijungti pirmąjį sprendimą, kad tai veiktų. Žr. Pirmojo sprendimo prijungimas prie "Git" saugyklos.

Šiame pavyzdyje parodyta, kaip naudoti veiksmą ConnectToGit , kad vėlesni sprendimai būtų prijungti prie "Git" saugyklos.

Užklausa

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

Response

HTTP/1.1 204 No Content
OData-Version: 4.0

Sužinokite, kaip iškviesti žiniatinklio API veiksmus

Konkretaus sprendimo atjungimas nuo "Git" šaltinio valdiklio, išlaikant prijungtus kitus sprendimus

Naudokite šį metodą, jei norite pašalinti vieno sprendimo šaltinio kontrolę, nepaveikdami kitų.

Šiame pavyzdyje parodyta, kaip naudoti veiksmą DisconnectFromGit , kad pašalintumėte vieno sprendimo šaltinio valdiklį nepaveikdami kitų.

Užklausa

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

Response

HTTP/1.1 204 No Content
OData-Version: 4.0

Sužinokite, kaip iškviesti žiniatinklio API veiksmus

Klaidų tvarkymas

Nei nei ConnectToGitDisconnectFromGit API negrąžina reikšmės, kai ji sėkmingai baigiama. Kai API nepavyksta, ji pateikia klaidą.

Dažniausi klaidų scenarijai:

  • Netinkami kredencialai: įsitikinkite, kad turite galiojantį "Git" teikėjo autentifikavimą.
  • Saugykla nerasta: patikrinkite organizacijos, projekto ir saugyklos pavadinimus.
  • Leidimas uždraustas: įsitikinkite, kad jūsų "Dataverse" paskyra turi šaltinio valdymo teises.
  • Sprendimas nerastas: patikrinkite, ar SolutionUniqueName jūsų aplinkoje yra.
  • Šakos nėra: patvirtinkite, kad saugykloje yra nurodyta šaka.

Palaikymas ir papildomi ištekliai

Daugiau informacijos apie šaltinio valdiklio integravimą su "Dataverse" žr.:

  • Last updated on