Pripojte a odpojte Dataverse od Git repozitára pomocou kódu

Použite ConnectToGit API a DisconnectFromGit na programatickú integráciu vášho Microsoft Dataverse prostredia s Git source control. Pomocou týchto rozhraní API môžete prepojiť jednotlivé riešenia alebo celé prostredia s podporovanými odkladacími priestormi Git a spravovať tieto pripojenia prostredníctvom kódu.

Požiadavky

Pred použitím týchto API sa uistite, že máte:

  • Prístup do prostredia Microsoft Dataverse
  • Oprávnenia správcu systému
  • Prístup na čítanie a zápis do Git repozitára

ConnectToGit API

Vytvára spojenie medzi riešením alebo prostredím Dataverse a Git repozitárom. Použitím tohto pripojenia môžete spravovať správu zdrojového kódu pre vaše komponenty v Dataverse.

Parametre

API ConnectToGit prijíma nasledujúce parametre:

Parameter Zadať Required Description
GitFolder Povrázok Áno Názov priečinka, ku ktorému chcete priradiť riešenie alebo prostredie.
Branch Povrázok Áno Názov pobočky, ku ktorej sa chcete pripojiť.
ConnectionType Celé číslo Nie Špecifikuje, na čo sa pripojiť. Pozri parameter ConnectionType.
GitProvider Celé číslo Nie Git poskytovateľ. Pozri parameter GitProvider.
Organization Povrázok Nie Názov organizácie, s ktorou sa chcete spojiť.
Project Povrázok Nie Názov projektu, ku ktorému sa chcete pripojiť.
Repository Povrázok Nie Názov repozitára, ku ktorému sa chcete pripojiť.
RootFolder Povrázok Nie Názov koreňového priečinka, kde sa nachádzajú všetky vaše riešenia v rozsahu riešenia.
SolutionUniqueName Povrázok Nie Jedinečný názov riešenia, ktoré chcete pripojiť k gitu.
UpstreamBranch Povrázok Nie Názov vetvy upstream, ku ktorej sa chcete pripojiť. Predvolene sa nastavuje na predvolenú vetvu repozitára.
GitHubConnectionId Povrázok Nie ID pripojenia pre GitHub pripojenie Power Platform. Vyžaduje sa, ak GitProvider nie je 1 zadáte GitHubPAT. Nedá sa použiť, ak je pre prostredie Dataverse povolená podpora virtuálnej siete (VNET).
GitHubPAT Povrázok Nie GitHub osobný prístupový token s prístupom do cieľového odkladacieho priestoru. Vyžaduje sa, ak GitProvider nie je 1 zadáte GitHubConnectionId. Vyžaduje sa, ak je pre prostredie Dataverse povolená podpora virtuálnej siete (VNET).
GitHubAppConfigId Povrázok Nie Odkaz na GitHub záznam konfigurácie aplikácie. Povinné, keď GitProvider je 1. Použite formát githubappconfigs(<recordId>).

Parameter ConnectionType

Parameter ConnectionType určuje, či sa pripojíme k celému Dataverse prostrediu alebo k konkrétnemu riešeniu.

Hodnota Označenie Description
0 Solution Spája konkrétne Dataverse riešenie s Gitom.
1 Environment Prepája celé prostredie Dataverse s Gitom.

Parameter GitProvider

Použite GitProvider parameter na určenie typu poskytovateľa Gitu, ktorý používate, buď Azure DevOps alebo GitHub.

Hodnota Označenie Description
0 Azure DevOps Použitie pre repozitáre hostované na Azure DevOps
1 GitHub Použitie pre repozitáre hostované na GitHube

DisconnectFromGit API

Odstraňuje pripojenie Git z riešenia alebo prostredia Dataverse a deaktivuje integráciu správy zdrojového kódu.

Parameter

API DisconnectFromGit má len jeden parameter.

Parameter Zadať Required Description
SolutionUniqueName Povrázok Nie Jedinečný názov riešenia, ktoré chcete odpojiť od Gitu. Vynechajte odpojenie všetkých riešení alebo prostredia.

