Свържете и прекъснете Dataverse от Git хранилището чрез код

Използвай ConnectToGit API-тата и DisconnectFromGit за програмна интеграция на Microsoft Dataverse средата с Git source control. Като използвате тези API, можете да свържете отделни решения или цели среди към поддържани Git хранилища и да управлявате тези връзки чрез код.

Предварителни изисквания

Преди да използвате тези API-та, уверете се, че имате:

  • Достъп до среда на Microsoft Dataverse
  • Разрешения за системен администратор
  • Достъп до четене и запис в Git репозиториум

ConnectToGit API

Създава връзка между решение или среда в Dataverse и хранилище в Git. Чрез тази връзка можете да управлявате контрола на исходния код за вашите компоненти в Dataverse.

Параметри

API приема следните параметри:ConnectToGit

параметър Тип Задължителни Описание
GitFolder String Да Името на папката, към която искате да свържете решението или средата.
Branch String Да Името на клона, към който искате да се свържете.
ConnectionType Цяло число Не Уточнява към какво да се свърже. Вижте параметъра ConnectionType.
GitProvider Цяло число Не Git доставчикът. Вижте параметъра GitProvider.
Organization String Не Името на организацията, към която искате да се свържете.
Project String Не Име на проекта, към който искате да се свържете.
Repository String Не Името на хранилището, към което искате да се свържете.
RootFolder String Не Името на кореновата папка, в която се намират всички ваши решения в обхвата на решението.
SolutionUniqueName String Не Уникалното име на решението, което искате да свържете към git.
UpstreamBranch String Не Името на горния клон, към който искате да се свържете. По подразбиране клонът на хранилището по подразбиране.
GitHubConnectionId String Не ИД на връзка за връзката на платформата Power GitHub. Задължително кога GitProvider е 1 , освен ако не предоставите GitHubPAT. Не може да се използва, когато поддръжката на виртуална мрежа (VNET) е разрешена за средата на Dataverse.
GitHubPAT String Не GitHub маркер за личен достъп с достъп до целевото хранилище. Задължително кога GitProvider е 1 , освен ако не предоставите GitHubConnectionId. Задължително, когато поддръжката на виртуална мрежа (VNET) е разрешена за средата Dataverse.
GitHubAppConfigId String Не Препратка към записа за конфигурация на приложението на GitHub. Задължително е, когато GitProvider е 1. Използвайте формата githubappconfigs(<recordId>).

Параметър ConnectionType

Параметърът ConnectionType контролира дали да се свърже с цялата среда на Dataverse или към конкретно решение.

Стойност Етикет Описание
0 Решение Свързва конкретно решение на Dataverse с Git.
1 Среда Свързва цялата среда на Dataverse към Git.

GitProvider параметър

Използвайте параметъра GitProvider , за да посочите типа Git доставчик, който използвате, било то Azure DevOps или GitHub.

Стойност Етикет Описание
0 Azure DevOps Използване за хранилища, хоствани на Azure DevOps
1 GitHub Използване за хранилища, хоствани в GitHub

DisconnectFromGit API

Премахва Git връзката от Dataverse решение или среда и деактивира интеграцията на source control.

параметър

DisconnectFromGit API има само един параметър.

параметър Тип Задължителни Описание
SolutionUniqueName String Не Уникалното име на решението, което искате да отделите от Git. Пропуснете да изключвате всички решения или средата.

Допълнителна информация

Ето няколко опции за стойност на параметъра, които да зададете при извикване DisconnectFromGitна .

  • Изключване на единично решение: Осигурете SolutionUniqueName разкачаване на конкретно решение.
  • Изключи всички решения: Не предоставяй параметри за прекъсване на всички връзки на ниво решение.
  • Среда за прекъсване: Не се предоставят параметри за прекъсване на връзката на ниво среда.

Примери

Следващите примери описват сценарии за използване на ConnectToGit API и DisconnectFromGit API:

Свържете цялата си 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 и да създадете GitHub връзка на платформата Power. За повече информация вижте Свързване с GitHub.

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

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

Можете да използвате всеки HTTP клиент, като например безсъние, Visual Studio Code REST клиент или извивка, за да извършвате тези обаждания. За удостоверяване се нуждаете от маркер на носителя. За повече информация вижте Използване на уеб 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 приложение, задайте ролята на потребител на Key Vault Crypto към управляваната от Dataverse самоличност, както е описано в Конфигуриране Key Vault управление на достъпа, базирано на роли (RBAC).

Повикване на 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 Crypto за управляваната самоличност и извиква ConnectToGit действието. Ако вече имате запис за конфигурация на GitHub приложение, предоставете GitHubAppConfigId пропускане на конфигурацията и Key Vault стъпките за присвояване на роли.

Инсталирайте и импортирайте модулите Az.Accounts, Az.KeyVaultи Az.Resources PowerShell, преди да изпълните примера. Влезте с Connect-AzAccount акаунт, който има достъп до средата на Dataverse и разрешение за присвояване на Key Vault роли.

Ако поддръжката на виртуална мрежа (VNET) е разрешена за средата 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 source control

Това действие премахва връзката на Git на ниво среда. Не използвайте параметъра SolutionUniqueName за тази операция. Dataverse автоматично идентифицира и премахва Git връзката на ниво среда.

Този пример показва как да използвате действието DisconnectFromGit , за да изключите цялата си Dataverse среда от Git source control.

Заявка

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 source control, като запазиш другите решения свързани

Използвайте този подход, за да премахнете контрола на версиите за едно решение, без да засегнете други.

Този пример показва как да се използва действието 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

Обработка на грешки

Нито API-то ConnectToGitDisconnectFromGit връща стойност при успешно завършване. Когато API се провали, той връща грешка.

Чести сценарии на грешки включват:

  • Невалидни идентификационни данни: Уверете се, че имате валидна автентикация към Git доставчика.
  • Не е намерено хранилище: Проверете имената на организацията, проекта и хранилището.
  • Отказано е разрешение: Уверете се, че вашият акаунт в Dataverse има права за управление на source control.
  • Решение не е намерено: Проверете дали SolutionUniqueName съществува във вашата среда.
  • Branch не съществува: Потвърдете, че посоченият клон съществува в хранилището.

Подкрепа и допълнителни ресурси

За повече информация относно интеграцията на контрола на версиите с Dataverse, вижте:

  • Last updated on