Dataverse csatlakoztatása és leválasztása Git-adattárból kód használatával

A ConnectToGit és DisconnectFromGit API-k segítségével programozottan integrálhatja a Microsoft Dataverse környezetet a Git forrásvezérlővel. Ezen API-k használatával egyes megoldásokat vagy teljes környezeteket csatlakoztathat a támogatott Git-adattárakhoz, és kóddal kezelheti ezeket a kapcsolatokat.

Prerequisites

Az API-k használata előtt győződjön meg arról, hogy a következőkre van szüksége:

  • Hozzáférés Microsoft Dataverse-környezethez
  • Rendszergazdai engedélyek
  • Git-adattárhoz való olvasási és írási hozzáférés

ConnectToGit API

Kapcsolatot hoz létre egy Dataverse-megoldás vagy -környezet és egy Git-adattár között. Ezzel a kapcsolattal kezelheti a Dataverse-összetevők forrásvezérlését.

Parameters

Az ConnectToGit API a következő paramétereket fogadja el:

Paraméter Típus Szükséges Description
GitFolder String Igen Annak a mappának a neve, amelyhez a megoldást vagy a környezetet hozzá szeretné kötni.
Branch String Igen Annak az ágnak a neve, amelyhez csatlakozni szeretne.
ConnectionType Integer No Meghatározza, hogy mihez kell csatlakozni. Lásd ConnectionType paraméter.
GitProvider Integer No A Git-szolgáltató. Lásd: GitProvider paraméter.
Organization String No Annak a szervezetnek a neve, amelyhez csatlakozni szeretne.
Project String No Annak a projektnek a neve, amelyhez csatlakozni szeretne.
Repository String No Annak az adattárnak a neve, amelyhez csatlakozni szeretne.
RootFolder String No Annak a gyökérmappának a neve, amelyben az összes megoldás a megoldás hatókörében található.
SolutionUniqueName String No A githez csatlakozni kívánt megoldás egyedi neve.
UpstreamBranch String No Annak a felső ágnak a neve, amelyhez csatlakozni szeretne. Alapértelmezésben az adattár alapértelmezett elágazása.
GitHubConnectionId String No A Power Platform GitHub kapcsolatazonosítója. Kötelező, ha a(z) GitProvider értéke 1, kivéve, ha megadja a(z) GitHubPAT értéket. Nem használható, ha a virtuális hálózat (VNET) támogatása engedélyezve van a Dataverse-környezetben.
GitHubPAT String No GitHub személyes hozzáférési token, amely hozzáféréssel rendelkezik a céltárolóhoz. Kötelező, ha a(z) GitProvider értéke 1, kivéve, ha megadja a következőt: GitHubConnectionId. Akkor szükséges, ha a virtuális hálózat (VNET) támogatása engedélyezve van a Dataverse-környezethez.
GitHubAppConfigId String No Hivatkozás az GitHub alkalmazáskonfigurációs rekordra. Kötelező, ha GitProvider van 1. Használja a következő formátumot: githubappconfigs(<recordId>).

ConnectionType paraméter

A ConnectionType paraméter azt szabályozza, hogy a teljes Dataverse-környezethez vagy egy adott megoldáshoz csatlakozik-e.

Érték Címke Description
0 Megoldás Egy adott Dataverse-megoldást csatlakoztat a Githez.
1 Környezet A teljes Dataverse-környezetet összekapcsolja a Gittel.

GitProvider paraméter

A paraméterrel GitProvider megadhatja a használt Git-szolgáltató típusát, akár az Azure DevOps, akár a GitHub.

Érték Címke Description
0 Azure DevOps Az Azure DevOpsban üzemeltetett adattárakhoz használható
1 GitHub GitHubon üzemeltetett adattárakhoz használható

DisconnectFromGit API

Eltávolítja a Git-kapcsolatot egy Dataverse-megoldásból vagy -környezetből, és letiltja a forrásvezérlés integrációját.

Paraméter

Az DisconnectFromGit API-nak csak egy paramétere van.

Paraméter Típus Szükséges Description
SolutionUniqueName String No A Gittől leválasztani kívánt megoldás egyedi neve. Ne végezze el az összes megoldás vagy környezet leválasztását.

További információk

Íme néhány paraméterérték-beállítás, amelyeket meg kell adni a meghíváskor DisconnectFromGit.

  • Egyetlen megoldás leválasztása: Adja meg a(z) SolutionUniqueName elemet egy adott megoldás leválasztásához.
  • Az összes megoldás leválasztása: Ne adjon meg paramétereket az összes megoldásszintű kapcsolat leválasztásához.
  • Környezet leválasztása: Ne adjon meg paramétereket a környezeti szintű kapcsolat leválasztásához.

Példák

Az alábbi példák a DisconnectFromGit és ConnectToGit API-k használatának különböző forgatókönyveit ismertetik:

A teljes Dataverse-környezet csatlakoztatása egy Azure DevOps-adattárhoz

Ez a kapcsolat lehetővé teszi a forrásvezérlést az összes környezeti szintű konfigurációhoz és összetevőhöz.

Ne használja ezeket a paramétereket ezzel a kapcsolattal:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Ez a példa bemutatja, hogyan csatlakoztathatja a teljes Dataverse-környezetet egy Azure DevOps-adattárhoz a ConnectToGit művelettel .

kérelem

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

Válasz

HTTP/1.1 204 No Content
OData-Version: 4.0

A webes API-műveletek meghívásának ismertetése

Csatlakozás GitHub adattárhoz

Mielőtt az API-t használva csatlakozik GitHub, végezze el a beállítási lépéseket a GitHub alkalmazás létrehozásához, a céladattárba való telepítéséhez, a titkos kulcs Azure Key Vault való importálásához és a Power Platform GitHub kapcsolat létrehozásához. További információ: Csatlakozás GitHub.

GitHub alkalmazáskonfigurációs rekord létrehozása a Webes API használatával

A Dataverse OData Webes API használatával hozzon létre egy rekordot githubappconfig . Post kérés küldése az GitHub alkalmazás ügyfélazonosítójával, Key Vault URI-val és kulcsnévvel.

Ezeket a hívásokat bármely HTTP-ügyfél, például az Insomnia, Visual Studio Code REST-ügyfél vagy curl használatával kezdeményezheti. A hitelesítéshez bearer tokenre van szükség. További információ: A Microsoft Dataverse Webes API használata.

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

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

Important

Jegyezze fel a válaszfejlécben visszaadott rekordazonosítót. Ez az érték a felügyelt identitás azonosításához, az RBAC konfigurálásához és a híváshoz ConnectToGitszükséges. A rekordazonosító olyan formátumot használ, mint a 13d565bb-4c22-f111-a546-7ced8d6e3e85.

A GitHub alkalmazáskonfigurációs rekord létrehozása után rendelje hozzá a Key Vault Titkosítási felhasználó szerepkört a Dataverse által felügyelt identitáshoz a Key Vault Szerepköralapú hozzáférés-vezérlés konfigurálása (RBAC) című cikkben leírtak szerint.

A ConnectToGit API meghívása

Miután létrehozta a githubappconfig rekordot, és konfigurálta Key Vault RBAC-t, a Dataverse Web API-val hozza létre a forrásvezérlő kapcsolatot a ConnectToGit művelet meghívásával.

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

Important

Az ágnak már léteznie kell az adattárban. Szükség esetén először hozza létre a GitHubon. Az GitHubAppConfigId értéknek a formátumot githubappconfigs(<recordId>)kell használnia.

Képernyőkép a ConnectToGit API HTTP-kérelemtörzséről GitHub paraméterekkel.

Ha sikeres választ kap, a környezet csatlakozik a GitHubhoz.

Csatlakozás GitHub-adattárhoz a PowerShell használatával

A következő PowerShell-példa létrehozza a GitHub alkalmazáskonfigurációs rekordot, megvárja, amíg a Dataverse által felügyelt identitás megjelenik a Microsoft Entra ID, hozzárendeli a Key Vault Crypto User szerepkört a felügyelt identitáshoz, és meghívja a ConnectToGit műveletet. Ha már rendelkezik GitHub-alkalmazás konfigurációs rekordjával, adja meg a(z) GitHubAppConfigId értéket a konfigurációs és a Key Vault-szerepkör hozzárendelési lépések kihagyásához.