Ďalšie informácie

Tu je niekoľko možností hodnôt parametrov, ktoré treba špecifikovať pri volaní DisconnectFromGit.

  • Odpojte jedno riešenie: Zabezpečte SolutionUniqueName odpojenie konkrétneho riešenia.
  • Odpojte všetky riešenia: Neposkytujte žiadne parametre na odpojenie všetkých pripojení na úrovni riešenia.
  • Prostredie na odpojenie: Neuvádzajte žiadne parametre na odpojenie spojenia na úrovni prostredia.

Príklady

Nasledujúce príklady popisujú scenáre používania ConnectToGit rozhraní a API DisconnectFromGit :

Pripojte celé svoje prostredie Dataverse k Azure DevOps repozitáru

Toto pripojenie umožňuje správu zdrojového kódu pre všetky konfigurácie a komponenty na úrovni prostredia.

Nepoužívajte tieto parametre s týmto pripojením:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Tento príklad ukazuje, ako použiť akciu ConnectToGit na prepojenie celého vášho Dataverse prostredia s Azure DevOps repozitárom.

Žiadosť

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

odpoveď

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučte sa, ako volať akcie Web API

Pripojenie k odkladaciemu priestoru GitHub

Skôr než použijete rozhranie API na pripojenie k GitHub, vykonajte kroky nastavenia a vytvorte aplikáciu GitHub, nainštalujte ju do cieľového odkladacieho priestoru, importujte jeho súkromný kľúč do Azure Key Vault a vytvorte pripojenie GitHub Power Platform. Ďalšie informácie nájdete v téme Pripojenie k GitHub.

Vytvorenie konfiguračného záznamu aplikácie GitHub pomocou webového rozhrania API

Na vytvorenie githubappconfig záznamu použite webové rozhranie Dataverse OData. Odošlite požiadavku POST s ID klienta aplikácie GitHub, identifikátorom URI Key Vault a názvom kľúča.

Na vykonanie týchto volaní môžete použiť ľubovoľného klienta HTTP, ako je napríklad Nespavosť, Visual Studio Code klienta REST alebo zložený názov. Na overenie potrebujete nosný token. Ďalšie informácie nájdete v téme Použitie rozhrania Microsoft Dataverse webového rozhrania API.

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

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

Dôležité

Všimnite si ID záznamu vrátené v hlavičke odpovede. Túto hodnotu potrebujete na identifikáciu spravovanej identity, konfiguráciu rbac a volanie ConnectToGit. ID záznamu používa formát, ako 13d565bb-4c22-f111-a546-7ced8d6e3e85napríklad .

Po vytvorení záznamu konfigurácie aplikácie služby GitHub priraďte rolu používateľa Key Vault Crypto k spravovanej identite Dataverse, ako je popísané v téme Konfigurácia Key Vault riadenia prístupu na základe rolí (RBAC) .

Volanie rozhrania API connectToGit

Po vytvorení záznamu githubappconfig a konfigurácii Key Vault RBAC použite rozhranie Dataverse Web API na vytvorenie pripojenia ovládacieho prvku ConnectToGit zdroja zavolaním akcie.

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

Dôležité

Vetva už musí existovať v odkladacom priestore. Ak je to potrebné, najskôr ho vytvorte v GitHub. Hodnota GitHubAppConfigId musí používať formát githubappconfigs(<recordId>).

Snímka obrazovky tela požiadavky HTTP pre rozhranie API ConnectToGit s parametrami GitHub.

Ak sa zobrazí úspešná odpoveď, prostredie je pripojené k službe GitHub.

Pripojenie k odkladaciemu priestoru GitHub pomocou prostredia PowerShell

Nasledujúci príklad prostredia PowerShell vytvorí konfiguračný záznam aplikácie GitHub, počká, kým sa na Microsoft Entra ID zobrazí spravovaná identita Dataverse, priradí spravovanej identite rolu Key Vault Crypto User a zavolá ConnectToGit akciu. Ak už máte GitHub záznam konfigurácie aplikácie, zadajteGitHubAppConfigId, aby ste vynechali konfiguráciu a Key Vault kroky priradenia rolí.

Pred spustením príkladu Az.Accountsnainštalujte a importujte moduly , Az.KeyVaulta Az.Resources PowerShell. Prihláste Connect-AzAccount sa pomocou konta, ktoré má prístup k prostrediu Dataverse, a povolenia na priradenie rolí Key Vault.

Ak je pre prostredie Dataverse povolená podpora virtuálnej siete (VNET), zadajte GitHubPAT. GitHub pripojenia nemožno používať s podporou virtuálnej siete.

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

Odpojte celé svoje prostredie Dataverse od správy zdrojového kódu v Gite

Táto akcia odstraňuje pripojenie Git na úrovni prostredia. Parameter pre túto operáciu nepoužívajte SolutionUniqueName . Dataverse automaticky identifikuje a odstraňuje pripojenie Git na úrovni prostredia.

Tento príklad ukazuje, ako použiť akciu DisconnectFromGit na odpojenie celého vášho prostredia Dataverse od správy zdrojového kódu Gitu.

Žiadosť

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

odpoveď

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučte sa, ako volať akcie Web API

Pripojte prvé riešenie k Git repozitáru

Toto spojenie vytvára väzbu a štruktúru priečinkov repozitára pre správu zdrojového kódu na úrovni riešenia k prvému riešeniu v prostredí.

Musíte zahrnúť hodnoty týchto parametrov, aby ste špecifikovali riešenie:

  • RootFolder
  • SolutionUniqueName

Tento príklad ukazuje, ako použiť akciu ConnectToGit na prepojenie prvého riešenia s Git repozitárom.

Žiadosť

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

odpoveď

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučte sa, ako volať akcie Web API

Pripojte ďalšie riešenia do toho istého Git repozitára po pripojení počiatočného riešenia

Po pripojení prvého riešenia potrebujete už len parametre špecifické pre dané riešenie. Údaje o spojení repozitára zdedíte z pôvodného spojenia.

Nastavte len tieto parametre:

  • SolutionUniqueName
  • Branch
  • GitFolder

Dôležité

Najprv musíte pripojiť prvé riešenie, aby to fungovalo. Pozri Pripojiť prvé riešenie k Git repozitáru.

Tento príklad ukazuje, ako použiť akciu ConnectToGit na prepojenie nasledujúcich riešení s Git repozitárom.

Žiadosť

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

odpoveď

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučte sa, ako volať akcie Web API

Odpojte konkrétne riešenie od správy zdrojového kódu v Gite, pričom ostatné riešenia ponechajte pripojené

Použite tento prístup na odstránenie správy zdrojového kódu pre jedno riešenie bez ovplyvnenia ostatných.

Tento príklad ukazuje, ako použiť akciu DisconnectFromGit na odstránenie správy zdrojového kódu pre jedno riešenie bez ovplyvnenia ostatných.

Žiadosť

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

odpoveď

HTTP/1.1 204 No Content
OData-Version: 4.0

Naučte sa, ako volať akcie Web API

Spracovanie chýb

Ani the ConnectToGit ani API nevrátia DisconnectFromGit hodnotu pri úspešnom dokončení. Keď API zlyhá, vráti chybu.

Bežné chybové scenáre zahŕňajú:

  • Neplatné prihlasovacie údaje: Uistite sa, že máte platnú autentifikáciu u poskytovateľa Gitu.
  • Repozitár nenájdený: Overte organizáciu, projekt a názvy repozitárov.
  • Povolenie zamietnuté: Uistite sa, že váš účet v Dataverse má oprávnenia na správu správy zdrojového kódu.
  • Riešenie sa nenašlo: Overte, či existuje SolutionUniqueName vo vašom prostredí.
  • Vetva neexistuje: Potvrďte, že špecifikovaná vetva existuje v repozitári.

Podpora a ďalšie zdroje

Pre viac informácií o integrácii správy zdrojového kódu s Dataverse pozri:

  • Naposledy aktualizované: