Menyambungkan dan memutuskan Sambungan Dataverse dari repositori Git dengan menggunakan kode

ConnectToGit Gunakan API dan DisconnectFromGit untuk mengintegrasikan lingkungan Microsoft Dataverse Anda secara terprogram dengan kontrol sumber Git. Dengan menggunakan API ini, Anda dapat menghubungkan solusi individual atau seluruh lingkungan ke repositori Git yang didukung dan mengelola koneksi tersebut melalui kode.

Prasyarat

Sebelum menggunakan API ini, pastikan Anda memiliki:

  • Akses ke lingkungan Microsoft Dataverse
  • Izin sistem administrator
  • Membaca dan menulis akses ke repositori Git

ConnectToGit API

Membuat koneksi antara solusi atau lingkungan Dataverse dan repositori Git. Dengan menggunakan koneksi ini, Anda dapat mengelola kontrol sumber untuk komponen Dataverse Anda.

Parameters

ConnectToGit API menerima parameter berikut:

Parameter Type Diperlukan Description
GitFolder String Yes Nama folder yang ingin Anda hubungkan dengan solusi atau lingkungan Anda.
Branch String Yes Nama cabang yang ingin Anda sambungkan.
ConnectionType Integer No Menentukan apa yang akan disambungkan. Lihat parameter ConnectionType.
GitProvider Integer No Penyedia Git. Lihat Parameter GitProvider.
Organization String No Nama organisasi yang ingin Anda sambungkan.
Project String No Nama proyek yang ingin Anda sambungkan.
Repository String No Nama repositori yang ingin Anda sambungkan.
RootFolder String No Nama folder utama tempat semua solusi Anda termasuk dalam cakupan solusi.
SolutionUniqueName String No Nama unik solusi yang ingin Anda sambungkan ke git.
UpstreamBranch String No Nama cabang hulu yang ingin Anda sambungkan. Default untuk cabang default repositori.
GitHubConnectionId String No ID koneksi untuk koneksi GitHub Power Platform. Diperlukan jika GitProvider adalah 1, kecuali jika Anda menyediakan GitHubPAT. Tidak dapat digunakan saat dukungan jaringan virtual (VNET) diaktifkan untuk lingkungan Dataverse.
GitHubPAT String No token akses pribadi GitHub yang memiliki akses ke repositori target. Diperlukan saat GitProvider adalah 1, kecuali jika Anda menyediakan GitHubConnectionId. Diperlukan saat dukungan jaringan virtual (VNET) diaktifkan untuk lingkungan Dataverse.
GitHubAppConfigId String No Referensi ke rekaman konfigurasi aplikasi GitHub. Diperlukan saat GitProvider adalah 1. Gunakan format githubappconfigs(<recordId>).

Parameter ConnectionType

Parameter ConnectionType mengontrol apakah akan terhubung ke seluruh lingkungan Dataverse atau solusi tertentu.

Value Label Description
0 Solusi Menyambungkan solusi Dataverse tertentu ke Git.
1 Environment Menyambungkan seluruh lingkungan Dataverse ke Git.

Parameter GitProvider

GitProvider Gunakan parameter untuk menentukan jenis penyedia Git yang Anda gunakan, baik Azure DevOps atau GitHub.

Value Label Description
0 Azure DevOps Gunakan untuk repositori yang dihosting di Azure DevOps
1 GitHub Gunakan untuk repositori yang dihosting di GitHub

API DisconnectFromGit

Menghapus koneksi Git dari solusi atau lingkungan Dataverse, dan menonaktifkan integrasi kontrol sumber.

Parameter

DisconnectFromGit API hanya memiliki satu parameter.

Parameter Type Diperlukan Description
SolutionUniqueName String No Nama unik solusi yang ingin Anda putuskan sambungannya dari Git. Abaikan untuk memutuskan koneksi semua perangkat atau sistem.

Informasi tambahan

Berikut adalah beberapa opsi nilai parameter untuk ditentukan saat memanggil DisconnectFromGit.

  • Putuskan solusi tunggal: Siapkan SolutionUniqueName untuk memutuskan solusi tertentu.
  • Memutuskan semua solusi: Tidak menyediakan parameter untuk memutuskan semua koneksi tingkat solusi.
  • Putuskan sambungan lingkungan: Tanpa parameter untuk memutuskan koneksi di tingkat lingkungan.

Contoh

Contoh berikut menjelaskan skenario untuk menggunakan ConnectToGit API dan DisconnectFromGit :

Menyambungkan seluruh lingkungan Dataverse Anda ke repositori Azure DevOps

Koneksi ini memungkinkan kontrol sumber untuk semua konfigurasi dan komponen tingkat lingkungan.

Jangan gunakan parameter ini dengan koneksi ini:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Contoh ini menunjukkan cara menggunakan tindakan ConnectToGit untuk menghubungkan seluruh lingkungan Dataverse Anda ke repositori Azure DevOps.

Permintaan

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

Jawaban

HTTP/1.1 204 No Content
OData-Version: 4.0

Pelajari cara memanggil tindakan API Web

Menyambungkan ke repositori GitHub

Sebelum Anda menggunakan API untuk terhubung ke GitHub, selesaikan langkah-langkah penyiapan untuk membuat Aplikasi GitHub, instal di repositori target, impor kunci privatnya ke Azure Key Vault, dan buat koneksi GitHub Power Platform. Untuk informasi selengkapnya, lihat Menyambungkan ke GitHub.

Membuat rekaman konfigurasi aplikasi GitHub dengan menggunakan API Web

Gunakan Dataverse OData Web API untuk membuat githubappconfig rekaman. Kirim permintaan POST dengan ID klien Aplikasi GitHub, URI Key Vault, dan nama kunci.

Anda dapat menggunakan klien HTTP apa pun, seperti Insomnia, Visual Studio Code REST Client, atau curl, untuk melakukan panggilan ini. Anda memerlukan token pembawa untuk autentikasi. Untuk informasi selengkapnya, lihat Menggunakan API Web Microsoft Dataverse.

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

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

Important

Perhatikan ID rekaman yang dikembalikan di header respons. Anda memerlukan nilai ini untuk mengidentifikasi identitas terkelola, mengonfigurasi RBAC, dan memanggil ConnectToGit. ID rekaman menggunakan format seperti 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Setelah membuat rekaman konfigurasi Aplikasi GitHub, tetapkan peran Pengguna Kripto Key Vault ke identitas terkelola Dataverse seperti yang dijelaskan dalam Mengonfigurasi kontrol akses berbasis peran (RBAC) Key Vault.

Memanggil ConnectToGit API

Setelah Anda membuat catatan githubappconfig dan mengonfigurasi Key Vault RBAC, gunakan API Web Dataverse untuk membuat koneksi kontrol sumber dengan memanggil tindakan 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

Cabang harus sudah ada di repositori. Buat di GitHub terlebih dahulu jika diperlukan. Nilai GitHubAppConfigId harus menggunakan format githubappconfigs(<recordId>).

Cuplikan layar isi permintaan HTTP untuk CONNECTToGit API dengan parameter GitHub.

Jika Anda menerima respons yang berhasil, lingkungan terhubung ke GitHub.

Menyambungkan ke repositori GitHub dengan menggunakan PowerShell

Contoh PowerShell berikut membuat rekaman konfigurasi Aplikasi GitHub, menunggu identitas terkelola Dataverse muncul di Microsoft Entra ID, menetapkan peran Pengguna Kripto Key Vault ke identitas terkelola, dan memanggil ConnectToGit tindakan. Jika Anda sudah memiliki catatan konfigurasi aplikasi GitHub, berikan GitHubAppConfigId untuk melewati konfigurasi dan langkah-langkah penetapan peran Key Vault.

Instal dan impor modul PowerShell Az.Accounts, Az.KeyVault, dan Az.Resources sebelum Anda menjalankan contoh. Masuk dengan Connect-AzAccount menggunakan akun yang memiliki akses ke lingkungan Dataverse dan izin untuk menetapkan peran Key Vault.

