Kết nối và ngắt kết nối Dataverse khỏi kho lưu trữ Git bằng cách sử dụng mã

Sử dụng ConnectToGit API và DisconnectFromGit để tích hợp môi trường Microsoft Dataverse của bạn theo chương trình với kiểm soát nguồn Git. Bằng cách sử dụng các API này, bạn có thể kết nối các giải pháp riêng lẻ hoặc toàn bộ môi trường với các kho git được hỗ trợ và quản lý các kết nối đó thông qua mã.

Điều kiện tiên quyết

Trước khi sử dụng các API này, hãy đảm bảo bạn có:

  • Truy nhập vào môi trường Microsoft Dataverse
  • Quyền quản trị viên hệ thống
  • Quyền truy cập đọc và ghi vào kho lưu trữ Git

ConnectToGit API

Tạo kết nối giữa giải pháp hoặc môi trường Dataverse và kho lưu trữ Git. Bằng cách sử dụng kết nối này, bạn có thể quản lý kiểm soát nguồn cho các thành phần Dataverse của mình.

Tham số

API ConnectToGit chấp nhận các thông số sau:

Tham số Loại Required Description
GitFolder Chuỗi Có Tên của thư mục bạn muốn liên kết giải pháp hoặc môi trường của mình.
Branch Chuỗi Có Tên của nhánh bạn muốn kết nối.
ConnectionType Số nguyên Không Chỉ định những gì cần kết nối. Xem tham số ConnectionType.
GitProvider Số nguyên Không Nhà cung cấp Git. Xem tham số GitProvider.
Organization Chuỗi Không Tên của tổ chức bạn muốn kết nối.
Project Chuỗi Không Tên của dự án bạn muốn kết nối.
Repository Chuỗi Không Tên của kho lưu trữ bạn muốn kết nối.
RootFolder Chuỗi Không Tên của thư mục gốc nơi tất cả các giải pháp của bạn nằm trong phạm vi giải pháp.
SolutionUniqueName Chuỗi Không Tên duy nhất của giải pháp bạn muốn kết nối với git.
UpstreamBranch Chuỗi Không Tên của nhánh ngược dòng bạn muốn kết nối. Mặc định là nhánh mặc định của kho lưu trữ.
GitHubConnectionId Chuỗi Không ID Kết nối cho kết nối GitHub Power Platform. Bắt buộc khi trừ GitProvider khi 1 bạn cung cấp GitHubPAT. Không thể sử dụng khi hỗ trợ mạng ảo (VNET) được bật cho môi trường Dataverse.
GitHubPAT Chuỗi Không GitHub mã thông báo truy nhập cá nhân có quyền truy nhập vào kho mục tiêu. Bắt buộc khi trừ GitProvider khi 1 bạn cung cấp GitHubConnectionId. Bắt buộc khi hỗ trợ mạng ảo (VNET) được bật cho môi trường Dataverse.
GitHubAppConfigId Chuỗi Không Tham chiếu đến bản ghi GitHub cấu hình Ứng dụng của bạn. Bắt buộc khi GitProvider là 1. Sử dụng định dạng githubappconfigs(<recordId>).

Tham số ConnectionType

Tham số kiểm ConnectionType soát xem có kết nối với toàn bộ môi trường Dataverse hay một giải pháp cụ thể hay không.

Giá trị Nhãn Description
0 Giải pháp Kết nối một giải pháp Dataverse cụ thể với Git.
1 Môi trường Kết nối toàn bộ môi trường Dataverse với Git.

Tham số GitProvider

Sử dụng tham số để GitProvider chỉ định loại nhà cung cấp Git bạn đang sử dụng, Azure DevOps hoặc GitHub.

Giá trị Nhãn Description
0 Azure DevOps Sử dụng cho các kho lưu trữ được lưu trữ trên Azure DevOps
1 GitHub Sử dụng cho các kho lưu trữ được lưu trữ trên GitHub

API Ngắt kết nối từ Git

Xóa kết nối Git khỏi giải pháp hoặc môi trường Dataverse và tắt tích hợp kiểm soát nguồn.

Tham số

DisconnectFromGit API chỉ có một tham số.

Tham số Loại Required Description
SolutionUniqueName Chuỗi Không Tên duy nhất của giải pháp bạn muốn ngắt kết nối khỏi Git. Bỏ qua việc ngắt kết nối tất cả các giải pháp hoặc môi trường.

Thông tin bổ sung

Dưới đây là một số tùy chọn giá trị tham số để chỉ định khi gọi DisconnectFromGit.

  • Ngắt kết nối giải pháp đơn: Cung cấp SolutionUniqueName để ngắt kết nối một giải pháp cụ thể.
  • Ngắt kết nối tất cả các giải pháp: Không cung cấp thông số nào để ngắt kết nối tất cả các kết nối cấp giải pháp.
  • Ngắt kết nối môi trường: Không cung cấp thông số nào để ngắt kết nối cấp môi trường.

Ví dụ

Các ví dụ sau đây mô tả các kịch bản cho việc sử ConnectToGit dụng DisconnectFromGit và API:

Kết nối toàn bộ môi trường Dataverse của bạn với kho lưu trữ Azure DevOps

Kết nối này cho phép kiểm soát nguồn cho tất cả các cấu hình và thành phần cấp môi trường.

Không sử dụng các thông số này với kết nối này:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Ví dụ này cho thấy cách sử dụng hành động ConnectToGit để kết nối toàn bộ môi trường Dataverse của bạn với kho lưu trữ Azure DevOps.

Yêu cầu

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

Phản hồi

HTTP/1.1 204 No Content
OData-Version: 4.0

Tìm hiểu cách gọi các hành động API Web

Kết nối với kho GitHub dữ liệu

Trước khi bạn sử dụng API để kết nối với GitHub, hãy hoàn thành các bước thiết lập để tạo Ứng dụng GitHub, cài đặt nó trên kho mục tiêu, nhập khóa riêng của nó vào Azure Key Vault và tạo kết nối GitHub Nền tảng Nguồn. Để biết thêm thông tin, hãy xem Kết nối với GitHub.

Tạo bản ghi cấu GitHub App bằng cách sử dụng API Web

Sử dụng API Web OData Dataverse để tạo bản githubappconfig ghi. Gửi yêu cầu POST với ID GitHub Ứng dụng, Key Vault URI và tên khóa.

Bạn có thể sử dụng bất kỳ máy khách HTTP nào, chẳng hạn như Mất ngủ, Visual Studio Code REST Client hoặc curl, để thực hiện các cuộc gọi này. Bạn cần một mã thông báo người mang để xác thực. Để biết thêm thông tin, hãy xem mục Sử Microsoft Dataverse API Web.

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

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

Quan trọng

Lưu ý ID bản ghi được trả về trong tiêu đề phản hồi. Bạn cần giá trị này để xác định danh tính được quản lý, cấu hình RBAC và gọi ConnectToGit. ID bản ghi sử dụng định dạng như 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Sau khi tạo hồ sơ cấu hình ứng dụng GitHub, gán vai trò người dùng tiền điện tử Key Vault cho danh tính được quản lý câu dữ liệu như được mô tả trong Cấu hình kiểm soát truy cập dựa trên vai trò Key Vault (RBAC).

Gọi API ConnectToGit

Sau khi bạn tạo bản ghi githubappconfig và đặt cấu hình Key Vault RBAC, hãy sử dụng API Web Dataverse để thiết lập kết nối điều khiển nguồn bằng cách gọi hành ConnectToGit động.

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

Quan trọng

Nhánh phải tồn tại trong kho. Trước tiên, hãy tạo GitHub trong tài liệu nếu cần. Giá GitHubAppConfigId trị phải sử dụng định dạng githubappconfigs(<recordId>).

Ảnh chụp màn hình nội dung yêu cầu HTTP cho API ConnectToGit với các GitHub số.

Nếu bạn nhận được một phản ứng thành công, môi trường được kết nối với GitHub.

Kết nối với kho GitHub bằng cách sử dụng PowerShell

Ví dụ powerShell sau tạo bản ghi cấu hình ứng dụng GitHub, chờ cho danh tính được quản lý của Câu dữ liệu xuất hiện trong Microsoft Entra ID, gán vai trò người dùng tiền điện tử Key Vault cho danh tính được quản lý và ConnectToGit gọi hành động. Nếu bạn đã có bản ghi cấu hình GitHub App, GitHubAppConfigId hãy cung cấp để bỏ qua cấu hình và thực hiện Key Vault các bước gán vai trò.

Cài đặt và nhập Az.Accountsmô-đun Az.Resources , Az.KeyVaultvà PowerShell trước khi bạn chạy ví dụ. Đăng nhập bằng Connect-AzAccount cách sử dụng tài khoản có quyền truy nhập vào môi trường Dataverse và quyền gán Key Vault vai trò.

