Dataversen yhdistäminen ja katkaiseminen Git-säilöön koodin avulla

-ja ConnectToGit -DisconnectFromGitohjelmointirajapintojen avulla voit integroida Microsoft Dataverse -ympäristösi Git-lähteen hallinnan kanssa. Näiden ohjelmointirajapintojen avulla voit yhdistää yksittäisiä ratkaisuja tai kokonaisia ympäristöjä tuettuihin Git-säilöihin ja hallita näitä yhteyksiä koodin avulla.

Edellytykset

Varmista ennen näiden ohjelmointirajapintojen käyttöä, että sinulla on seuraavat asiat:

• Pääsy Microsoft Dataverse -ympäristöön
• Järjestelmänvalvojan oikeudet
• Git-säilön luku- ja kirjoitusoikeudet

ConnectToGit-ohjelmointirajapinta

Luo yhteyden Dataverse-ratkaisun tai ympäristön ja Git-säilön välille. Käyttämällä tätä yhteyttä voit hallita Dataverse-osien lähdeohjausobjektia.

Parametrit

Ohjelmointirajapinta ConnectToGit hyväksyy seuraavat parametrit:

ConnectionType-parametri

ConnectionType Parametri määrittää, muodostetaanko yhteys koko Dataverse-ympäristöön vai tiettyyn ratkaisuun.

GitProvider-parametri

-parametrin GitProvider avulla voit määrittää käyttämäsi Git-palvelun tyypin( joko Azure DevOps tai GitHub).

DisconnectFromGit-ohjelmointirajapinta

Poistaa Git-yhteyden Dataverse-ratkaisusta tai -ympäristöstä ja poistaa lähteen hallinnan integroinnin käytöstä.

Parametri

-ohjelmointirajapinnalla DisconnectFromGit on vain yksi parametri.

Lisätietoja

Seuraavassa on muutamia parametriarvoasetuksia, jotka määritetään käynnistäessäsi DisconnectFromGit.

• Katkaise yhteys yksittäiseen ratkaisuun: Anna SolutionUniqueName , jos haluat katkaista tietyn ratkaisun.
• Katkaise kaikki ratkaisut: Älä anna parametreja kaikkien ratkaisutason yhteyksien katkaisemiseksi.
• Ympäristön katkaiseminen: Älä anna parametreja ympäristötason yhteyden katkaisemiseksi.

Esimerkit

Seuraavissa esimerkeissä kuvataan -ja DisconnectFromGit -ConnectToGitohjelmointirajapintojen käyttöskenaarioita:

• Koko Dataverse-ympäristön yhdistäminen Azure DevOps -säilöön
• Yhdistäminen GitHub säilöön
• Yhteyden muodostaminen GitHub säilöön PowerShellin avulla
• Koko Dataverse-ympäristön katkaiseminen Git-lähdeohjausobjektista
• Ensimmäisen ratkaisun yhdistäminen Git-säilöön
• Yhdistä ylimääräiset ratkaisut samaan Git-säilöön sen jälkeen, kun olet muodostanut yhteyden alkuperäiseen ratkaisuun
• Eristä ratkaisu Git-lähteen ohjausobjektista pitäen muut ratkaisut yhdistettynä

Koko Dataverse-ympäristön yhdistäminen Azure DevOps -säilöön

Tämä yhteys mahdollistaa lähdehallinnan kaikissa ympäristötason määrityksissä ja komponenteissa.

Älä käytä näitä parametreja tässä yhteydessä:

• RootFolder
• SolutionUniqueName
• UpstreamBranch

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

private const int GitProviderAzureDevOps = 0;
private const int GitProviderGitHub = 1;
private const int ConnectionTypeEnvironment = 1;