Jika dukungan jaringan virtual (VNET) diaktifkan untuk lingkungan Dataverse, berikan GitHubPAT. Koneksi GitHub tidak dapat digunakan dengan dukungan jaringan virtual.

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

Memutuskan seluruh lingkungan Dataverse Anda dari kontrol sumber Git

Tindakan ini menghapus koneksi Git tingkat lingkungan. Jangan gunakan SolutionUniqueName parameter untuk operasi ini. Dataverse secara otomatis mengidentifikasi dan menghapus koneksi Git tingkat lingkungan.

Contoh ini menunjukkan cara menggunakan tindakan DisconnectFromGit untuk memutuskan sambungan seluruh lingkungan Dataverse Anda dari kontrol sumber Git.

Permintaan

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

Jawaban

HTTP/1.1 204 No Content
OData-Version: 4.0

Pelajari cara memanggil tindakan API Web

Menyambungkan solusi pertama ke repositori Git

Koneksi ini menetapkan tautan repositori dan struktur folder untuk kontrol sumber tingkat solusi ke solusi pertama di lingkungan.

Anda perlu menyertakan nilai untuk parameter ini untuk menentukan solusi:

  • RootFolder
  • SolutionUniqueName

Contoh ini menunjukkan cara menggunakan tindakan ConnectToGit untuk menyambungkan solusi pertama ke repositori Git.

Permintaan

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

Jawaban

HTTP/1.1 204 No Content
OData-Version: 4.0

Pelajari cara memanggil tindakan API Web

Hubungkan solusi tambahan ke repositori Git yang sama setelah Anda menyambungkan solusi awal

Setelah menyambungkan solusi pertama, Anda hanya memerlukan parameter khusus solusi. Anda mewarisi detail koneksi repositori dari koneksi awal.

Atur hanya parameter ini:

  • SolutionUniqueName
  • Branch
  • GitFolder

Important

Anda harus terlebih dahulu menyambungkan solusi pertama sebelum ini berfungsi. Lihat Menyambungkan solusi pertama ke repositori Git.

Contoh ini menunjukkan cara menggunakan tindakan ConnectToGit untuk menyambungkan solusi berikutnya ke repositori Git.

Permintaan

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

Jawaban

HTTP/1.1 204 No Content
OData-Version: 4.0

Pelajari cara memanggil tindakan API Web

Putuskan sambungan solusi tertentu dari kontrol sumber Git sambil menjaga solusi lain tetap terhubung

Gunakan pendekatan ini untuk menghapus kontrol sumber untuk satu solusi tanpa memengaruhi yang lain.

Contoh ini menunjukkan cara menggunakan tindakan DisconnectFromGit untuk menghapus kontrol sumber untuk satu solusi tanpa memengaruhi yang lain.

Permintaan

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

Jawaban

HTTP/1.1 204 No Content
OData-Version: 4.0

Pelajari cara memanggil tindakan API Web

Penanganan kesalahan

ConnectToGit API maupun DisconnectFromGit API tidak mengembalikan nilai saat keduanya berhasil diselesaikan. Saat API gagal, API akan mengembalikan kesalahan.

Skenario kesalahan umum meliputi:

  • Kredensial tidak valid: Pastikan Anda memiliki autentikasi yang valid ke penyedia Git.
  • Repositori tidak ditemukan: Verifikasi nama organisasi, proyek, dan repositori.
  • Izin ditolak: Pastikan akun Dataverse Anda memiliki izin manajemen kontrol sumber.
  • Solusi tidak ditemukan: Verifikasi ada SolutionUniqueName di lingkungan Anda.
  • Cabang tidak ada: Konfirmasi cabang yang ditentukan ada di repositori.

Dukungan dan sumber daya tambahan

Untuk informasi selengkapnya tentang integrasi kontrol sumber dengan Dataverse, lihat:

  • Last updated on