Подключение и отключение Dataverse из репозитория Git с помощью кода

Используйте API ConnectToGit и DisconnectFromGit для программной интеграции среды Microsoft Dataverse с системой управления источником на Git. С помощью этих API можно подключать отдельные решения или целые среды к поддерживаемым репозиториям Git и управлять этими подключениями с помощью кода.

Предпосылки

Прежде чем использовать эти API, убедитесь, что у вас есть:

  • Доступ к среде Microsoft Dataverse
  • Разрешения системного администратора
  • Доступ на чтение и запись к репозиторию Git

ConnectToGit API

Создает соединение между решением dataverse или средой и репозиторием Git. С помощью этого подключения вы можете управлять системой управления версиями для своих компонентов Dataverse.

Parameters

ConnectToGit API принимает следующие параметры:

Параметр Type Обязательно Description
GitFolder String Yes Имя папки, к которой нужно привязать решение или среду.
Branch String Yes Имя ветви, к которой требуется подключиться.
ConnectionType Целое No Указывает, к чему нужно подключиться. См. параметр ConnectionType.
GitProvider Целое No Поставщик Git. См. параметр GitProvider.
Organization String No Имя организации, к которой требуется подключиться.
Project String No Имя проекта, к которому требуется подключиться.
Repository String No Имя репозитория, к которому требуется подключиться.
RootFolder String No Имя корневой папки, в которой находятся все решения в области решения.
SolutionUniqueName String No Уникальное имя решения, которое вы хотите подключить к Git.
UpstreamBranch String No Имя вышестоящей ветви, к которой вы хотите подключиться. По умолчанию используется ветвь репозитория по умолчанию.
GitHubConnectionId String No Идентификатор подключения для подключения GitHub к Power Platform. Требуется, если GitProvider имеет значение GitHubPAT, если только вы не предоставите 1. Невозможно использовать, если поддержка виртуальной сети включена для среды Dataverse.
GitHubPAT String No Личный токен доступа GitHub с доступом к целевому репозиторию. Требуется, если GitProvider — 1, если только вы не предоставите GitHubConnectionId. Требуется, если поддержка виртуальной сети включена для среды Dataverse.
GitHubAppConfigId String No Ссылка на запись конфигурации приложения GitHub. Обязательный, если GitProvider имеет значение 1. Используйте формат githubappconfigs(<recordId>).

Параметр ConnectionType

Параметр ConnectionType определяет, следует ли подключаться ко всей среде Dataverse или определенному решению.

Ценность Этикетка Description
0 Решение Подключает определенное решение Dataverse к Git.
1 Окружение Подключает всю среду Dataverse к Git.

Параметр GitProvider

GitProvider Используйте параметр, чтобы указать тип используемого поставщика Git, Azure DevOps или GitHub.

Ценность Этикетка Description
0 Azure DevOps Используется для репозиториев, размещенных в Azure DevOps
1 GitHub Используется для репозиториев, размещенных на GitHub

API-интерфейс DisconnectFromGit

Удаляет подключение к Git из решения или среды Dataverse и отключает интеграцию с системой управления версиями.

Параметр

API DisconnectFromGit имеет только один параметр.

Параметр Type Обязательно Description
SolutionUniqueName String No Уникальное имя решения, которое требуется отключить от Git. Опустите его, чтобы отключить все решения или среду.

Дополнительные сведения

Представлены несколько вариантов значений параметров, которые необходимо указать при вызове DisconnectFromGit.

  • Отключить одно решение. Укажите SolutionUniqueName для отключения конкретного решения.
  • Отключить все решения: не укажите параметры для отключения всех подключений на уровне решения.
  • Отключить среду: Не указывайте параметры для отключения соединения на уровне среды.

Примеры

В следующих примерах приведены сценарии использования API ConnectToGit и DisconnectFromGit:

Подключение всей среды Dataverse к репозиторию Azure DevOps

Это подключение обеспечивает управление версиями для всех конфигураций и компонентов уровня среды.

Не используйте эти параметры с этим подключением:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

В этом примере показано, как использовать действие ConnectToGit для подключения всей среды Dataverse к репозиторию Azure DevOps.

запрос

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

Узнайте, как вызывать действия веб-API

Подключение к репозиторию GitHub

Прежде чем использовать API для подключения к GitHub, выполните действия по настройке, чтобы создать приложение GitHub, установить его в целевой репозиторий, импортировать его закрытый ключ в Azure Key Vault и создать подключение Power Platform GitHub. Дополнительные сведения см. в разделе "Подключение к GitHub".

Создание записи конфигурации приложения GitHub с помощью веб-API