static void ConnectDataverseEnvironment(
    IOrganizationService service,
    string gitFolderName,
    string branchName,
    string organizationName,
    string projectName,
    string repositoryName,
    OptionSetValue? gitProvider = null)
{
    // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
    ArgumentException.ThrowIfNullOrWhiteSpace(organizationName);
    ArgumentException.ThrowIfNullOrWhiteSpace(projectName);
    ArgumentException.ThrowIfNullOrWhiteSpace(repositoryName);

    // Default to Azure Dev Ops
    gitProvider ??= new OptionSetValue(GitProviderAzureDevOps);

    ParameterCollection parameters = new()
    {
        { "GitFolder", gitFolderName },
        { "Branch", branchName },
        { "ConnectionType", new OptionSetValue(ConnectionTypeEnvironment) },
        { "GitProvider", gitProvider },
        { "Organization", organizationName },
        { "Project", projectName },
        { "Repository", repositoryName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "ConnectToGit",
        Parameters = parameters
    };

     service.Execute(request);
}

Yhdistäminen GitHub säilöön

Ennen kuin käytät ohjelmointirajapintaa yhteyden muodostamiseen GitHub, suorita asennusvaiheet GitHub sovelluksen luomiseksi, asenna se kohdesäilöön, tuo sen yksityinen avain Azure Key Vault ja luo Power Platform GitHub -yhteys. Lisätietoja on artikkelissa GitHub yhdistäminen.

GitHub sovelluksen määritystietueen luominen WWW-ohjelmointirajapinnan avulla

Luo tietue Dataverse OData Web -ohjelmointirajapinnan githubappconfig avulla. Lähetä POST-pyyntö, joka sisältää GitHub Sovelluksen asiakastunnuksen, Key Vault URI-tunnuksen ja avaimen nimen.

Voit käyttää näitä kutsuja millä tahansa HTTP-asiakasohjelmalla, kuten Insomnialla, Visual Studio Code REST-asiakasohjelmalla tai curlilla. Tarvitset haltijatunnuksen todennusta varten. Lisätietoja on kohdassa Microsoft Dataverse WWW-ohjelmointirajapinnan käyttäminen.

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

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

Kun olet luonut GitHub sovelluksen määritystietueen, määritä Key Vault-salauskäyttäjärooli Dataversen hallittuihin käyttäjätietoihin artikkelissa Roolipohjaisen käytön hallinnan Key Vault (RBAC) kuvatulla tavalla.

ConnectToGit-ohjelmointirajapinnan kutsuminen

Kun olet luonut tietueen githubappconfig ja määrittänyt Key Vault RBAC:lle, muodosta lähteen hallintayhteys Dataverse Web API:n avulla kutsumalla ConnectToGit toimintoa.

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

Jos saat onnistuneen vastauksen, ympäristö on yhdistetty GitHub.

Yhteyden muodostaminen GitHub säilöön PowerShellin avulla

Seuraava PowerShell-esimerkki luo GitHub sovelluksen määritystietueen, odottaa Dataversen hallittujen käyttäjätietojen näkymistä Microsoft Entra ID, määrittää Key Vault Crypto-käyttäjäroolin hallituille käyttäjätiedoilla ja kutsuu ConnectToGit toimintoa. Jos sinulla on jo GitHub Sovelluksen määritystietue, ohita GitHubAppConfigId määritys ja Key Vault roolimääritysvaiheet.

Asenna ja tuo Az.Accounts-, Az.KeyVault- ja Az.Resources PowerShell-moduulit, ennen esimerkin suorittamista. Kirjaudu sisään käyttämällä tiliä, jolla Connect-AzAccount on pääsy Dataverse-ympäristöön ja oikeus määrittää Key Vault roolia.

Jos näennäisverkon (VNET) tuki on käytössä Dataverse-ympäristössä, anna GitHubPAT. GitHub yhteyksiä ei voi käyttää näennäisverkon tuen kanssa.

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

Koko Dataverse-ympäristön katkaiseminen Git-lähdeohjausobjektista

Tämä toiminto poistaa ympäristötason Git-yhteyden. Älä käytä parametria SolutionUniqueName tälle toiminnolle. Dataverse tunnistaa ja poistaa ympäristötason Git-yhteyden automaattisesti.

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

static void DisconnectDataverseEnvironment(IOrganizationService service) {

   // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);

   OrganizationRequest request = new("DisconnectFromGit");

   service.Execute(request);

}

Ensimmäisen ratkaisun yhdistäminen Git-säilöön

Tämä yhteys muodostaa säilön linkin ja kansiorakenteen ratkaisutason lähteen hallintaa varten ympäristön ensimmäiseen ratkaisuun.

Sinun on sisällytettävä arvot seuraaville parametreille ratkaisun määrittämiseksi:

• RootFolder
• SolutionUniqueName

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

private const int ConnectionTypeSolution = 0;

static void ConnectFirstSolution(
    IOrganizationService service,
    string gitFolderName,
    string branchName,
    string organizationName,
    string projectName,
    string repositoryName,
    string rootFolderName,
    string solutionUniqueName,
    OptionSetValue? gitProvider = null)
{
    // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
    ArgumentException.ThrowIfNullOrWhiteSpace(organizationName);
    ArgumentException.ThrowIfNullOrWhiteSpace(projectName);
    ArgumentException.ThrowIfNullOrWhiteSpace(repositoryName);
    ArgumentException.ThrowIfNullOrWhiteSpace(rootFolderName);
    ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

    // Default to Azure Dev Ops
    gitProvider ??= new OptionSetValue(GitProviderAzureDevOps);

    ParameterCollection parameters = new()
    {
        { "GitFolder", gitFolderName },
        { "Branch", branchName },
        { "ConnectionType", new OptionSetValue(ConnectionTypeSolution) },
        { "GitProvider", gitProvider },
        { "Organization", organizationName },
        { "Project", projectName },
        { "Repository", repositoryName },
        { "RootFolder", rootFolderName },
        { "SolutionUniqueName", solutionUniqueName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "ConnectToGit",
        Parameters = parameters
    };

    service.Execute(request);
}

Yhdistä ylimääräiset ratkaisut samaan Git-säilöön sen jälkeen, kun olet muodostanut yhteyden alkuperäiseen ratkaisuun

Kun olet muodostanut yhteyden ensimmäiseen ratkaisuun, tarvitset vain ratkaisukohtaiset parametrit. Perit säilön yhteyden tiedot ensiyhteyden kautta.

Määritä vain nämä parametrit:

• SolutionUniqueName
• Branch
• GitFolder

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

static void ConnectExtraSolution(
   IOrganizationService service,
   string gitFolderName,
   string branchName,
   string solutionUniqueName)
{
   // Validate required parameters
   ArgumentNullException.ThrowIfNull(service);
   ArgumentException.ThrowIfNullOrWhiteSpace(gitFolderName);
   ArgumentException.ThrowIfNullOrWhiteSpace(branchName);
   ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

   ParameterCollection parameters = new()
   {
         { "GitFolder", gitFolderName },
         { "Branch", branchName },
         { "SolutionUniqueName", solutionUniqueName }
   };

   OrganizationRequest request = new()
   {
         RequestName = "ConnectToGit",
         Parameters = parameters
   };

   service.Execute(request);
}

Eristä ratkaisu Git-lähteen ohjausobjektista pitäen muut ratkaisut yhdistettynä

Tämän lähestymistavan avulla voit poistaa lähteen hallinnan yhdestä ratkaisusta vaikuttamatta muihin.

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

static void DisconnectSolution(IOrganizationService service,
    string solutionUniqueName)
{

   // Validate required parameters
    ArgumentNullException.ThrowIfNull(service);
    ArgumentException.ThrowIfNullOrWhiteSpace(solutionUniqueName);

    ParameterCollection parameters = new()
    {
        { "SolutionUniqueName", solutionUniqueName }
    };

    OrganizationRequest request = new()
    {
        RequestName = "DisconnectFromGit",
        Parameters = parameters
    };

    service.Execute(request);
}

Virheen käsittely

ConnectToGit- ja -DisconnectFromGitohjelmointirajapinta eivät palauta arvoa, kun se on suoritettu onnistuneesti. Kun ohjelmointirajapinta epäonnistuu, se palauttaa virheen.

Yleisiä virhetilanteita ovat seuraavat:

• Virheelliset tunnistetiedot: Varmista, että sinulla on kelvollinen todennus Git-palveluun.
• Säilöä ei löydy: Tarkista organisaation, projektin ja säilön nimet.
• Käyttöoikeus estetty: Varmista, että Dataverse-tililläsi on lähteen hallinnan hallintaoikeudet.
• Ratkaisua ei löydy: Varmista, että SolutionUniqueName ympäristösi on olemassa.
• Haaraa ei ole: Varmista, että määritetty haara on olemassa säilössä.

Tuki ja lisäresurssit

Lisätietoja lähteen hallinnan integroinnista Dataverseen on ohjeaiheessa:

• Power Platformin Git-integroinnin yleiskatsaus
• ConnectToGit-toiminto
• DisconnectFromGit-toiminto
• CommitToGit-toiminto
• RefreshChangesFromGit-toiminto
• PullChangesFromGit-toiminto