Připojení a odpojení Dataverse z úložiště Git pomocí kódu

Pomocí ConnectToGit a DisconnectFromGit rozhraní API můžete programaticky integrovat prostředí Microsoft Dataverse se systémem řízení verzí Git. Pomocí těchto rozhraní API můžete připojit jednotlivá řešení nebo celá prostředí k podporovaným úložištím Git a spravovat tato připojení prostřednictvím kódu.

Předpoklady

Před použitím těchto rozhraní API se ujistěte, že máte:

  • Přístup k prostředí Microsoft Dataverse
  • Oprávnění správce systému
  • Přístup ke čtení a zápisu do úložiště Git

ConnectToGit API

Vytvoří propojení mezi řešením Dataverse nebo prostředím a úložištěm Git. Pomocí tohoto připojení můžete spravovat správu zdrojového kódu pro komponenty Dataverse.

Parameters

Rozhraní ConnectToGit API přijímá následující parametry:

Parameter Typ Povinné Description
GitFolder String Ano Název složky, ke které chcete vytvořit vazbu vašeho řešení nebo prostředí
Branch String Ano Název větve, ke které se chcete připojit.
ConnectionType Celočíselný datový typ Ne Určuje, k čemu se má připojit. Přečtěte si parametr ConnectionType.
GitProvider Celočíselný datový typ Ne Poskytovatel Gitu. Viz parametr GitProvider.
Organization String Ne Název organizace, ke které se chcete připojit.
Project String Ne Název projektu, ke kterému se chcete připojit.
Repository String Ne Název úložiště, ke kterému se chcete připojit.
RootFolder String Ne Název kořenové složky, ve které se nacházejí všechna vaše řešení v oboru řešení.
SolutionUniqueName String Ne Jedinečný název řešení, ke kterému se chcete připojit k Gitu.
UpstreamBranch String Ne Název upstreamové větve, ke které se chcete připojit. Výchozí nastavení je výchozí větev úložiště.
GitHubConnectionId String Ne ID připojení pro připojení GitHub v Power Platform. Vyžaduje se, když je GitProviderGitHubPAT, pokud neposkytnete 1. Nejde použít, pokud je pro prostředí Dataverse povolená podpora virtuální sítě.
GitHubPAT String Ne GitHub osobní přístupový token s přístupem k cílovému úložišti. Vyžaduje se, pokud je GitProviderGitHubConnectionId, pokud nezadáte 1. Vyžaduje se, když je pro prostředí Dataverse povolená podpora virtuální sítě.
GitHubAppConfigId String Ne Odkaz na záznam konfigurace aplikace GitHub Vyžaduje se, pokud GitProvider je 1. Použijte formát githubappconfigs(<recordId>).

Parametr ConnectionType

Parametr ConnectionType určuje, jestli se chcete připojit k celému prostředí Dataverse nebo ke konkrétnímu řešení.

Hodnota Popisek Description
0 Řešení Připojí konkrétní řešení Dataverse k Gitu.
1 Prostředí Připojí celé prostředí Dataverse k Gitu.

Parametr poskytovatele Gitu

Pomocí parametru GitProvider určete typ zprostředkovatele Gitu, který používáte, a to buď Azure DevOps, nebo GitHub.

Hodnota Popisek Description
0 Azure DevOps Použití pro úložiště hostovaná v Azure DevOps
1 GitHub Použití pro úložiště hostovaná na GitHubu

Rozhraní API DisconnectFromGit

Odebere připojení Git z řešení Nebo prostředí Dataverse a zakáže integraci správy zdrojového kódu.

Parameter

Rozhraní DisconnectFromGit API má pouze jeden parametr.

Parameter Typ Povinné Description
SolutionUniqueName String Ne Jedinečný název řešení, které chcete odpojit od Gitu. Vynechejte odpojení všech řešení nebo prostředí.

Další informace

Tady je několik možností hodnoty parametru, které se mají určit při vyvolání DisconnectFromGit.

  • Odpojit konkrétní řešení: Poskytněte SolutionUniqueName k odpojení konkrétního řešení.
  • Odpojit všechna řešení: Nezadávejte žádné parametry pro odpojení všech připojení na úrovni řešení.
  • Odpojte prostředí: Nepoužívejte žádné parametry pro odpojení připojení na úrovni prostředí.

Příklady

Následující příklady popisují scénáře pro použití rozhraní API ConnectToGit a DisconnectFromGit:

Připojení celého prostředí Dataverse k úložišti Azure DevOps

Toto připojení umožňuje správu zdrojového kódu pro všechny konfigurace a komponenty na úrovni prostředí.

U tohoto připojení nepoužívejte tyto parametry:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Tento příklad ukazuje, jak pomocí akce ConnectToGit připojit celé prostředí Dataverse k úložišti Azure DevOps.

Žádost

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

odpověď

HTTP/1.1 204 No Content
OData-Version: 4.0

Zjistěte, jak vyvolat akce webového rozhraní API.

Připojení k úložišti GitHub

Než použijete rozhraní API pro připojení k GitHub, dokončete kroky nastavení a vytvořte aplikaci GitHub, nainstalujte ji do cílového úložiště, importujte jeho privátní klíč do Azure Key Vault a vytvořte připojení GitHub Power Platform. Další informace najdete v tématu Připojení k GitHub.

Vytvoření záznamu konfigurace aplikace GitHub pomocí webového rozhraní API

K vytvoření záznamu githubappconfig použijte webové rozhraní API Dataverse OData. Odešlete požadavek POST s ID klienta aplikace GitHub, Key Vault identifikátorem URI a názvem klíče.

