Kod kullanarak Dataverse'e bağlanma ve Git deposu bağlantısını kesme

Microsoft Dataverse ortamınızı Git kaynak denetimiyle program aracılığıyla tümleştirmek için ConnectToGit ve DisconnectFromGit API'lerini kullanın. Bu API'leri kullanarak tek tek çözümleri veya ortamların tamamını desteklenen Git depolarına bağlayabilir ve bu bağlantıları kod aracılığıyla yönetebilirsiniz.

Prerequisites

Bu API'leri kullanmadan önce şunlara sahip olduğunuzdan emin olun:

  • Microsoft Dataverse ortamına erişim
  • Sistem yöneticisi izinleri
  • Git deposuna okuma ve yazma erişimi

ConnectToGit API

Dataverse çözümü veya ortamı ile Git deposu arasında bir bağlantı oluşturur. Bu bağlantıyı kullanarak Dataverse bileşenleriniz için kaynak denetimini yönetebilirsiniz.

Parameters

ConnectToGit API aşağıdaki parametreleri kabul eder:

Parametre Türü Zorunlu Description
GitFolder String Evet Çözümünüzü veya ortamınızı bağlamak istediğiniz klasörün adı.
Branch String Evet Bağlanmak istediğiniz dalın adı.
ConnectionType Tam sayı Hayır Bağlanılacak şeyi belirtir. Bkz. ConnectionType parametresi.
GitProvider Tam sayı Hayır Git sağlayıcısı. Bkz . GitProvider parametresi.
Organization String Hayır Bağlanmak istediğiniz kuruluşun adı.
Project String Hayır Bağlanmak istediğiniz projenin adı.
Repository String Hayır Bağlanmak istediğiniz deponun adı.
RootFolder String Hayır Tüm çözümlerinizin çözüm kapsamında bulunduğu kök klasörün adı.
SolutionUniqueName String Hayır Git'e bağlanmak istediğiniz çözümün benzersiz adı.
UpstreamBranch String Hayır Bağlanmak istediğiniz yukarı akış dalının adı. Varsayılan olarak deponun varsayılan dalına ayarlanır.
GitHubConnectionId String Hayır Power Platform GitHub bağlantısının bağlantı kimliği. GitProvider 1 olduğunda gereklidir, aksi takdirde GitHubPAT sağlamanız gerekir. Dataverse ortamı için sanal ağ (VNET) desteği etkinleştirildiğinde kullanılamaz.
GitHubPAT String Hayır Hedef depoya erişimi olan GitHub kişisel erişim belirteci. GitProvider 1 olduğunda gereklidir, aksi takdirde GitHubConnectionId sağlamanız gerekir. Dataverse ortamı için sanal ağ (VNET) desteği etkinleştirildiğinde gereklidir.
GitHubAppConfigId String Hayır GitHub Uygulaması yapılandırma kaydına referans. GitProvider 1 olduğunda gereklidir. githubappconfigs(<recordId>) biçimini kullanın.

ConnectionType parametresi

parametresi, ConnectionType Dataverse ortamının tamamına mı yoksa belirli bir çözüme mi bağlanılıp bağlanılmayacağını denetler.

Değer Etiket Description
0 Çözüm Belirli bir Dataverse çözümünü Git'e bağlar.
1 Ortam Dataverse ortamının tamamını Git'e bağlar.

GitProvider parametresi

GitProvider Azure DevOps veya GitHub olmak üzere kullandığınız Git sağlayıcısının türünü belirtmek için parametresini kullanın.

Değer Etiket Description
0 Azure DevOps Azure DevOps'ta barındırılan depolar için kullanın
1 GitHub (İngilizce) GitHub'da barındırılan depolar için kullanın

Git'ten Bağlantıyı Kes API

Dataverse çözümünden veya ortamından Git bağlantısını kaldırır ve kaynak denetimi tümleştirmesini devre dışı bırakır.

Parametre

API'nin DisconnectFromGit yalnızca bir parametresi vardır.

Parametre Türü Zorunlu Description
SolutionUniqueName String Hayır Git bağlantısını kesmek istediğiniz çözümün benzersiz adı. Tüm çözümleri veya ortamı bağlamaktan vazgeçin.

Ek bilgiler

