Łączenie i odłączanie usługi Dataverse z repozytorium Git przy użyciu kodu

Użyj interfejsów API ConnectToGit i DisconnectFromGit, aby programowo zintegrować środowisko Microsoft Dataverse z kontrolą źródła usługi Git. Korzystając z tych interfejsów API, można połączyć poszczególne rozwiązania lub całe środowiska z obsługiwanymi repozytoriami Git i zarządzać tymi połączeniami za pośrednictwem kodu.

Wymagania wstępne

Przed użyciem tych interfejsów API upewnij się, że masz następujące elementy:

• Dostęp do środowiska usługi Microsoft Dataverse
• Uprawnienia administratora systemu
• Dostęp do odczytu i zapisu w repozytorium Git

ConnectToGit API

Tworzy połączenie między rozwiązaniem Dataverse lub środowiskiem a repozytorium Git. Za pomocą tego połączenia można zarządzać kontrolą źródła składników usługi Dataverse.

Parameters

Interfejs ConnectToGit API akceptuje następujące parametry:

Parametr ConnectionType

Parametr ConnectionType określa, czy połączyć się z całym środowiskiem Usługi Dataverse, czy konkretnym rozwiązaniem.

Parametr GitProvider

Użyj parametru GitProvider , aby określić typ używanego dostawcy Usługi Git— Azure DevOps lub GitHub.

Interfejs API DisconnectFromGit

Usuwa połączenie Git z rozwiązania lub środowiska usługi Dataverse i wyłącza integrację kontroli źródła.

Parametr

Interfejs DisconnectFromGit API ma tylko jeden parametr.

Informacje dodatkowe

Poniżej przedstawiono kilka opcji wartości parametrów, które należy określić podczas wywoływania DisconnectFromGitelementu .

• Rozłącz pojedyncze rozwiązanie: podaj SolutionUniqueName , aby rozłączyć określone rozwiązanie.
• Rozłącz wszystkie rozwiązania: nie podaj parametrów, aby odłączyć wszystkie połączenia na poziomie rozwiązania.
• Rozłącz środowisko: nie podaj parametrów, aby odłączyć połączenie na poziomie środowiska.

Przykłady

W poniższych przykładach opisano scenariusze korzystania z interfejsów API ConnectToGit i DisconnectFromGit:

• Łączenie całego środowiska usługi Dataverse z repozytorium usługi Azure DevOps
• Nawiązywanie połączenia z repozytorium GitHub
• Nawiązywanie połączenia z repozytorium GitHub przy użyciu programu PowerShell
• Odłącz całe środowisko Dataverse od kontroli źródła Git
• Łączenie pierwszego rozwiązania z repozytorium Git
• Łączenie dodatkowych rozwiązań z tym samym repozytorium Git po nawiązaniu połączenia z początkowym rozwiązaniem
• Odłączanie określonego rozwiązania od kontroli źródła usługi Git przy zachowaniu połączenia z innymi rozwiązaniami

Łączenie całego środowiska usługi Dataverse z repozytorium usługi Azure DevOps

To połączenie umożliwia kontrolę źródła dla wszystkich konfiguracji i składników na poziomie środowiska.

Nie używaj tych parametrów z tym połączeniem:

• RootFolder
• SolutionUniqueName
• UpstreamBranch

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

HTTP/1.1 204 No Content
OData-Version: 4.0

private const int GitProviderAzureDevOps = 0;
private const int GitProviderGitHub = 1;
private const int ConnectionTypeEnvironment = 1;

static void ConnectDataverseEnvironment(
    IOrganizationService service,
    string gitFolderName,
    string branchName,
    string organizationName,
    string projectName,
    string repositoryName,
    OptionSetValue? gitProvider = null)
{
    // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
    ArgumentException.ThrowIfNullOrWhiteSpace(organizationName);
    ArgumentException.ThrowIfNullOrWhiteSpace(projectName);
    ArgumentException.ThrowIfNullOrWhiteSpace(repositoryName);

    // Default to Azure Dev Ops
    gitProvider ??= new OptionSetValue(GitProviderAzureDevOps);

    ParameterCollection parameters = new()
    {
        { "GitFolder", gitFolderName },
        { "Branch", branchName },
        { "ConnectionType", new OptionSetValue(ConnectionTypeEnvironment) },
        { "GitProvider", gitProvider },
        { "Organization", organizationName },
        { "Project", projectName },
        { "Repository", repositoryName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "ConnectToGit",
        Parameters = parameters
    };

     service.Execute(request);
}

Nawiązywanie połączenia z repozytorium GitHub

Przed użyciem interfejsu API do nawiązania połączenia z GitHub wykonaj kroki instalacji, aby utworzyć aplikację GitHub, zainstaluj ją w docelowym repozytorium, zaimportuj klucz prywatny do Azure Key Vault i utwórz połączenie usługi Power Platform GitHub. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia z GitHub.

Tworzenie rekordu konfiguracji aplikacji GitHub przy użyciu internetowego interfejsu API

Użyj interfejsu API sieci Web Dataverse OData, aby utworzyć rekord githubappconfig. Wyślij żądanie POST z użyciem identyfikatora klienta aplikacji GitHub, identyfikatora URI usługi Key Vault oraz nazwy klucza.

Możesz użyć dowolnego klienta HTTP, takiego jak Insomnia, klient REST dla Visual Studio Code lub curl, aby wykonać te wywołania. Do uwierzytelniania potrzebny jest token okaziciela. Aby uzyskać więcej informacji, zobacz Use the Microsoft Dataverse Web API (Korzystanie z internetowego interfejsu API Microsoft Dataverse).

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

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

Po utworzeniu rekordu konfiguracji aplikacji GitHub przypisz rolę użytkownika kryptograficznego Key Vault do tożsamości zarządzanej usługi Dataverse zgodnie z opisem w temacie Konfigurowanie kontroli dostępu opartej na rolach (RBAC) Key Vault.

Wywołaj interfejs API ConnectToGit

Po utworzeniu rekordu githubappconfig i skonfigurowaniu kontroli dostępu opartej na rolach (RBAC) usługi Key Vault użyj internetowego interfejsu API usługi Dataverse, aby ustanowić połączenie z kontrolą źródła, wywołując akcję 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>)"
}

Jeśli otrzymasz pomyślną odpowiedź, środowisko jest połączone z GitHub.

Nawiązywanie połączenia z repozytorium GitHub przy użyciu programu PowerShell

Poniższy przykład programu PowerShell tworzy rekord konfiguracji aplikacji GitHub, czeka na pojawienie się tożsamości zarządzanej usługi Dataverse w usłudze Microsoft Entra ID, przypisuje do tej tożsamości zarządzanej rolę Key Vault Crypto User i wywołuje akcję ConnectToGit. Jeśli masz już rekord konfiguracji aplikacji GitHub, podaj GitHubAppConfigId, aby pominąć kroki konfiguracji i przypisywania ról w usłudze Key Vault.

Przed uruchomieniem przykładu zainstaluj i zaimportuj moduły programu PowerShell Az.Accounts, Az.KeyVault i Az.Resources. Zaloguj się za pomocą Connect-AzAccount konta, które ma dostęp do środowiska Dataverse i uprawnienia do przypisywania ról Key Vault.

Jeśli obsługa sieci wirtualnej jest włączona dla środowiska Dataverse, podaj wartość GitHubPAT. Połączeń z GitHubem nie można używać z obsługą sieci wirtualnych.

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

Odłącz całe środowisko Dataverse od systemu kontroli wersji Git

Ta akcja powoduje usunięcie połączenia git na poziomie środowiska. Nie używaj parametru SolutionUniqueName dla tej operacji. Usługa Dataverse automatycznie identyfikuje i usuwa połączenie git na poziomie środowiska.

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

HTTP/1.1 204 No Content
OData-Version: 4.0

static void DisconnectDataverseEnvironment(IOrganizationService service) {

   // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);

   OrganizationRequest request = new("DisconnectFromGit");

   service.Execute(request);

}

Łączenie pierwszego rozwiązania z repozytorium Git

To połączenie ustanawia strukturę połączenia repozytorium i folderu dla kontroli źródła na poziomie rozwiązania do pierwszego rozwiązania w środowisku.

Aby określić rozwiązanie, należy uwzględnić wartości tych parametrów:

• RootFolder
• SolutionUniqueName

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

HTTP/1.1 204 No Content
OData-Version: 4.0

private const int ConnectionTypeSolution = 0;

static void ConnectFirstSolution(
    IOrganizationService service,
    string gitFolderName,
    string branchName,
    string organizationName,
    string projectName,
    string repositoryName,
    string rootFolderName,
    string solutionUniqueName,
    OptionSetValue? gitProvider = null)
{
    // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
    ArgumentException.ThrowIfNullOrWhiteSpace(organizationName);
    ArgumentException.ThrowIfNullOrWhiteSpace(projectName);
    ArgumentException.ThrowIfNullOrWhiteSpace(repositoryName);
    ArgumentException.ThrowIfNullOrWhiteSpace(rootFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

    // Default to Azure Dev Ops
    gitProvider ??= new OptionSetValue(GitProviderAzureDevOps);

    ParameterCollection parameters = new()
    {
        { "GitFolder", gitFolderName },
        { "Branch", branchName },
        { "ConnectionType", new OptionSetValue(ConnectionTypeSolution) },
        { "GitProvider", gitProvider },
        { "Organization", organizationName },
        { "Project", projectName },
        { "Repository", repositoryName },
        { "RootFolder", rootFolderName },
        { "SolutionUniqueName", solutionUniqueName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "ConnectToGit",
        Parameters = parameters
    };

    service.Execute(request);
}

Łączenie dodatkowych rozwiązań z tym samym repozytorium Git po nawiązaniu połączenia z początkowym rozwiązaniem

Po nawiązaniu połączenia z pierwszym rozwiązaniem potrzebne są tylko parametry specyficzne dla rozwiązania. Szczegóły połączenia repozytorium są dziedziczone z początkowego połączenia.

Ustaw tylko następujące parametry:

• SolutionUniqueName
• Branch
• GitFolder

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

HTTP/1.1 204 No Content
OData-Version: 4.0

static void ConnectExtraSolution(
   IOrganizationService service,
   string gitFolderName,
   string branchName,
   string solutionUniqueName)
{
   // Validate required parameters
   ArgumentNullException.ThrowIfNull(service);
   ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
   ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
   ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

   ParameterCollection parameters = new()
   {
         { "GitFolder", gitFolderName },
         { "Branch", branchName },
         { "SolutionUniqueName", solutionUniqueName }
   };

   OrganizationRequest request = new()
   {
         RequestName = "ConnectToGit",
         Parameters = parameters
   };

   service.Execute(request);
}

Odłączanie określonego rozwiązania od kontroli źródła usługi Git przy zachowaniu połączenia z innymi rozwiązaniami

Użyj tego podejścia, aby usunąć kontrolę źródła dla jednego rozwiązania bez wpływu na inne.

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

HTTP/1.1 204 No Content
OData-Version: 4.0

static void DisconnectSolution(IOrganizationService service,
    string solutionUniqueName)
{

   // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

    ParameterCollection parameters = new()
    {
        { "SolutionUniqueName", solutionUniqueName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "DisconnectFromGit",
        Parameters = parameters
    };

    service.Execute(request);
}

Obsługa błędów

Ani interfejs API ConnectToGit, ani DisconnectFromGit nie zwraca wartości po pomyślnym zakończeniu. Gdy interfejs API zakończy się niepowodzeniem, zwraca błąd.

Typowe scenariusze błędów obejmują:

• Nieprawidłowe poświadczenia: upewnij się, że masz prawidłowe uwierzytelnianie u dostawcy usługi Git.
• Nie znaleziono repozytorium: Sprawdź nazwy organizacji, projektu i repozytorium.
• Odmowa uprawnień: upewnij się, że konto usługi Dataverse ma uprawnienia do zarządzania kontrolą źródła.
• Nie znaleziono rozwiązania: Sprawdź, SolutionUniqueName czy istnieje w danym środowisku.
• Gałąź nie istnieje: Upewnij się, że określona gałąź istnieje w repozytorium.

Pomoc techniczna i dodatkowe zasoby

Aby uzyskać więcej informacji na temat integracji kontroli źródła z usługą Dataverse, zobacz:

• Omówienie integracji z usługą Git na platformie Power Platform
• Akcja ConnectToGit
• Akcja DisconnectFromGit
• Akcja CommitToGit
• Akcja RefreshChangesFromGit
• Akcja PullChangesFromGit