Nota
L'accés a aquesta pàgina requereix autorització. Podeu provar d'iniciar la sessió o de canviar els directoris.
L'accés a aquesta pàgina requereix autorització. Podeu provar de canviar els directoris.
Utilitza les ConnectToGit API de AND DisconnectFromGit per integrar programàticament el teu entorn Microsoft Dataverse amb el control de versions de Git. Utilitzant aquestes APIs, pots connectar solucions individuals o entorns sencers a repositoris Git compatibles i gestionar aquestes connexions mitjançant codi.
Requisits previs
Abans d'utilitzar aquestes APIs, assegura't que tens:
- Accés a un entorn Microsoft Dataverse
- Permisos d'administrador del sistema
- Accés de lectura i escriptura a un repositori Git
ConnectToGit API
Crea una connexió entre una solució o entorn Dataverse i un repositori Git. Utilitzant aquesta connexió, pots gestionar el control de versions dels teus components de Dataverse.
Paràmetres
L'API ConnectToGit accepta els següents paràmetres:
| Paràmetre | Tipus | Necessari | Descripció |
|---|---|---|---|
GitFolder |
String | Sí | Nom de la carpeta a la qual vols vincular la teva solució o entorn. |
Branch |
String | Sí | Nom de la sucursal a la qual vols connectar-te. |
ConnectionType |
Enter | No | Especifica a què s'ha de connectar. Vegeu el paràmetre ConnectionType. |
GitProvider |
Enter | No | El proveïdor Git. Vegeu el paràmetre GitProvider. |
Organization |
String | No | Nom de l'organització amb la qual vols connectar-te. |
Project |
String | No | Nom del projecte al qual vols connectar. |
Repository |
String | No | Nom del repositori al qual vols connectar-te. |
RootFolder |
String | No | Nom de la carpeta arrel on resideixen totes les teves solucions dins l'abast de la solució. |
SolutionUniqueName |
String | No | El nom únic de la solució que vols connectar a git. |
UpstreamBranch |
String | No | Nom de la branca amunt a la qual vols connectar-te. Per defecte la branca predeterminada del repositori. |
GitHubConnectionId |
String | No | ID de connexió per a la connexió GitHub de Power Platform. És obligatori quan GitProvider és 1 tret que proporcionis GitHubPAT. No es pot utilitzar quan el suport de xarxa virtual (VNET) està activat per a l'entorn Dataverse. |
GitHubPAT |
String | No | Token d'accés personal de GitHub amb accés al repositori de destinació. És obligatori quan GitProvider és 1 tret que proporcionis GitHubConnectionId. És necessari quan el suport de xarxa virtual (VNET) està activat per a l'entorn Dataverse. |
GitHubAppConfigId |
String | No | Referència al registre de configuració de l'aplicació de GitHub. És necessari quan GitProvider és 1. Utilitza el format githubappconfigs(<recordId>). |
Paràmetre ConnectionType
El ConnectionType paràmetre controla si s'ha de connectar a tot l'entorn Dataverse o a una solució específica.
| Valor | Etiqueta | Descripció |
|---|---|---|
| 0 | Solució | Connecta una solució específica de Dataverse amb Git. |
| 1 | Entorn | Connecta tot l'entorn Dataverse a Git. |
Paràmetre GitProvider
Utilitza el GitProvider paràmetre per especificar el tipus de proveïdor Git que utilitzes, ja sigui Azure DevOps o GitHub.
| Valor | Etiqueta | Descripció |
|---|---|---|
| 0 | Azure DevOps | Ús per a repositoris allotjats a Azure DevOps |
| 1 | GitHub | Ús per a repositoris allotjats a GitHub |
DisconnectFromGit API
Elimina la connexió Git d'una solució o entorn Dataverse, i desactiva la integració amb control de versions.
Paràmetre
L'API DisconnectFromGit només té un paràmetre.
| Paràmetre | Tipus | Necessari | Descripció |
|---|---|---|---|
SolutionUniqueName |
String | No | El nom únic de la solució que vols desconnectar de Git. Evita desconnectar totes les solucions o l'entorn. |
Informació addicional
Aquí tens algunes opcions de valor de paràmetre per especificar quan s'invoca DisconnectFromGit.
-
Desconnectar una solució única: Proporcionar
SolutionUniqueNameper desconnectar una solució específica. - Desconnectar totes les solucions: No proporcionar cap paràmetre per desconnectar totes les connexions a nivell de solució.
- Desconnectar l'entorn: No proporcionar paràmetres per desconnectar la connexió a nivell d'entorn.
Exemples
Els exemples següents descriuen escenaris per utilitzar les ConnectToGit API de i (i DisconnectFromGit aquests):
- Connecta tot el teu entorn Dataverse a un repositori Azure DevOps
- Connecta't a un repositori de GitHub
- Connecta't a un repositori de GitHub utilitzant PowerShell
- Desconnecta tot l'entorn Dataverse del control de versions de Git
- Connecta la primera solució a un repositori Git
- Connecta solucions addicionals al mateix repositori Git després de connectar la solució inicial
- Desconnecta una solució específica del control de versions de Git mentre mantens les altres solucions connectades
Connecta tot el teu entorn Dataverse a un repositori Azure DevOps
Aquesta connexió permet el control de versions per a totes les configuracions i components a nivell d'entorn.
No utilitzis aquests paràmetres amb aquesta connexió:
RootFolderSolutionUniqueNameUpstreamBranch
Aquest exemple mostra com utilitzar l'acció ConnectToGit per connectar tot el teu entorn Dataverse a un repositori Azure DevOps.
Demanar
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"
}
Resposta
HTTP/1.1 204 No Content
OData-Version: 4.0
Connecta't a un repositori de GitHub
Abans d'utilitzar l'API per connectar-te a GitHub, completa els passos de configuració per crear l'aplicació GitHub, instal·la-la al repositori objectiu, importa la seva clau privada a Azure Key Vault i crea la connexió Power Platform GitHub. Per a més informació, vegeu Connect to GitHub.
Crea un registre de configuració de l'aplicació GitHub utilitzant l'API web
Utilitza l'API web Dataverse OData per crear un githubappconfig registre. Envia una sol·licitud POST amb l'ID del client de l'aplicació GitHub, l'URI de Key Vault i el nom de la clau.
Pots utilitzar qualsevol client HTTP, com Insomnia, Visual Studio Code REST Client o curl, per fer aquestes trucades. Necessites un testimoni portador per a l'autenticació. Per a més informació, vegeu Utilitza l'API web de Microsoft Dataverse.
POST {{DataverseOrgUrl}}/api/data/v9.2/githubappconfigs
Authorization: Bearer {{token}}
Content-Type: application/json
{
"githubappid": "Iv23liBWoH9sf7xDrRe6",
"keyvaulturi": "{{KeyVaultUri}}",
"keyname": "demoGitHubKey"
}
Important
Fixeu-vos en l'ID de registre retornat a la capçalera de resposta. Necessites aquest valor per identificar la identitat gestionada, configurar RBAC i cridar ConnectToGit. L'ID de registre utilitza un format com 13d565bb-4c22-f111-a546-7ced8d6e3e85.
Després de crear el registre de configuració de l'aplicació GitHub, assigna el rol d'usuari Key Vault Crypto a la identitat gestionada de Dataverse, tal com es descriu a Configure Key Vault basat en el control d'accés basat en rols (RBAC).
Truca a l'API de ConnectToGit
Després de crear el githubappconfig registre i configurar Key Vault RBAC, utilitza l'API web de Dataverse per establir la connexió de control de versions cridant l'accióConnectToGit.
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
La branca ja ha d'existir al repositori. Crea'l primer a GitHub si cal. El GitHubAppConfigId valor ha d'utilitzar el format githubappconfigs(<recordId>).
Si reps una resposta exitosa, l'entorn està connectat a GitHub.
Connecta't a un repositori de GitHub utilitzant PowerShell
L'exemple següent de PowerShell crea el registre de configuració de l'aplicació GitHub, espera que aparegui la identitat gestionada de Dataverse a Microsoft Entra ID, assigna el rol d'usuari Key Vault Crypto a la identitat gestionada i crida l'accióConnectToGit. Si ja tens un registre de configuració de l'aplicació de GitHub, proporciona GitHubAppConfigId per saltar els passos de configuració i assignació de rols de Key Vault.
Instal·la i importa els Az.Accountsmòduls , Az.KeyVault, i Az.Resources PowerShell abans d'executar l'exemple. Inicia sessió utilitzant Connect-AzAccount un compte que tingui accés a l'entorn Dataverse i permís per assignar rols a Key Vault.
Si el suport per a xarxes virtuals (VNET) està activat per a l'entorn Dataverse, proporciona GitHubPAT. Les connexions a GitHub no es poden utilitzar amb suport de xarxa virtual.
[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."
Desconnecta tot l'entorn Dataverse del control de versions de Git
Aquesta acció elimina la connexió Git a nivell d'entorn. No utilitzis el SolutionUniqueName paràmetre per a aquesta operació. Dataverse identifica i elimina automàticament la connexió Git a nivell d'entorn.
Aquest exemple mostra com utilitzar l'acció DisconnectFromGit per desconnectar tot l'entorn Dataverse del control de versions de Git.
Demanar
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
Resposta
HTTP/1.1 204 No Content
OData-Version: 4.0
Connecta la primera solució a un repositori Git
Aquesta connexió estableix l'enllaç del repositori i l'estructura de carpetes per al control de versions a nivell de solució per a la primera solució en un entorn.
Cal incloure valors per a aquests paràmetres per especificar la solució:
RootFolderSolutionUniqueName
Aquest exemple mostra com utilitzar l'acció ConnectToGit per connectar la primera solució a un repositori Git.
Demanar
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"
}
Resposta
HTTP/1.1 204 No Content
OData-Version: 4.0
Connecta solucions addicionals al mateix repositori Git després de connectar la solució inicial
Després de connectar la primera solució, només necessites els paràmetres específics de la solució. S'hereten els detalls de la connexió del repositori de la connexió inicial.
Fixa només aquests paràmetres:
SolutionUniqueNameBranchGitFolder
Important
Primer has de connectar la primera solució abans que això funcioni. Vegeu Connecta la primera solució a un repositori Git.
Aquest exemple mostra com utilitzar l'acció ConnectToGit per connectar solucions posteriors a un repositori Git.
Demanar
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"
}
Resposta
HTTP/1.1 204 No Content
OData-Version: 4.0
Desconnecta una solució específica del control de versions de Git mentre mantens les altres solucions connectades
Utilitza aquest enfocament per eliminar el control de versions d'una solució sense afectar les altres.
Aquest exemple mostra com utilitzar l'acció DisconnectFromGit per eliminar el control de versions d'una solució sense afectar les altres.
Demanar
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"
}
Resposta
HTTP/1.1 204 No Content
OData-Version: 4.0
Gestió d'errors
Ni l'API ConnectToGit ni l'API DisconnectFromGit retornen un valor quan es completa amb èxit. Quan una API falla, retorna un error.
Els escenaris d'error més comuns inclouen:
- Credencials invàlides: Assegura't de tenir una autenticació vàlida amb el proveïdor Git.
- Repositori no trobat: Verifica els noms de l'organització, projecte i repositori.
- Permís denegat: Assegura't que el teu compte de Dataverse tingui permisos de gestió de control de versions.
-
Solució no trobada: Verifica que existeixi
SolutionUniqueNameal teu entorn. - La branca no existeix: Confirma que la branca especificada existeix al repositori.
Suport i recursos addicionals
Per a més informació sobre la integració del control de versions amb Dataverse, vegeu: