Підключіть і від'єднайте Dataverse від репозиторію Git за допомогою коду

Використовуйте ConnectToGit API та DisconnectFromGit для програмної інтеграції вашого середовища Microsoft Dataverse з контролем версій Git. Використовуючи ці інтерфейси API, можна підключити окремі рішення або цілі середовища до підтримуваних репозиторіїв Git і керувати цими підключеннями за допомогою коду.

вимоги

Перед використанням цих API переконайтеся, що у вас:

  • Доступ до середовища Microsoft Dataverse
  • Права доступу системного адміністратора
  • Доступ до читання та запису до репозиторію Git

ConnectToGit API

Створює зв'язок між рішенням або середовищем Dataverse та репозиторієм Git. Використовуючи це з'єднання, ви можете керувати контролем версії для компонентів Dataverse.

Параметри

API приймає такі параметри:ConnectToGit

Параметр Тип Обов'язковий Опис
GitFolder Рядок Так Назвіть папку, до якої хочете прив'язати рішення або середовище.
Branch Рядок Так Назвіть філію, до якої хочете підключитися.
ConnectionType Ціле число Ні Вказує, до чого підключатися. Див. параметр ConnectionType.
GitProvider Ціле число Ні Провайдер Git. Див. параметр GitProvider.
Organization Рядок Ні Назвіть організацію, з якою хочете зв'язатися.
Project Рядок Ні Назва проєкту, до якого ви хочете приєднатися.
Repository Рядок Ні Назва репозиторію, до якого ви хочете підключитися.
RootFolder Рядок Ні Ім'я кореневої папки, де всі ваші рішення знаходяться у scope solution.
SolutionUniqueName Рядок Ні Унікальна назва рішення, яке ви хочете підключити до git.
UpstreamBranch Рядок Ні Назва верхньої гілки, до якої ви хочете підключитися. За замовчуванням налаштований на стандартну гілку репозиторію.
GitHubConnectionId Рядок Ні Ідентифікатор підключення для підключення GitHub платформи Power Platform. Обов'язковий час, 1 якщо GitProvider ви не надаєте GitHubPAT. Не можна використовувати, якщо активовано підтримку віртуальної мережі (VNET) для середовища Dataverse.
GitHubPAT Рядок Ні GitHub маркер особистого доступу з доступом до цільового сховища. Обов'язковий час, 1 якщо GitProvider ви не надаєте GitHubConnectionId. Обов'язково, коли ввімкнуто підтримку віртуальної мережі (VNET) для середовища Dataverse.
GitHubAppConfigId Рядок Ні Посилання на запис конфігурації програми 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 і вимикає інтеграцію з контролем версій.

Параметр

DisconnectFromGit API має лише один параметр.

Параметр Тип Обов'язковий Опис
SolutionUniqueName Рядок Ні Унікальна назва рішення, яке ви хочете від'єднати від 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

Дізнайтеся, як викликати дії Web API

Підключення до сховища GitHub

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

Створення запису конфігурації програми GitHub за допомогою веб-інтерфейсу API

Створюйте запис за допомогою веб-інтерфейсу githubappconfig API OData Dataverse. Надішліть запит POST з ідентифікатором клієнта програми GitHub, Key Vault URI та іменем ключа.

Ви можете використовувати будь-який http-клієнт, наприклад Insomnia, 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"
}

Important

Зверніть увагу, що ідентифікатор запису повернувся в заголовку відповіді. Це значення потрібне, щоб ідентифікувати керовану ідентичність, настроїти 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>)"
}

Important

Гілка вже має існувати в сховищі. Спочатку створіть його в GitHub. Значення GitHubAppConfigId має використовувати формат githubappconfigs(<recordId>).

Знімок екрана: текст запиту HTTP для API ConnectToGit із параметрами GitHub.

Якщо ви отримали успішну відповідь, середовище підключено до GitHub.

Підключення до сховища GitHub за допомогою PowerShell

У наведеному нижче прикладі PowerShell створюється запис конфігурації програми GitHub, очікується, що керована ідентичність Dataverse з'явиться в Microsoft Entra ID, призначає керованій ідентичності роль Key Vault Crypto User і викликає ConnectToGit дію. Якщо у вас уже є запис конфігурації програми GitHub, задайтеGitHubAppConfigId, щоб пропустити настроювання та Key Vault етапи призначення ролей.

Перш ніж запускати приклад, Az.Accountsінсталюйте та імпортуйте модулі , Az.KeyVaultі Az.Resources PowerShell. Connect-AzAccount Увійдіть, використовуючи обліковий запис, який має доступ до середовища Dataverse, і дозвіл на призначення Key Vault ролей.

Якщо для середовища 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-з'єднання на рівні середовища.

Цей приклад показує, як використати дію 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

Дізнайтеся, як викликати дії Web 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

Дізнайтеся, як викликати дії Web API

Підключіть додаткові рішення до того ж репозиторію Git після підключення початкового рішення

Після підключення першого рішення вам потрібні лише параметри, специфічні для цього рішення. Ви успадковуєте деталі підключення репозиторію від початкового з'єднання.

Встановіть лише такі параметри:

  • SolutionUniqueName
  • Branch
  • GitFolder

Important

Спочатку потрібно підключити перше рішення, перш ніж це спрацює. Див. Підключити перше рішення до репозиторію 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

Дізнайтеся, як викликати дії Web 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

Дізнайтеся, як викликати дії Web API

Обробка помилок

Ні API, ConnectToGitDisconnectFromGit ні API не повертає значення після успішного завершення. Коли API виходить з ладу, він повертає помилку.

Поширені сценарії помилок включають:

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

Підтримка та додаткові ресурси

Для отримання додаткової інформації про інтеграцію контролю версії з Dataverse дивіться:

  • Востаннє оновлено: