Konektatu eta deskonektatu Dataverse Git biltegi batetik kodea erabiliz

Erabili ConnectToGit eta DisconnectFromGit APIak zure Microsoft Dataverse ingurunea Git iturburu-kontrolarekin programatikoki integratzeko. API hauek erabiliz, soluzio indibidualak edo ingurune osoak Git biltegi onartuetara konekta ditzakezu eta konexio horiek kodearen bidez kudeatu.

Aurrebaldintzak

API hauek erabili aurretik, ziurtatu honako hauek dituzula:

  • Microsoft Dataverse ingurunerako sarbidea
  • Sistema-administratzailearen baimenak
  • Git biltegi baterako irakurketa- eta idazketa-sarbidea

ConnectToGit APIa

Dataverse-ren irtenbide edo ingurune baten eta Git biltegi baten arteko konexioa sortzen du. Konexio hau erabiliz, Dataverse-ren osagaien iturburu-kontrola kudea dezakezu.

Parametroak

APIak ConnectToGit honako parametro hauek onartzen ditu:

Parametroa Mota Beharrezkoa Deskribapenak
GitFolder String Bai Irtenbidea edo ingurunea lotu nahi duzun karpetaren izena.
Branch String Bai Konektatu nahi duzun adarraren izena.
ConnectionType Oso-osoa Ez Zehazten du zertara konektatu behar den. Ikus ConnectionType parametroa.
GitProvider Oso-osoa Ez Git hornitzailea. Ikus GitProvider parametroa.
Organization String Ez Konektatu nahi duzun erakundearen izena.
Project String Ez Konektatu nahi duzun proiektuaren izena.
Repository String Ez Konektatu nahi duzun biltegiaren izena.
RootFolder String Ez Soluzio guztiak soluzioaren esparruan dauden erroko karpetaren izena.
SolutionUniqueName String Ez Git-era konektatu nahi duzun soluzioaren izen esklusiboa.
UpstreamBranch String Ez Konektatu nahi duzun upstream adarraren izena. Lehenespenez, biltegiaren adar lehenetsia da.
GitHubConnectionId String Ez Power Platform GitHub konexioaren konexio ID-a. Derrigorrezkoa denean GitProvider1 da, salbu eta ez baduzu ematen GitHubPAT. Ezin da erabili sare birtualaren (VNET) euskarria Dataverse ingurunean gaituta dagoenean.
GitHubPAT String Ez GitHub sarbide pertsonaleko token helburu biltegira sarbidea duena. Derrigorrezkoa denean GitProvider1 da, salbu eta ez baduzu ematen GitHubConnectionId. Dataverse ingurunerako sare birtualeko (VNET) laguntza gaituta dagoenean beharrezkoa da.
GitHubAppConfigId String Ez GitHub App konfigurazio erregistroaren erreferentzia. Beharrezkoa denean GitProvider1. Erabili formatua githubappconfigs(<recordId>).

ConnectionType parametroa

Parametroak ConnectionType Dataverse ingurune osoarekin edo irtenbide zehatz batera konektatu behar den ala ez kontrolatzen du.

Balioa Etiketa Deskribapenak
0 Soluzioa Dataverse irtenbide zehatz bat Git-ekin konektatzen du.
1 Ingurunea Dataverse ingurune osoa Git-ekin konektatzen du.

GitProvider parametroa

Erabili parametroa GitProvider erabiltzen ari zaren Git hornitzaile mota zehazteko, Azure DevOps edo GitHub.

Balioa Etiketa Deskribapenak
0 Azure DevOps Erabili Azure DevOps-en ostatatutako biltegietarako
1 GitHub Erabili GitHub-en ostatatutako biltegietarako

DisconnectFromGit APIa

Git konexioa Dataverse-ren irtenbide edo ingurune batetik kentzen du, eta iturburu-kontrolaren integrazioa desgaitzen du.

Parametroa

APIak DisconnectFromGit parametro bakarra du.

Parametroa Mota Beharrezkoa Deskribapenak
SolutionUniqueName String Ez Git-etik deskonektatu nahi duzun soluzioaren izen esklusiboa. Irtenbide guztiak edo ingurumena deskonektatzea.

Informazio gehigarria

Hona hemen deitzerakoan DisconnectFromGitzehaztu beharreko parametro-balio aukera batzuk.

  • Deskonektatu irtenbide bakarra: Eman SolutionUniqueName irtenbide zehatz bat deskonektatzeko.
  • Deskonektatu irtenbide guztiak: ez eman parametrorik soluzio mailako konexio guztiak deskonektatzeko.
  • Deskonektatu ingurunea: ez eman parametrorik ingurune mailako konexioa deskonektatzeko.

Adibideak

Hurrengo adibideek eta DisconnectFromGit APIak erabiltzeko ConnectToGit egoerak deskribatzen dituzte:

Konektatu zure Dataverse ingurune osoa Azure DevOps biltegi batera

Konexio honek ingurune mailako konfigurazio eta osagai guztien iturburu-kontrola ahalbidetzen du.

Ez erabili parametro hauek konexio honekin:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Adibide honek erakusten du nola erabili ConnectToGit ekintza zure Dataverse ingurune osoa Azure DevOps biltegi batera konektatzeko.

Eskaera

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

Erantzuna

HTTP/1.1 204 No Content
OData-Version: 4.0

Ikasi nola deitu Web APIaren ekintzak

GitHub biltegi batera konektatu

APIa erabili aurretik GitHub-era konektatzeko, egin GitHub aplikazioa sortzeko konfigurazio pausoak, instalatu helburu biltegian, inportatu bere gako pribatua Azure Key Vault-era eta sortu Power Platform GitHub konexioa. Informazio gehiago nahi izanez gero, ikusi Konektatu GitHub-era.

Sortu GitHub App konfigurazio erregistro bat Web APIa erabiliz

Erabili Dataverse OData Web API-a erregistro bat githubappconfig sortzeko. Bidali POST eskaera GitHub App bezero IDarekin, Key Vault URIarekin eta gako izenarekin.

Edozein HTTP bezero erabil dezakezu, hala nola Insomnia, Visual Studio Code REST Client edo curl, dei hauek egiteko. Egiaztapenerako eramale-token bat behar duzu. Informazio gehiago nahi izanez gero, ikus Erabili Microsoft Dataverse Web API.

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

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

Garrantzitsua

Kontuan hartu erantzun goiburuan agertzen den erregistro IDa. Balio hau behar duzu kudeatutako identitatea identifikatzeko, RBAC konfiguratzeko eta deitzeko ConnectToGit. Erregistro IDak formatu bat erabiltzen du, adibidez 13d565bb-4c22-f111-a546-7ced8d6e3e85.

GitHub App konfigurazio erregistroa sortu ondoren, Key Vault Crypto User rola esleitu Dataverse-ren kudeatutako identitateari, Configure Key Vault role-based access control (RBAC)-n deskribatzen den bezala.

Deitu ConnectToGit APIa

Erregistroa sortu githubappconfig eta Key Vault RBAC konfiguratu ondoren, erabili Dataverse Web API-a iturburu-kontrol konexioa ezartzeko ekintza deituzConnectToGit.

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

Garrantzitsua

Adarra dagoeneko egon behar du biltegian. Sortu lehenik GitHub-en behar bada. Balioak GitHubAppConfigId formatu githubappconfigs(<recordId>)hau erabili behar du .

ConnectToGit APIrako HTTP eskaera gorputzaren pantaila-argazkia GitHub parametroekin.

Erantzun arrakastatsua jasotzen baduzu, ingurunea GitHub-era konektatuta.

GitHub biltegi batera konektatu PowerShell erabiliz

Hurrengo PowerShell adibideak GitHub App konfigurazio erregistroa sortzen du, Dataverse kudeatutako identitatea Microsoft Entra ID-n agertzea itxaroten du, Key Vault Crypto User rola kudeatutako identitateari esleitzen dio, eta ekintza deitzen ConnectToGit du. Jada GitHub App konfigurazio erregistro bat baduzu, eman GitHubAppConfigId konfigurazio eta Key Vault-en rolen esleipenaren pausoak saltatzeko.

Instalatu eta inportatu Az.Accounts, Az.KeyVault, eta Az.Resources PowerShell moduluak adibidea exekutatu aurretik. Saioa hasi Connect-AzAccount Dataverse ingurunean sartzeko sarbidea eta Key Vault rolak esleitzeko baimena duen kontu batekin.

Dataverse ingurunerako sare birtualeko (VNET) laguntza gaituta badago, eman GitHubPAT. GitHub konexioak ezin dira erabili sare birtualeko laguntzarekin.

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

Deskonektatu Dataverse ingurune osoa Git-en iturburu-kontroletik

Ekintza honek ingurune mailako Git konexioa kentzen du. Ez erabili parametroa SolutionUniqueName eragiketa honetarako. Dataverse-k automatikoki identifikatu eta kentzen du ingurune mailako Git konexioa.

Adibide honek erakusten du nola erabili DisconnectFromGit ekintza Dataverse ingurune osoa Git iturburu-kontroletik deskonektatzeko.

Eskaera

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

Erantzuna

HTTP/1.1 204 No Content
OData-Version: 4.0

Ikasi nola deitu Web APIaren ekintzak

Konektatu lehenengo irtenbidea Git biltegi batera

Konexio honek biltegiaren esteka eta karpeta egitura ezartzen ditu irtenbide mailako iturburu-kontrola ingurune bateko lehen irtenbidera.

Parametro hauen balioak sartu behar dituzu irtenbidea zehazteko:

  • RootFolder
  • SolutionUniqueName

Adibide honek ConnectToGit ekintza nola erabili erakusten du lehen irtenbidea Git biltegi batera konektatzeko.

Eskaera

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

Erantzuna

HTTP/1.1 204 No Content
OData-Version: 4.0

Ikasi nola deitu Web APIaren ekintzak

Konektatu irtenbide gehigarriak Git biltegi berean, hasierako irtenbidea konektatu ondoren

Lehenengo irtenbidea konektatu ondoren, soluzioaren parametro espezifikoak baino ez dituzu behar. Biltegiko konexioaren xehetasunak hasierako konexiotik heredatzen dituzu.

Ezarri parametro hauek soilik:

  • SolutionUniqueName
  • Branch
  • GitFolder

Garrantzitsua

Lehenik eta behin, lehenengo irtenbidea konektatu behar duzu honek funtzionatu aurretik. Ikus Konektatu lehenengo irtenbidea Git biltegi batera.

Adibide honek ConnectToGit ekintza nola erabili erakusten du ondorengo irtenbideak Git biltegi batera konektatzeko.

Eskaera

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

Erantzuna

HTTP/1.1 204 No Content
OData-Version: 4.0

Ikasi nola deitu Web APIaren ekintzak

Deskonektatu irtenbide zehatz bat Git iturburu-kontroletik, beste irtenbide batzuk konektatuta mantenduz

Erabili planteamendu hau irtenbide baten iturburu-kontrola kentzeko, besteei eragin gabe.

Adibide honek erakusten du nola erabili DisconnectFromGit ekintza irtenbide bateko iturburu-kontrola kentzeko, besteei eragin gabe.

Eskaera

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

Erantzuna

HTTP/1.1 204 No Content
OData-Version: 4.0

Ikasi nola deitu Web APIaren ekintzak

Akatsen kontrola

Ez APIak ConnectToGit ez DisconnectFromGit du baliorik itzultzen ongi osatzen denean. API batek huts egiten duenean, errore bat itzultzen du.

Ohiko errore-agertoki hauek dira:

  • Kredentzial baliogabeak: ziurtatu Git hornitzailearen baliozko autentifikazioa duzula.
  • Biltegia ez da aurkitu: egiaztatu erakundearen, proiektuaren eta biltegiaren izenak.
  • Baimena ukatuta: ziurtatu zure Dataverse kontuak iturburu-kontrola kudeatzeko baimenak dituela.
  • Irtenbidea ez da aurkitu: egiaztatu zure ingurunean dagoela SolutionUniqueName .
  • Adarra ez da existitzen: baieztatu zehaztutako adarra biltegian dagoela.

Laguntza eta baliabide osagarriak

Dataverse-rekin iturburu-kontrolaren integrazioari buruzko informazio gehiago nahi izanez gero, ikus:

  • Last updated on