A példa futtatása előtt telepítse és importálja a Az.Accounts, Az.KeyVaultés Az.Resources PowerShell-modulokat. Jelentkezzen be Connect-AzAccount olyan fiókkal, amely hozzáféréssel rendelkezik a Dataverse-környezethez, és jogosult Key Vault szerepkörök hozzárendelésére.

Ha a virtuális hálózat (VNET) támogatása engedélyezve van a Dataverse-környezetben, adja meg: GitHubPAT GitHub kapcsolatok nem használhatók a virtuális hálózat támogatásával.

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

Válassza le a teljes Dataverse-környezetet a Git forrásvezérlésről

Ez a művelet eltávolítja a környezetszintű Git-kapcsolatot. Ehhez a művelethez ne használja a SolutionUniqueName paramétert. A Dataverse automatikusan azonosítja és eltávolítja a környezetszintű Git-kapcsolatot.

Ez a példa bemutatja, hogyan lehet a DisconnectFromGit művelettel leválasztani a teljes Dataverse-környezetet a Git-forrásvezérlőről.

kérelem

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

Válasz

HTTP/1.1 204 No Content
OData-Version: 4.0

A webes API-műveletek meghívásának ismertetése

Az első megoldás csatlakoztatása Egy Git-adattárhoz

Ez a kapcsolat létrehozza az adattárhivatkozást és a mappastruktúrát a megoldásszintű forrásvezérléshez a környezet első megoldásához.

A megoldás megadásához meg kell adnia az alábbi paraméterek értékeit:

  • RootFolder
  • SolutionUniqueName

Ez a példa bemutatja, hogyan csatlakoztathatja az első megoldást egy Git-adattárhoz a ConnectToGit művelettel .

kérelem

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

Válasz

HTTP/1.1 204 No Content
OData-Version: 4.0

A webes API-műveletek meghívásának ismertetése

További megoldások csatlakoztatása ugyanahhoz a Git-adattárhoz a kezdeti megoldás csatlakoztatása után

Az első megoldás csatlakoztatása után csak a megoldásspecifikus paraméterekre lesz szüksége. Az adattár kapcsolati adatait a kezdeti kapcsolattól örökli.

Csak ezeket a paramétereket állítsa be:

  • SolutionUniqueName
  • Branch
  • GitFolder

Important

Először csatlakoztatnia kell az első megoldást, mielőtt ez működik. Lásd : Az első megoldás csatlakoztatása egy Git-adattárhoz.

Ez a példa bemutatja, hogyan csatlakoztathat további megoldásokat egy Git-adattárhoz a ConnectToGit művelettel .

kérelem

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

Válasz

HTTP/1.1 204 No Content
OData-Version: 4.0

A webes API-műveletek meghívásának ismertetése

Egy adott megoldás leválasztása a Git-forrásvezérlőről más megoldások csatlakoztatása mellett

Ezzel a módszerrel eltávolíthatja az egyik megoldás forrásvezérlését anélkül, hogy másokat érintenének.

Ez a példa bemutatja, hogyan távolíthatja el az egyik megoldás forrásvezérlőjét a DisconnectFromGit művelet használatával anélkül, hogy másokat érintenének.

kérelem

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

Válasz

HTTP/1.1 204 No Content
OData-Version: 4.0

A webes API-műveletek meghívásának ismertetése

Hibakezelés

Sem a ConnectToGit, sem a DisconnectFromGit API nem ad vissza értéket, amikor sikeresen befejeződik. Ha egy API meghibásodik, hibát ad vissza.

A gyakori hibaesetek a következők:

  • Érvénytelen hitelesítő adatok: Győződjön meg arról, hogy érvényes hitelesítést használ a Git-szolgáltatóhoz.
  • Az adattár nem található: Ellenőrizze a szervezet, a projekt és az adattár nevét.
  • Engedély megtagadva: Győződjön meg arról, hogy Dataverse-fiókja rendelkezik forrásvezérlési felügyeleti engedélyekkel.
  • A megoldás nem található: Ellenőrizze, hogy létezik-e a SolutionUniqueName környezetben.
  • Az ág nem létezik: Ellenőrizze, hogy a megadott ág létezik-e az adattárban.

Támogatás és további erőforrások

A Dataversevel való forráskövetési integrációval kapcsolatos további információkért lásd:

  • Utolsó frissítés időpontja: