コードを使用して Dataverse を Git リポジトリに接続して切断する

ConnectToGit API とDisconnectFromGit API を使用して、Microsoft Dataverse 環境を Git ソース管理とプログラムで統合します。 これらの API を使用すると、個々のソリューションまたは環境全体をサポートされている Git リポジトリに接続し、コードを使用してそれらの接続を管理できます。

前提条件

これらの API を使用する前に、次のことを確認してください。

• Microsoft Dataverse 環境へのアクセス
• システム管理者のアクセス許可
• Git リポジトリへの読み取りと書き込みアクセス

ConnectToGit API

Dataverse ソリューションまたは環境と Git リポジトリの間の接続を作成します。 この接続を使用すると、Dataverse コンポーネントのソース管理を管理できます。

Parameters

ConnectToGit API は、次のパラメーターを受け入れます。

ConnectionType パラメーター

ConnectionType パラメーターは、Dataverse 環境全体に接続するか、特定のソリューションに接続するかを制御します。

GitProvider パラメーター

GitProvider パラメーターを使用して、使用している Git プロバイダーの種類 (Azure DevOps または GitHub) を指定します。

DisconnectFromGit API

Dataverse ソリューションまたは環境から Git 接続を削除し、ソース管理の統合を無効にします。

パラメーター

DisconnectFromGit API にはパラメーターが 1 つだけ含まれています。

追加情報

DisconnectFromGitを呼び出すときに指定するパラメーター値のオプションをいくつか次に示します。

• 1 つのソリューションを切断する: 特定のソリューションを切断するための SolutionUniqueName を提供します。
• すべてのソリューションを切断する: すべてのソリューション レベルの接続を切断するためのパラメーターを指定しません。
• 環境の切断: 環境レベルの接続を切断するためのパラメーターを指定しません。

例示

次の例では、 ConnectToGit API と DisconnectFromGit API を使用するシナリオについて説明します。

• Dataverse 環境全体を Azure DevOps リポジトリに接続する
• GitHub リポジトリに接続する
• PowerShell を使用してGitHub リポジトリに接続する
• Dataverse 環境全体を Git ソース管理から切断する
• 最初のソリューションを Git リポジトリに接続する
• 初期ソリューションを接続した後、追加のソリューションを同じ Git リポジトリに接続する
• 他のソリューションを接続したまま、特定のソリューションを Git ソース管理から切断する

Dataverse 環境全体を Azure DevOps リポジトリに接続する

この接続により、すべての環境レベルの構成とコンポーネントのソース管理が可能になります。

この接続では、次のパラメーターを使用しないでください。

• 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);
}

GitHub リポジトリに接続する

API を使用してGitHubに接続する前に、GitHub アプリの作成、ターゲット リポジトリへのインストール、Azure Key Vaultへの秘密キーのインポート、Power Platform GitHub接続の作成を行うセットアップ手順を完了します。 詳細については、「GitHubへの接続」を参照してください。

Web API を使用してGitHubアプリ構成レコードを作成する

Dataverse OData Web API を使用して、 githubappconfig レコードを作成します。 GitHub アプリ クライアント ID、Key Vault URI、キー名を使用して POST 要求を送信します。

これらの呼び出しには、不眠症、Visual Studio Code REST クライアント、curl などの任意の HTTP クライアントを使用できます。 認証にはベアラー トークンが必要です。 詳細については、「Microsoft Dataverse Web API の使用」を参照してください。

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

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

GitHub App の構成レコードを作成した後、Key Vault のロールベースのアクセス制御 (RBAC) を構成する で説明されているように、Dataverse マネージド ID に Key Vault Crypto User ロールを割り当てます。

ConnectToGit API を呼び出す

githubappconfig レコードを作成し、KEY VAULT RBAC を構成したら、Dataverse Web API を使用して、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>)"
}

正常な応答を受け取った場合、環境はGitHubに接続されます。

PowerShell を使用してGitHub リポジトリに接続する

次の PowerShell の例では、GitHubアプリ構成レコードを作成し、Dataverse マネージド ID がMicrosoft Entra IDに表示されるのを待ち、Key Vault Crypto User ロールをマネージド ID に割り当てて、ConnectToGit アクションを呼び出します。 GitHub App の構成レコードが既にある場合は、構成と Key Vault のロール割り当ての手順をスキップするために、GitHubAppConfigId を指定します。

例を実行する前に、powerShell モジュールの Az.Accounts、 Az.KeyVault、および Az.Resources をインストールしてインポートします。 Dataverse 環境にアクセスできるアカウントと、Key Vaultロールを割り当てるアクセス許可を持つアカウントを使用して、Connect-AzAccountでサインインします。

Dataverse 環境で仮想ネットワーク (VNET) のサポートが有効になっている場合は、 GitHubPATを指定します。 GitHub接続は、仮想ネットワークのサポートでは使用できません。

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

Dataverse 環境全体を Git ソース管理から切断する

このアクションにより、環境レベルの Git 接続が削除されます。 この操作には SolutionUniqueName パラメーターを使用しないでください。 Dataverse は、環境レベルの Git 接続を自動的に識別して削除します。

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);

}

最初のソリューションを Git リポジトリに接続する

この接続により、ソリューション レベルのソース管理のリポジトリ リンクとフォルダー構造が、環境内の最初のソリューションに確立されます。

ソリューションを指定するには、これらのパラメーターの値を含める必要があります。

• 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);
}

初期ソリューションを接続した後、追加のソリューションを同じ Git リポジトリに接続する

最初のソリューションを接続した後は、ソリューション固有のパラメーターのみが必要になります。 最初の接続からリポジトリ接続の詳細を継承します。

次のパラメーターのみを設定します。

• 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);
}

他のソリューションを接続したまま、特定のソリューションを Git ソース管理から切断する

このアプローチを使用して、他のソリューションに影響を与えずに 1 つのソリューションのソース管理を削除します。

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

エラー処理

正常に完了したときに、 ConnectToGit と DisconnectFromGit API のどちらも値を返しません。 API が失敗すると、エラーが返されます。

一般的なエラーのシナリオは次のとおりです。

• 無効な資格情報: Git プロバイダーに対する有効な認証があることを確認します。
• リポジトリが見つかりません: 組織、プロジェクト、リポジトリの名前を確認します。
• アクセス許可が拒否されました: Dataverse アカウントにソース管理の管理アクセス許可があることを確認します。
• 解決策が見つかりません: SolutionUniqueName が環境内に存在するかどうかを確認します。
• ブランチが存在しない: 指定したブランチがリポジトリに存在するかどうかを確認します。

サポートとその他のリソース

Dataverse とのソース管理の統合の詳細については、以下を参照してください。

• Power Platform での Git 統合の概要
• ConnectToGit アクション
• DisconnectFromGit アクション
• CommitToGit アクション
• RefreshChangesFromGit アクション
• PullChangesFromGit アクション