Sambungkan dan putuskan sambungan Dataverse daripada repositori Git dengan menggunakan kod

Gunakan ConnectToGit API dan DisconnectFromGit untuk menyepadukan persekitaran Microsoft Dataverse anda secara terprogram dengan kawalan sumber Git. Dengan menggunakan API ini, anda boleh menyambungkan penyelesaian individu atau keseluruhan persekitaran ke repositori Git yang disokong dan mengurus sambungan tersebut melalui kod.

Prasyarat

Sebelum menggunakan API ini, pastikan anda mempunyai:

  • Akses kepada persekitaran Microsoft Dataverse
  • Kebenaran pentadbir sistem
  • Baca dan tulis akses kepada repositori Git

ConnectToGit API

Mencipta sambungan antara penyelesaian atau persekitaran Dataverse dan repositori Git. Dengan menggunakan sambungan ini, anda boleh mengurus kawalan sumber untuk komponen Dataverse anda.

Parameter

ConnectToGit API menerima parameter berikut:

Parameter_ Jenis Diperlukan Perihalan
GitFolder String Ya Nama folder yang anda mahu ikat penyelesaian atau persekitaran anda.
Branch String Ya Nama cawangan yang anda mahu sambungkan.
ConnectionType Integer Tidak Menentukan perkara yang hendak disambungkan. Lihat parameter ConnectionType.
GitProvider Integer Tidak Pembekal Git. Lihat parameter GitProvider.
Organization String Tidak Nama organisasi yang anda mahu sambungkan.
Project String Tidak Nama projek yang anda mahu sambungkan.
Repository String Tidak Nama repositori yang anda mahu sambungkan.
RootFolder String Tidak Nama folder akar di mana semua penyelesaian anda berada dalam skop penyelesaian.
SolutionUniqueName String Tidak Nama unik penyelesaian yang anda ingin sambungkan ke git.
UpstreamBranch String Tidak Nama cawangan huluan yang anda mahu sambungkan. Lalai kepada cawangan lalai repositori.
GitHubConnectionId String Tidak ID Sambungan untuk sambungan Power Platform GitHub. Diperlukan bila GitProvider kecuali 1 anda menyediakan GitHubPAT. Tidak boleh digunakan apabila sokongan rangkaian maya (VNET) diaktifkan untuk persekitaran Dataverse.
GitHubPAT String Tidak Token akses peribadi GitHub dengan akses ke repositori sasaran. Diperlukan bila GitProvider kecuali 1 anda menyediakan GitHubConnectionId. Diperlukan apabila sokongan rangkaian maya (VNET) diaktifkan untuk persekitaran Dataverse.
GitHubAppConfigId String Tidak Rujukan kepada rekod konfigurasi Aplikasi GitHub. Diperlukan bila GitProvider .1 Gunakan format githubappconfigs(<recordId>).

Parameter ConnectionType

Parameter mengawal ConnectionType sama ada untuk menyambung ke keseluruhan persekitaran Dataverse atau penyelesaian tertentu.

Nilai Label Perihalan
0 Penyelesaian Menyambungkan penyelesaian Dataverse tertentu ke Git.
1 Persekitaran Menyambungkan keseluruhan persekitaran Dataverse ke Git.

Parameter GitProvider

Gunakan GitProvider parameter untuk menentukan jenis pembekal Git yang anda gunakan, sama ada Azure DevOps atau GitHub.

Nilai Label Perihalan
0 Azure DevOps Gunakan untuk repositori yang dihoskan pada Azure DevOps
1 GitHub Gunakan untuk repositori yang dihoskan pada GitHub

API Putuskan Sambungan DariGit

Mengalih keluar sambungan Git daripada penyelesaian atau persekitaran Dataverse dan menyahdayakan penyepaduan kawalan sumber.

Parameter_

DisconnectFromGit API hanya mempunyai satu parameter.

Parameter_ Jenis Diperlukan Perihalan
SolutionUniqueName String Tidak Nama unik penyelesaian yang anda mahu putuskan sambungan daripada Git. Jangan putuskan sambungan semua penyelesaian atau persekitaran.

Maklumat tambahan

Berikut ialah beberapa pilihan nilai parameter untuk ditentukan semasa memanggil DisconnectFromGit.

  • Putuskan sambungan penyelesaian tunggal: Sediakan SolutionUniqueName untuk memutuskan sambungan penyelesaian tertentu.
  • Putuskan sambungan semua penyelesaian: Sediakan tiada parameter untuk memutuskan sambungan semua sambungan peringkat penyelesaian.
  • Putuskan sambungan persekitaran: Sediakan tiada parameter untuk memutuskan sambungan peringkat persekitaran.

Contoh

Contoh berikut menerangkan senario untuk menggunakan ConnectToGit API dan DisconnectFromGit :

Sambungkan keseluruhan persekitaran Dataverse anda ke repositori Azure DevOps

Sambungan ini membolehkan kawalan sumber untuk semua konfigurasi dan komponen peringkat persekitaran.

Jangan gunakan parameter ini dengan sambungan ini:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Contoh ini menunjukkan cara menggunakan tindakan ConnectToGit untuk menyambungkan keseluruhan persekitaran 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"
}

Respons

HTTP/1.1 204 No Content
OData-Version: 4.0

Ketahui cara memanggil tindakan API Web

Sambung ke repositori GitHub

Sebelum anda menggunakan API untuk menyambung ke GitHub, lengkapkan langkah persediaan untuk mencipta Aplikasi GitHub, pasangnya pada repositori sasaran, import kunci peribadinya ke Azure Key Vault, dan cipta sambungan Power Platform GitHub. Untuk maklumat lanjut, lihat Sambung ke GitHub.

Cipta rekod konfigurasi Aplikasi GitHub menggunakan Web API

Gunakan Dataverse OData Web API untuk mencipta githubappconfig rekod. Hantar permintaan POST dengan ID klien Aplikasi GitHub, URI Key Vault, dan nama kunci.

Anda boleh menggunakan mana-mana klien HTTP, seperti Insomnia, Visual Studio Code REST Client, atau curl, untuk membuat panggilan ini. Anda perlukan token pembawa untuk pengesahan. Untuk maklumat lanjut, lihat Gunakan API Web Microsoft Dataverse.

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

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

Penting

Perhatikan ID rekod yang dikembalikan dalam pengepala respons. Anda memerlukan nilai ini untuk mengenal pasti identiti yang diurus, mengkonfigurasi RBAC, dan memanggil ConnectToGit. ID rekod menggunakan format seperti 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Selepas mencipta rekod konfigurasi Aplikasi GitHub, tetapkan peranan Pengguna Kripto Key Vault kepada identiti terurus Dataverse seperti yang diterangkan dalam Konfigurasi kawalan akses berasaskan peranan Key Vault (RBAC).

Panggil API ConnectToGit

Selepas anda mencipta githubappconfig rekod dan mengkonfigurasi Key Vault RBAC, gunakan Dataverse Web API untuk mewujudkan sambungan kawalan sumber dengan memanggil tindakan tersebutConnectToGit.

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

Penting

Cawangan mesti sudah wujud dalam repositori. Cipta dahulu di GitHub jika perlu. Nilai mesti GitHubAppConfigId menggunakan format githubappconfigs(<recordId>).

Tangkapan skrin badan permintaan HTTP untuk API ConnectToGit dengan parameter GitHub.

Jika anda menerima respons yang berjaya, persekitaran akan disambungkan ke GitHub.

Sambung ke repositori GitHub menggunakan PowerShell

Contoh PowerShell berikut mencipta rekod konfigurasi GitHub App, menunggu identiti terurus Dataverse muncul dalam Microsoft Entra ID, menetapkan peranan Key Vault Crypto User kepada identiti yang diurus, dan memanggil tindakan tersebutConnectToGit. Jika anda sudah mempunyai rekod konfigurasi Aplikasi GitHub, pastikan GitHubAppConfigId untuk melangkau langkah penugasan peranan konfigurasi dan Key Vault.

Pasang dan import Az.Accountsmodul , Az.KeyVault, dan Az.Resources PowerShell sebelum anda menjalankan contoh tersebut. Log masuk menggunakan Connect-AzAccount akaun yang mempunyai akses ke persekitaran Dataverse dan kebenaran untuk menetapkan peranan Key Vault.

Jika sokongan rangkaian maya (VNET) diaktifkan untuk persekitaran Dataverse, sediakan GitHubPAT. Sambungan GitHub tidak boleh digunakan dengan sokongan rangkaian maya.

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

Putuskan sambungan keseluruhan persekitaran Dataverse anda daripada kawalan sumber Git

Tindakan ini mengalih keluar sambungan Git peringkat persekitaran. Jangan gunakan SolutionUniqueName parameter untuk operasi ini. Dataverse secara automatik mengenal pasti dan mengalih keluar sambungan Git peringkat persekitaran.

Contoh ini menunjukkan cara menggunakan tindakan DisconnectFromGit untuk memutuskan sambungan keseluruhan persekitaran Dataverse anda daripada kawalan 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

Respons

HTTP/1.1 204 No Content
OData-Version: 4.0

Ketahui cara memanggil tindakan API Web

Sambungkan penyelesaian pertama ke repositori Git

Sambungan ini mewujudkan pautan repositori dan struktur folder untuk kawalan sumber peringkat penyelesaian kepada penyelesaian pertama dalam persekitaran.

Anda perlu memasukkan nilai untuk parameter ini untuk menentukan penyelesaian:

  • RootFolder
  • SolutionUniqueName

Contoh ini menunjukkan cara menggunakan tindakan ConnectToGit untuk menyambungkan penyelesaian 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"
}

Respons

HTTP/1.1 204 No Content
OData-Version: 4.0

Ketahui cara memanggil tindakan API Web

Sambungkan penyelesaian tambahan ke repositori Git yang sama selepas anda menyambungkan penyelesaian awal

Selepas anda menyambungkan penyelesaian pertama, anda hanya memerlukan parameter khusus penyelesaian. Anda mewarisi butiran sambungan repositori daripada sambungan awal.

Tetapkan parameter ini sahaja:

  • SolutionUniqueName
  • Branch
  • GitFolder

Penting

Anda mesti menyambungkan penyelesaian pertama terlebih dahulu sebelum ini berfungsi. Lihat Sambungkan penyelesaian pertama ke repositori Git.

Contoh ini menunjukkan cara menggunakan tindakan ConnectToGit untuk menyambungkan penyelesaian 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"
}

Respons

HTTP/1.1 204 No Content
OData-Version: 4.0

Ketahui cara memanggil tindakan API Web

Putuskan sambungan penyelesaian tertentu daripada kawalan sumber Git sambil memastikan penyelesaian lain disambungkan

Gunakan pendekatan ini untuk mengalih keluar kawalan sumber bagi satu penyelesaian tanpa menjejaskan yang lain.

Contoh ini menunjukkan cara menggunakan tindakan DisconnectFromGit untuk mengalih keluar kawalan sumber untuk satu penyelesaian tanpa menjejaskan 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"
}

Respons

HTTP/1.1 204 No Content
OData-Version: 4.0

Ketahui cara memanggil tindakan API Web

Pengendalian ralat

API mahupun ConnectToGitDisconnectFromGit tidak mengembalikan nilai apabila ia berjaya diselesaikan. Apabila API gagal, ia mengembalikan ralat.

Senario ralat biasa termasuk:

  • Kelayakan tidak sah: Pastikan anda mempunyai pengesahan yang sah kepada pembekal Git.
  • Repositori tidak dijumpai: Sahkan nama organisasi, projek dan repositori.
  • Kebenaran ditolak: Pastikan akaun Dataverse anda mempunyai keizinan pengurusan kawalan sumber.
  • Penyelesaian tidak dijumpai: Sahkan kewujudan SolutionUniqueName dalam persekitaran anda.
  • Cawangan tidak wujud: Sahkan cawangan yang ditentukan wujud dalam repositori.

Sokongan dan sumber tambahan

Untuk maklumat lanjut tentang penyepaduan kawalan sumber dengan Dataverse, lihat:

  • Last updated on