İşte DisconnectFromGit çağrılırken belirtilecek birkaç parametre değer seçeneği.

  • Tek çözümün bağlantısını kes: Belirli bir çözümün bağlantısını kesmek için SolutionUniqueName kullanın.
  • Çözüm bağlantılarını kes: Çözüm seviyesindeki tüm bağlantıları kesmek için parametre sağlamayın.
  • Ortamın bağlantısını kes: Ortam düzeyindeki bağlantıyı kesmek için hiçbir parametre sağlamayın.

Examples

Aşağıdaki örnekler, DisconnectFromGit ve ConnectToGit API'lerini kullanmaya yönelik senaryoları açıklamaktadır:

Dataverse ortamınızın tamamını bir Azure DevOps deposuna bağlama

Bu bağlantı, tüm ortam düzeyindeki yapılandırmalar ve bileşenler için kaynak denetimini etkinleştirir.

Bu bağlantıyla bu parametreleri kullanmayın:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

Bu örnekte, Dataverse ortamınızın tamamını bir Azure DevOps deposuna bağlamak için ConnectToGit eyleminin nasıl kullanılacağı gösterilmektedir.

İstek

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

Yanıt

HTTP/1.1 204 No Content
OData-Version: 4.0

Web API eylemlerini çağırmayı öğrenin

GitHub deposuna bağlanma

GITHUB bağlanmak için API'yi kullanmadan önce, GitHub Uygulamasını oluşturmak, hedef depoya yüklemek, özel anahtarını Azure Key Vault içeri aktarmak ve Power Platform GitHub bağlantısını oluşturmak için kurulum adımlarını tamamlayın. Daha fazla bilgi için bkz. GitHub bağlanma.

Web API'sini kullanarak GitHub Uygulama yapılandırma kaydı oluşturma

Kayıt oluşturmak için Dataverse OData Web API'sini githubappconfig kullanın. GitHub Uygulama istemci kimliği, Key Vault URI'si ve anahtar adıyla bir POST isteği gönderin.

Bu çağrıları yapmak için Uykusuzluk, Visual Studio Code REST İstemcisi veya curl gibi herhangi bir HTTP istemcisini kullanabilirsiniz. Kimlik doğrulaması için taşıyıcı belirteci gerekir. Daha fazla bilgi için bkz. Microsoft Dataverse Web API'sini kullanma.

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

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

Important

Yanıt üst bilgisinde döndürülen kayıt kimliğini not edin. Yönetilen kimliği tanımlamak, RBAC'yi yapılandırmak ve çağrısı ConnectToGityapmak için bu değere ihtiyacınız vardır. Kayıt kimliği, 13d565bb-4c22-f111-a546-7ced8d6e3e85 gibi bir biçim kullanır.

GitHub Uygulaması yapılandırma kaydını oluşturduktan sonra, Key Vault rol tabanlı erişim denetimini yapılandırma (RBAC) bölümünde açıklandığı gibi Dataverse yönetilen kimliğine Key Vault Şifreleme Kullanıcısı rolünü atayın.

ConnectToGit API'sini çağırma

githubappconfig kaydını oluşturup Key Vault RBAC’yi yapılandırdıktan sonra, ConnectToGit eylemini çağırarak kaynak denetimi bağlantısını oluşturmak için Dataverse Web API’sini kullanın.

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

Dalın depoda zaten mevcut olması gerekir. Gerekirse onu önce GitHub’da oluşturun. Değerin GitHubAppConfigId biçimini githubappconfigs(<recordId>)kullanması gerekir.

GitHub parametreleriyle ConnectToGit API'sinin HTTP istek gövdesinin ekran görüntüsü.

Başarılı bir yanıt alırsanız ortam GitHub bağlanır.

PowerShell kullanarak GitHub deposuna bağlanma

Aşağıdaki PowerShell örneği, GitHub Uygulama yapılandırma kaydını oluşturur, Dataverse yönetilen kimliğinin Microsoft Entra ID görünmesini bekler, yönetilen kimliğe Key Vault Şifreleme Kullanıcısı rolünü atar ve eylemi çağırırConnectToGit. Zaten bir GitHub Uygulaması yapılandırma kaydınız varsa, yapılandırma ve Key Vault rol atama adımlarını atlamak için GitHubAppConfigId sağlayın.

Örneği çalıştırmadan önce Az.KeyVault, Az.Resources ve Az.Accounts PowerShell modüllerini yükleyip içeri aktarın. Dataverse ortamına erişimi ve Key Vault rolleri atama izni olan bir hesapla Connect-AzAccount oturum açın.

Dataverse ortamı için sanal ağ (VNET) desteği etkinleştirildiyse, GitHubPAT belirtin. GitHub bağlantılar sanal ağ desteğiyle kullanılamaz.

[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 ortamınızın tamamının Git kaynak denetimiyle bağlantısını kesme

Bu eylem, ortam düzeyi Git bağlantısını kaldırır. Bu işlem için parametresini SolutionUniqueName kullanmayın. Dataverse, ortam düzeyi Git bağlantısını otomatik olarak tanımlar ve kaldırır.

Bu örnekte, Dataverse ortamınızın tamamının Git kaynak denetimiyle bağlantısını kesmek için DisconnectFromGit eyleminin nasıl kullanılacağı gösterilmektedir.

İstek

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

Yanıt

HTTP/1.1 204 No Content
OData-Version: 4.0

Web API eylemlerini çağırmayı öğrenin

İlk çözümü bir Git deposuna bağlama

Bu bağlantı, bir ortamdaki ilk çözüme çözüm düzeyinde kaynak denetimi için depo bağlantısını ve klasör yapısını oluşturur.

Çözümü belirtmek için bu parametrelerin değerlerini eklemeniz gerekir:

  • RootFolder
  • SolutionUniqueName

Bu örnekte, ilk çözümü bir Git deposuna bağlamak için ConnectToGit eyleminin nasıl kullanılacağı gösterilmektedir.

İstek

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

Yanıt

HTTP/1.1 204 No Content
OData-Version: 4.0

Web API eylemlerini çağırmayı öğrenin

İlk çözümü bağladıktan sonra ek çözümleri aynı Git deposuna bağlama

İlk çözümü bağladıktan sonra yalnızca çözüme özgü parametreler gerekir. Depo bağlantı ayrıntılarını ilk bağlantıdan devralırsınız.

Yalnızca şu parametreleri ayarlayın:

  • SolutionUniqueName
  • Branch
  • GitFolder

Important

Bu işlem çalışmadan önce ilk çözümü bağlamanız gerekir. Bkz. İlk çözümü git deposuna bağlama.

Bu örnekte, sonraki çözümleri bir Git deposuna bağlamak için ConnectToGit eyleminin nasıl kullanılacağı gösterilmektedir.

İstek

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

Yanıt

HTTP/1.1 204 No Content
OData-Version: 4.0

Web API eylemlerini çağırmayı öğrenin

Diğer çözümleri bağlı tutarken belirli bir çözümün Git kaynak denetimiyle bağlantısını kesme

Başkalarını etkilemeden bir çözümün kaynak denetimini kaldırmak için bu yaklaşımı kullanın.

Bu örnekte, başkalarını etkilemeden bir çözümün kaynak denetimini kaldırmak için DisconnectFromGit eyleminin nasıl kullanılacağı gösterilmektedir.

İstek

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

Yanıt

HTTP/1.1 204 No Content
OData-Version: 4.0

Web API eylemlerini çağırmayı öğrenin

Hata yönetimi

ConnectToGit ne de DisconnectFromGit API başarıyla tamamlandığında bir değer döndürmez. Api başarısız olduğunda bir hata döndürür.

Yaygın hatalar şunlardır:

  • Geçersiz kimlik bilgileri: Git sağlayıcısında geçerli kimlik doğrulamasına sahip olduğunuzdan emin olun.
  • Depo bulunamadı: Kuruluş, proje ve depo adlarını doğrulayın.
  • İzin reddedildi: Dataverse hesabınızın kaynak denetimi yönetimi izinlerine sahip olduğundan emin olun.
  • Çözüm bulunamadı: SolutionUniqueName ortamınızda bulunduğunu doğrulayın.
  • Dal yok: Belirtilen dalın depoda var olduğunu onaylayın.

Destek ve ek kaynaklar

Dataverse ile kaynak denetimi tümleştirmesi hakkında daha fazla bilgi için bkz:

  • Last updated on