Nếu hỗ trợ mạng ảo (VNET) được bật cho môi trường Dataverse, hãy cung cấp GitHubPAT. GitHub thể được sử dụng với hỗ trợ mạng ảo.

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

Ngắt kết nối toàn bộ môi trường Dataverse của bạn khỏi kiểm soát nguồn Git

Hành động này sẽ loại bỏ kết nối Git cấp môi trường. Không sử dụng tham số cho SolutionUniqueName thao tác này. Dataverse tự động xác định và xóa kết nối Git cấp môi trường.

Ví dụ này cho thấy cách sử dụng hành động DisconnectFromGit để ngắt kết nối toàn bộ môi trường Dataverse của bạn khỏi kiểm soát nguồn Git.

Yêu cầu

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

Phản hồi

HTTP/1.1 204 No Content
OData-Version: 4.0

Tìm hiểu cách gọi các hành động API Web

Kết nối giải pháp đầu tiên với kho lưu trữ Git

Kết nối này thiết lập cấu trúc thư mục và liên kết kho lưu trữ để kiểm soát nguồn cấp giải pháp cho giải pháp đầu tiên trong môi trường.

Bạn cần bao gồm các giá trị cho các tham số này để chỉ định giải pháp:

  • RootFolder
  • SolutionUniqueName

Ví dụ này cho thấy cách sử dụng hành động ConnectToGit để kết nối giải pháp đầu tiên với kho lưu trữ Git.

Yêu cầu

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

Phản hồi

HTTP/1.1 204 No Content
OData-Version: 4.0

Tìm hiểu cách gọi các hành động API Web

Kết nối các giải pháp bổ sung với cùng một kho lưu trữ Git sau khi bạn kết nối giải pháp ban đầu

Sau khi kết nối giải pháp đầu tiên, bạn chỉ cần các thông số dành riêng cho giải pháp. Bạn kế thừa chi tiết kết nối kho lưu trữ từ kết nối ban đầu.

Chỉ đặt các thông số sau:

  • SolutionUniqueName
  • Branch
  • GitFolder

Quan trọng

Trước tiên, bạn phải kết nối giải pháp đầu tiên trước khi điều này hoạt động. Xem Kết nối giải pháp đầu tiên với kho lưu trữ Git.

Ví dụ này cho thấy cách sử dụng hành động ConnectToGit để kết nối các giải pháp tiếp theo với kho lưu trữ Git.

Yêu cầu

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

Phản hồi

HTTP/1.1 204 No Content
OData-Version: 4.0

Tìm hiểu cách gọi các hành động API Web

Ngắt kết nối một giải pháp cụ thể khỏi kiểm soát nguồn Git trong khi vẫn giữ các giải pháp khác được kết nối

Sử dụng cách tiếp cận này để loại bỏ kiểm soát nguồn cho một giải pháp mà không ảnh hưởng đến các giải pháp khác.

Ví dụ này cho thấy cách sử dụng hành động DisconnectFromGit để loại bỏ kiểm soát nguồn cho một giải pháp mà không ảnh hưởng đến các giải pháp khác.

Yêu cầu

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

Phản hồi

HTTP/1.1 204 No Content
OData-Version: 4.0

Tìm hiểu cách gọi các hành động API Web

Xử lý lỗi

Cả ConnectToGit API và DisconnectFromGit API đều không trả về giá trị khi hoàn tất thành công. Khi một API bị lỗi, nó sẽ trả về một lỗi.

Các tình huống lỗi phổ biến bao gồm:

  • Thông tin đăng nhập không hợp lệ: Đảm bảo bạn có xác thực hợp lệ với nhà cung cấp Git.
  • Không tìm thấy kho lưu trữ: Xác minh tên tổ chức, dự án và kho lưu trữ.
  • Quyền bị từ chối: Đảm bảo tài khoản Dataverse của bạn có quyền quản lý kiểm soát nguồn.
  • Không tìm thấy giải pháp: Xác minh sự SolutionUniqueName tồn tại trong môi trường của bạn.
  • Nhánh không tồn tại: Xác nhận nhánh được chỉ định tồn tại trong kho lưu trữ.

Hỗ trợ và tài nguyên bổ sung

Để biết thêm thông tin về tích hợp kiểm soát nguồn với Dataverse, hãy xem:

  • Last updated on