Ühenda ja lahtiühenda Dataverse Git-hoidlast koodi abil

Kasuta ConnectToGit ja DisconnectFromGit API-sid, et programmiliselt integreerida oma Microsoft Dataverse'i keskkond Git lähtekoodihaldusega. Nende API-de abil saate ühendada üksikuid lahendusi või terveid keskkondi toetatud Giti hoidlatega ja hallata neid ühendusi koodi kaudu.

Eeltingimused

Enne nende API-de kasutamist veendu, et sul on:

  • Juurdepääs Microsoft Dataverse'i keskkonnale
  • Süsteemiadministraatori õigused
  • Lugemis- ja kirjutamisligipääs Git-repositooriumile

ConnectToGit API

Loob ühenduse Dataverse'i lahenduse või keskkonna ja Git-hoidla vahel. Selle ühenduse abil saad hallata oma Dataverse'i komponentide lähtekoodihaldust.

Parameetrid

API ConnectToGit aktsepteerib järgmisi parameetreid:

Parameeter Tüüp Nõutav Kirjeldus
GitFolder String Jah Kausta nimi, kuhu soovid oma lahenduse või keskkonna siduda.
Branch String Jah Haru nimi, millega soovid ühenduda.
ConnectionType Täisarv Nr Määrab, millega ühenduda. Vaata ConnectionType parameetrit.
GitProvider Täisarv Nr Git-teenuse pakkuja. Vaata GitProvider parameetrit.
Organization String Nr Organisatsiooni nimi, kellega soovid ühendust võtta.
Project String Nr Projekti nimi, millega soovid ühenduda.
Repository String Nr Andmehoidla nimi, millega soovid ühenduda.
RootFolder String Nr Juurkausta nimi, kus kõik sinu lahendused lahenduste ulatuses asuvad.
SolutionUniqueName String Nr Lahenduse ainulaadne nimi, millega soovid ühendada.
UpstreamBranch String Nr Ülemharu nimi, millega soovid ühenduda. Vaikimisi on hoidla vaikimisi haru.
GitHubConnectionId String Nr Power Platformi GitHub ühenduse ID. Nõutav, kui GitProvider te 1 ei sisesta GitHubPAT. Ei saa kasutada, kui Dataverse'i keskkonnas on lubatud virtuaalvõrgu (VNET) tugi.
GitHubPAT String Nr GitHub isiklikku pääsutõendi, millel on juurdepääs sihthoidlale. Nõutav, kui GitProvider te 1 ei sisesta GitHubConnectionId. Nõutav, kui Dataverse'i keskkonnas on lubatud virtuaalvõrgu (VNET) tugi.
GitHubAppConfigId String Nr Viide GitHub rakenduse konfiguratsioonikirjele. Vajalik, kui GitProvider on 1. Kasuta formaati githubappconfigs(<recordId>).

ConnectionType parameeter

Parameeter ConnectionType määrab, kas ühendada kogu Dataverse'i keskkonnaga või konkreetse lahendusega.

Väärtus Silt Kirjeldus
0 Lahendus Ühendab konkreetse Dataverse'i lahenduse Gitiga.
1 Keskkond Ühendab kogu Dataverse'i keskkonna Gitiga.

GitProvider parameeter

Kasuta parameetrit GitProvider , et määrata, millist Git-teenuse pakkujat kasutad, kas Azure DevOps või GitHub.

Väärtus Silt Kirjeldus
0 Azure DevOps Kasuta Azure DevOps majutatavate hoidlate jaoks
1 GitHub Kasutus GitHubis majutatud repositooriumitele

DisconnectFromGit API

Eemaldab Git-ühenduse Dataverse'i lahendusest või keskkonnast ning keelab lähtekoodihalduse integratsiooni.

Parameeter

API-l DisconnectFromGit on ainult üks parameeter.

Parameeter Tüüp Nõutav Kirjeldus
SolutionUniqueName String Nr Lahenduse unikaalne nimi, mida soovid Gitist lahti ühendada. Ära katkesta kõigi lahenduste või keskkonna katkestamist.

Lisateave

Siin on mõned parameetri väärtuse valikud, mida määrata kutsumisel DisconnectFromGit.

  • Ühenda lahti üks lahendus: Paku SolutionUniqueName konkreetse lahenduse lahtiühendamist.
  • Katkesta kõik lahendused: Ära anna parameetreid kõigi lahendustaseme ühenduste lahtiühendamiseks.
  • Ühenduse katkestamise keskkond: Ei paku parameetreid keskkonnataseme ühenduse katkestamiseks.

Näited

Järgmistes näidetes kirjeldatakse API-de kasutamise DisconnectFromGit stsenaariumeConnectToGit.

Ühenda kogu oma Dataverse'i keskkond Azure DevOps repositooriumiga

See ühendus võimaldab lähtekoodihaldust kõigi keskkonnataseme konfiguratsioonide ja komponentide jaoks.

Ära kasuta neid parameetreid selle seosega:

  • RootFolder
  • SolutionUniqueName
  • UpstreamBranch

See näide näitab, kuidas kasutada ConnectToGit tegevust , et ühendada kogu oma Dataverse'i keskkond Azure DevOps hoidlaga.

Taotlus

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

Vastus

HTTP/1.1 204 No Content
OData-Version: 4.0

Õpi, kuidas käivitada Web API toiminguid

ühenduse loomine GitHub hoidlaga

Enne kui kasutate API-t GitHub ühenduse loomiseks, täitke GitHub rakenduse loomiseks häälestustoimingud, installige see sihthoidlasse, importige privaatvõti Azure Key Vault ja looge Power Platformi GitHub ühendus. Lisateavet leiate teemast Ühenduse loomine GitHub.

GitHub rakenduse konfiguratsioonikirje loomine veebi-API abil

Kirje loomiseks kasutage Dataverse OData veebi API-t githubappconfig . Saatke POST-taotlus GitHub rakenduse kliendi ID, Key Vault URI ja võtme nimega.

Nende kõnede tegemiseks saate kasutada mis tahes HTTP-klienti (nt Insomnia, Visual Studio Code REST Client või curl). Autentimiseks vajate kandjatõendi. Lisateavet leiate teemast Microsoft Dataverse veebi API kasutamine.

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

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

Oluline

Pange tähele, et vastuse päises tagastatud kirje ID. Seda väärtust on vaja hallatava identiteedi tuvastamiseks, RBAC-i konfigureerimiseks ja helistamiseks ConnectToGit. Kirje ID kasutab sellist vormingut nagu 13d565bb-4c22-f111-a546-7ced8d6e3e85.

Pärast GitHub rakenduse konfiguratsioonikirje loomist määrake Key Vault Crypto User roll Dataverse'i hallatavale identiteedile, nagu on kirjeldatud artiklis Key Vault rollipõhise juurdepääsu reguleerimise konfigureerimine (RBAC).

ConnectToGiti API kutsumine

Pärast kirje loomist githubappconfig ja Key Vault RBAC-i konfigureerimist kasutage toimingu kutsumisega ConnectToGit lähtekontrolli ühenduse loomiseks Dataverse Web API-t.

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

Oluline

Haru peab hoidlas juba olemas olema. Vajaduse korral looge see esmalt GitHub. Väärtus GitHubAppConfigId peab kasutama vormingut githubappconfigs(<recordId>).

Screenshot of an HTTP request body for the ConnectToGit API with GitHub parameters.

Kui saate vastuse, on keskkond ühendatud GitHub.

GitHub hoidlaga ühenduse loomine PowerShelli abil

Järgmises PowerShelli näites luuakse GitHub rakenduse konfiguratsioonikirje, oodatakse Andmeverse'i hallatava identiteedi kuvamist Microsoft Entra ID, määratakse hallatavale identiteedile Key Vault krüptokasutaja roll ja kutsutakse ConnectToGit toiming. Kui teil on juba GitHub rakenduse konfiguratsioonikirje, jätke GitHubAppConfigId konfigureerimine vahele ja Key Vault rollimääramise juhised.