K provádění těchto volání můžete použít libovolného klienta HTTP, například Insomnia, REST Client pro Visual Studio Code nebo curl. Pro ověření potřebujete nosný token. Další informace najdete v tématu Použití webového rozhraní API Microsoft Dataverse.

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

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

Important

Poznamenejte si ID záznamu vrácené v hlavičce odpovědi. Tuto hodnotu potřebujete k identifikaci spravované identity, konfiguraci RBAC a volání ConnectToGit. ID záznamu používá formát, například 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Po vytvoření záznamu konfigurace aplikace GitHub přiřaďte spravované identitě Dataverse roli Key Vault Crypto User, jak je popsáno v části Konfigurace řízení přístupu na základě rolí (RBAC) pro Key Vault.

Volání rozhraní API ConnectToGit

Po vytvoření záznamu githubappconfig a konfiguraci řízení přístupu na základě role (RBAC) pro Key Vault použijte webové rozhraní Dataverse API k navázání připojení ke správě zdrojového kódu voláním akce ConnectToGit.

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

Větev už musí existovat v úložišti. V případě potřeby ho nejprve vytvořte v GitHub. Hodnota GitHubAppConfigId musí používat formát githubappconfigs(<recordId>).

Snímek obrazovky s textem požadavku HTTP pro rozhraní CONNECTToGit API s parametry GitHub

Pokud obdržíte úspěšnou odpověď, prostředí se připojí k GitHub.

Připojení k úložišti GitHub pomocí PowerShellu

Následující příklad PowerShellu vytvoří záznam konfigurace GitHub aplikace, počká, až se spravovaná identita Dataverse zobrazí v Microsoft Entra ID, přiřadí roli Key Vault Crypto User spravované identitě a zavolá ConnectToGit akci. Pokud už máte záznam konfigurace aplikace GitHub App, zadejte GitHubAppConfigId, aby se přeskočily kroky konfigurace a přiřazení role ke službě Key Vault.

Před spuštěním příkladu Az.Accountsnainstalujte a naimportujte moduly , Az.KeyVaulta Az.Resources PowerShell. Přihlaste se pomocí Connect-AzAccount účtu, který má přístup k prostředí Dataverse a oprávnění k přiřazování rolí Key Vault.

Pokud je pro prostředí Dataverse povolená podpora virtuální sítě, zadejte GitHubPAT. GitHub připojení se nedají použít s podporou virtuální sítě.

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

Odpojení celého prostředí Dataverse od správy zdrojového kódu Gitu

Tato akce odebere připojení Git na úrovni prostředí. Pro tuto operaci nepoužívejte SolutionUniqueName parametr. Služba Dataverse automaticky identifikuje a odebere připojení Git na úrovni prostředí.

Tento příklad ukazuje, jak pomocí akce DisconnectFromGit odpojit celé prostředí Dataverse od správy zdrojového kódu Git.

Žádost

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

odpověď

HTTP/1.1 204 No Content
OData-Version: 4.0

Zjistěte, jak vyvolat akce webového rozhraní API.

Připojení prvního řešení k úložišti Git

Toto připojení vytvoří propojení úložiště a strukturu složek pro správu zdrojového kódu na úrovni řešení s prvním řešením v prostředí.

Abyste mohli určit řešení, musíte zahrnout hodnoty pro tyto parametry:

  • RootFolder
  • SolutionUniqueName

Tento příklad ukazuje, jak pomocí akce ConnectToGit připojit první řešení k úložišti Git.

Žádost

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

odpověď

HTTP/1.1 204 No Content
OData-Version: 4.0

Zjistěte, jak vyvolat akce webového rozhraní API.

Po připojení počátečního řešení připojte další řešení ke stejnému úložišti Git.

Po připojení prvního řešení potřebujete pouze parametry specifické pro řešení. Z počátečního připojení dědíte podrobnosti o připojení úložiště.

Nastavte pouze tyto parametry:

  • SolutionUniqueName
  • Branch
  • GitFolder

Important

Před tím, než to funguje, musíte nejprve připojit první řešení. Viz Připojení prvního řešení k úložišti Git.

Tento příklad ukazuje, jak pomocí akce ConnectToGit připojit následná řešení k úložišti Git.

Žádost

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

odpověď

HTTP/1.1 204 No Content
OData-Version: 4.0

Zjistěte, jak vyvolat akce webového rozhraní API.

Odpojení konkrétního řešení od správy zdrojového kódu Gitu při zachování připojení jiných řešení

Tento přístup použijte k odebrání správy zdrojového kódu pro jedno řešení, aniž by to ovlivnilo ostatní.

Tento příklad ukazuje, jak pomocí akce DisconnectFromGit odebrat správu zdrojového kódu pro jedno řešení, aniž by to ovlivnilo ostatní.

Žádost

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

odpověď

HTTP/1.1 204 No Content
OData-Version: 4.0

Zjistěte, jak vyvolat akce webového rozhraní API.

Zpracování chyb

ConnectToGit DisconnectFromGit Ani rozhraní API nevrací hodnotu po úspěšném dokončení. Když se rozhraní API nezdaří, vrátí chybu.

Mezi běžné scénáře chyb patří:

  • Neplatné přihlašovací údaje: Ujistěte se, že máte platné ověřování u poskytovatele Gitu.
  • Úložiště se nenašlo: Ověřte názvy organizací, projektů a úložišť.
  • Oprávnění byla odepřena: Ujistěte se, že váš účet Dataverse má oprávnění ke správě zdrojového kódu.
  • Řešení se nenašlo: Ověřte, že SolutionUniqueName ve vašem prostředí existuje.
  • Větev neexistuje: Ověřte, že zadaná větev existuje v úložišti.

Podpora a další zdroje informací

Další informace o integraci správy zdrojového kódu s Dataverse najdete v tématech:

  • Last updated on