Используйте веб-API Dataverse OData для создания githubappconfig записи. Отправьте запрос POST с идентификатором клиента приложения GitHub, Key Vault URI и именем ключа.

Для выполнения этих вызовов можно использовать любой HTTP-клиент, например "Бессонница", Visual Studio Code REST Client или curl. Для проверки подлинности требуется маркер носителя. Дополнительные сведения см. в разделе "Использование веб-API Microsoft Dataverse".

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

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

Это важно

Запишите идентификатор записи, возвращенный в заголовке ответа. Это значение необходимо, чтобы определить управляемую идентичность, настроить RBAC и вызвать ConnectToGit. Идентификатор записи использует такой формат, как 13d565bb-4c22-f111-a546-7ced8d6e3e85.

После создания записи конфигурации приложения GitHub назначьте управляемому удостоверению Dataverse роль Пользователь шифрования Key Vault, как описано в разделе Настройка управления доступом на основе ролей (RBAC) для Key Vault.

Вызов API ConnectToGit

После создания записи githubappconfig и настройки Key Vault RBAC используйте веб-API Dataverse, чтобы установить подключение к системе контроля версий, вызвав действие 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. Значение GitHubAppConfigId должно использовать формат githubappconfigs(<recordId>).

Снимок экрана: текст HTTP-запроса для API ConnectToGit с параметрами GitHub.

Если вы получите успешный ответ, среда подключена к GitHub.

Подключение к репозиторию GitHub с помощью PowerShell

В следующем примере PowerShell создается запись конфигурации приложения GitHub, выполняется ожидание появления управляемого удостоверения Dataverse в Microsoft Entra ID, управляемому удостоверению назначается роль Пользователь шифрования Key Vault, а затем вызывается действие ConnectToGit. Если у вас уже есть запись о конфигурации приложения GitHub, укажите GitHubAppConfigId, чтобы пропустить шаги настройки и назначения ролей для Key Vault.

Установите и импортируйте Az.AccountsAz.KeyVaultAz.Resources модули PowerShell перед запуском примера. Выполните вход с помощью Connect-AzAccount, используя учетную запись, которая имеет доступ к среде Dataverse и разрешение для назначения ролей Key Vault.

Если поддержка виртуальной сети включена для среды Dataverse, укажите 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.

В этом примере показано, как использовать действие DisconnectFromGit для отключения всей среды 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

Узнайте, как вызывать действия веб-API

Подключение первого решения к репозиторию Git

Это подключение устанавливает ссылку на репозиторий и структуру папок для управления версиями в соответствии с первым решением в среде.

Чтобы указать решение, необходимо включить значения для этих параметров:

  • RootFolder
  • SolutionUniqueName

В этом примере показано, как использовать действие ConnectToGit для подключения первого решения к репозиторию Git.

запрос

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

Узнайте, как вызывать действия веб-API

Подключение дополнительных решений к одному репозиторию Git после подключения исходного решения

После подключения первого решения вам потребуются только параметры, относящиеся к решению. Сведения о подключении к репозиторию наследуются от изначального подключения.

Задайте только следующие параметры:

  • SolutionUniqueName
  • Branch
  • GitFolder

Это важно

Прежде чем это будет работать, необходимо сначала подключить первое решение. См. статью "Подключение первого решения к репозиторию Git".

В этом примере показано, как использовать действие ConnectToGit для подключения последующих решений к репозиторию Git.

запрос

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

Узнайте, как вызывать действия веб-API

Отключение конкретного решения от системы управления версиями Git при сохранении подключения к другим решениям

Используйте этот подход для удаления системы контроля версий для одного проекта, не влияя на другие.

В этом примере показано, как использовать действие DisconnectFromGit для удаления системы контроля версий для одного решения без влияния на другие.

запрос

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

Узнайте, как вызывать действия веб-API

Обработка ошибок

Ни ConnectToGit, ни DisconnectFromGit API не возвращают значение после успешного завершения. При сбое API возвращает ошибку.

Распространенные сценарии ошибок включают:

  • Недопустимые учетные данные: Убедитесь, что у вас есть действующие учетные данные для аутентификации у поставщика Git.
  • Репозиторий не найден: проверьте имена организации, проекта и репозитория.
  • Доступ запрещен: Убедитесь, что у вашей учетной записи Dataverse есть разрешения на управление системой контроля версий.
  • Решение не найдено: проверьте SolutionUniqueName наличие в вашей среде.
  • Ветвь не существует: убедитесь, что указанная ветвь существует в репозитории.

Поддержка и дополнительные ресурсы

Дополнительные сведения об интеграции системы управления исходным кодом с Dataverse см. в разделе ниже.

  • Last updated on