Installige ja importige Az.Accountsmoodulid , Az.KeyVaultja Az.Resources PowerShell enne näite käivitamist. Logige sisse kontogaConnect-AzAccount, millel on juurdepääs Dataverse'i keskkonnale ja õigus määrata Key Vault rolle.

Kui Dataverse'i keskkonnas on lubatud virtuaalvõrgu (VNET) tugi, andke .GitHubPAT GitHub ühendusi ei saa kasutada virtuaalvõrgu toega.

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

Katkesta kogu oma Dataverse'i keskkond Git lähtekoodihaldusest

See tegevus eemaldab keskkonnataseme Git-ühenduse. Ära kasuta seda SolutionUniqueName parameetrit selle operatsiooni jaoks. Dataverse tuvastab ja eemaldab automaatselt keskkonnataseme Git-ühenduse.

See näide näitab, kuidas kasutada DisconnectFromGit tegevust , et katkestada kogu oma Dataverse'i keskkond Git lähtekoodihaldusest.

Taotlus

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

Vastus

HTTP/1.1 204 No Content
OData-Version: 4.0

Õpi, kuidas käivitada Web API toiminguid

Ühenda esimene lahendus Git-repositooriumiga

See ühendus loob hoidla lingi ja kaustastruktuuri lahendustaseme lähtekoodihalduse jaoks esimese lahenduseni keskkonnas.

Lahenduse määramiseks tuleb lisada nende parameetrite väärtused:

  • RootFolder
  • SolutionUniqueName

See näide näitab, kuidas kasutada ConnectToGit tegevust , et ühendada esimene lahendus Giti hoidlaga.

Taotlus

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

Vastus

HTTP/1.1 204 No Content
OData-Version: 4.0

Õpi, kuidas käivitada Web API toiminguid

Ühenda lisalahendused samasse Giti hoidla pärast esialgse lahenduse ühendamist

Pärast esimese lahenduse ühendamist on vaja ainult lahendusspetsiifilisi parameetreid. Sa pärid hoidla ühenduse andmed algsest ühendusest.

Sea ainult need parameetrid:

  • SolutionUniqueName
  • Branch
  • GitFolder

Oluline

Enne kui see töötab, pead esmalt ühendama esimese lahenduse. Vaata Ühenda esimene lahendus Giti hoidlaga.

See näide näitab, kuidas kasutada ConnectToGit tegevust , et ühendada järgmised lahendused Git-hoidlaga.

Taotlus

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

Vastus

HTTP/1.1 204 No Content
OData-Version: 4.0

Õpi, kuidas käivitada Web API toiminguid

Ühenda konkreetne lahendus Giti lähtehaldusest, hoides samal ajal teisi lahendusi ühendatuna

Kasuta seda lähenemist, et eemaldada ühe lahenduse lähtekoodikontroll ilma teisi mõjutamata.

See näide näitab, kuidas kasutada DisconnectFromGit tegevust , et eemaldada ühe lahenduse lähtekood ilma teisi mõjutamata.

Taotlus

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

Vastus

HTTP/1.1 204 No Content
OData-Version: 4.0

Õpi, kuidas käivitada Web API toiminguid

Tõrketöötlus

Ei API ConnectToGit ega DisconnectFromGit API tagasta väärtust, kui see edukalt lõpetatakse. Kui API ebaõnnestub, tagastab see vea.

Levinumad vea stsenaariumid on:

  • Kehtetud mandaadiandmed: Veendu, et sul on Giti teenusepakkujale kehtiv autentimine.
  • Hoidla ei leitud: Kontrolli organisatsiooni, projekti ja hoidla nimed.
  • Luba keelatud: Veenduge, et teie Dataverse'i kontol on lähtekoodihalduse õigused.
  • Lahendus ei leitud: Kontrolli, et need SolutionUniqueName eksisteerivad sinu keskkonnas.
  • Haru ei eksisteeri: Kinnita, et määratud haru eksisteerib hoidlas.

Toetus ja täiendavad ressursid

Lisateabe saamiseks lähtekoodihalduse integratsiooni kohta Dataverse'iga vaata:

  • Last updated on