Nota
O acceso a esta páxina require autorización. Pode tentar iniciar sesión ou modificar os directorios.
O acceso a esta páxina require autorización. Pode tentar modificar os directorios.
Usa as ConnectToGit APIs e DisconnectFromGit para integrar programáticamente o teu entorno Microsoft Dataverse co control de versións de Git. Ao usar estas APIs, podes conectar solucións individuais ou contornos enteiros a repositorios Git soportados e xestionar esas conexións mediante código.
Requisitos previos
Antes de usar estas APIs, asegúrate de ter:
- Acceso a un entorno Microsoft Dataverse
- Permisos de administrador do sistema
- Acceso de lectura e escritura a un repositorio Git
ConnectToGit API
Crea unha conexión entre unha solución ou entorno Dataverse e un repositorio Git. Usando esta conexión, podes xestionar o control de versións dos teus compoñentes de Dataverse.
Parámetros
A ConnectToGit API acepta os seguintes parámetros:
| Parámetro | Tipo | Necesario | Descripción |
|---|---|---|---|
GitFolder |
String | Si | Nome da carpeta á que queres vincular a túa solución ou ambiente. |
Branch |
String | Si | Nome da sucursal á que queres conectar. |
ConnectionType |
Enteiro | Non | Especifica a que conectar. Ver parámetro ConnectionType. |
GitProvider |
Enteiro | Non | O provedor Git. Ver parámetro GitProvider. |
Organization |
String | Non | Nome da organización coa que queres conectarte. |
Project |
String | Non | Nome do proxecto ao que queres conectar. |
Repository |
String | Non | Nome do repositorio ao que queres conectarte. |
RootFolder |
String | Non | Nome da carpeta raíz onde residen todas as túas solucións no ámbito da solución. |
SolutionUniqueName |
String | Non | O nome único da solución que queres conectar con git. |
UpstreamBranch |
String | Non | Nome da ramificación río arriba á que queres conectar. Por defecto a rama predeterminada do repositorio. |
GitHubConnectionId |
String | Non | ID de conexión para a conexión Power Platform GitHub. É obrigatorio cando GitProvider é 1 a menos que proporciones GitHubPAT. Non se pode usar cando o soporte para rede virtual (VNET) está activado para o entorno Dataverse. |
GitHubPAT |
String | Non | Token de acceso persoal de GitHub con acceso ao repositorio obxectivo. É obrigatorio cando GitProvider é 1 a menos que proporciones GitHubConnectionId. É necesario cando se habilita o soporte para redes virtuais (VNET) no entorno Dataverse. |
GitHubAppConfigId |
String | Non | Referencia ao rexistro de configuración da aplicación GitHub. Requirido cando GitProvider é 1. Usa o formato githubappconfigs(<recordId>). |
Parámetro ConnectionType
O ConnectionType parámetro controla se conectar a todo o entorno Dataverse ou a unha solución específica.
| Valor | Etiqueta | Descripción |
|---|---|---|
| 0 | Solución | Conecta unha solución específica de Dataverse con Git. |
| 1 | Ambiente | Conecta todo o entorno Dataverse con Git. |
Parámetro GitProvider
Usa o GitProvider parámetro para especificar o tipo de provedor Git que estás a usar, xa sexa Azure DevOps ou GitHub.
| Valor | Etiqueta | Descripción |
|---|---|---|
| 0 | Azure DevOps | Use para repositorios aloxados en Azure DevOps |
| 1 | GitHub | Uso para repositorios aloxados en GitHub |
DisconnectFromGit API
Elimina a conexión Git dunha solución ou entorno Dataverse e desactiva a integración do control de versión.
Parámetro
A DisconnectFromGit API só ten un parámetro.
| Parámetro | Tipo | Necesario | Descripción |
|---|---|---|---|
SolutionUniqueName |
String | Non | O nome único da solución que queres desconectar de Git. Evita desconectar todas as solucións ou o medio ambiente. |
Información adicional
Aquí tes algunhas opcións de valor de parámetro para especificar ao invocar DisconnectFromGit.
-
Desconectar unha solución única: Proporcionar
SolutionUniqueNamepara desconectar unha solución específica. - Desconecte todas as solucións: Non proporcione parámetros para desconectar todas as conexións a nivel de solución.
- Desconectar o ambiente: Non proporcionar parámetros para desconectar a conexión a nivel de ambiente.
Exemplos
Os seguintes exemplos describen escenarios para o uso das ConnectToGit APIs de e DisconnectFromGit :
- Conecta todo o teu entorno Dataverse a un repositorio Azure DevOps
- Conéctate a un repositorio de GitHub
- Conéctate a un repositorio de GitHub usando PowerShell
- Desconecta todo o teu entorno Dataverse do control de versións de Git
- Conecta a primeira solución a un repositorio Git
- Conecta solucións extra ao mesmo repositorio Git despois de conectar a solución inicial
- Desconecta unha solución específica do control de código Git mantendo outras solucións conectadas
Conecta todo o teu entorno Dataverse a un repositorio Azure DevOps
Esta conexión permite o control de versións para todas as configuracións e compoñentes a nivel de ambiente.
Non uses estes parámetros con esta conexión:
RootFolderSolutionUniqueNameUpstreamBranch
Este exemplo mostra como usar a acción ConnectToGit para conectar todo o teu entorno Dataverse a un repositorio Azure DevOps.
Solicitude
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
Conéctate a un repositorio de GitHub
Antes de usar a API para conectarte a GitHub, completa os pasos de configuración para crear a aplicación GitHub, instálaa no repositorio destino, importa a súa clave privada en Azure Key Vault e crea a conexión Power Platform GitHub. Para máis información, véxase Conectar a GitHub.
Crea un rexistro de configuración de GitHub App usando a API web
Usa a API web de Dataverse OData para crear un githubappconfig rexistro. Envía unha solicitude POST co ID do cliente da aplicación GitHub, o URI de Key Vault e o nome da clave.
Podes usar calquera cliente HTTP, como Insomnia, Visual Studio Code REST Client ou curl, para facer estas chamadas. Necesitas un token portador para autenticación. Para máis información, véxase Usar a 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"
}
Importante
Nota o ID do rexistro devolto na cabeceira de resposta. Necesitas este valor para identificar a identidade xestionada, configurar RBAC e chamar ConnectToGita . O ID do rexistro usa un formato como 13d565bb-4c22-f111-a546-7ced8d6e3e85.
Despois de crear o rexistro de configuración da aplicación GitHub, asigna o rol de usuario Key Vault Crypto á identidade xestionada de Dataverse tal e como se describe no control de acceso baseado en roles (RBAC) de Configure Key Vault.
Chama á API de ConnectToGit
Despois de crear o githubappconfig rexistro e configurar Key Vault RBAC, usa a API web de Dataverse para establecer a conexión de control de versións chamando á ConnectToGit acció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>)"
}
Importante
A rama debe existir xa no repositorio. Créao primeiro en GitHub se é necesario. O GitHubAppConfigId valor debe usar o formato githubappconfigs(<recordId>).
Se recibes unha resposta exitosa, o entorno conéctase a GitHub.
Conéctate a un repositorio de GitHub usando PowerShell
O seguinte exemplo de PowerShell crea o rexistro de configuración da aplicación GitHub, espera a que apareza a identidade xestionada Dataverse no Microsoft Entra ID, asigna o rol de usuario Key Vault Crypto á identidade xestionada e chama á ConnectToGit acción. Se xa tes un rexistro de configuración de GitHub App, proporciona GitHubAppConfigId para saltar os pasos de configuración e asignación de roles de Key Vault.
Instala e importa os módulos Az.Accounts, Az.KeyVault, e Az.Resources PowerShell antes de executar o exemplo. Inicia Connect-AzAccount sesión usando unha conta que teña acceso ao entorno Dataverse e permiso para asignar roles de Key Vault.
Se o soporte para rede virtual (VNET) está habilitado para o entorno Dataverse, proporciona GitHubPAT. As conexións de GitHub non se poden usar con soporte para redes virtuais.
[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."
Desconecta todo o teu entorno Dataverse do control de versións de Git
Esta acción elimina a conexión Git a nivel de ambiente. Non uses o SolutionUniqueName parámetro para esta operación. Dataverse identifica e elimina automaticamente a conexión Git a nivel de ambiente.
Este exemplo mostra como usar a acción DisconnectFromGit para desconectar todo o teu entorno Dataverse do control de versións de Git.
Solicitude
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
Conecta a primeira solución a un repositorio Git
Esta conexión establece a estrutura de ligazóns e carpetas do repositorio para o control de versión a nivel de solución para a primeira solución nun entorno.
Necesitas incluír valores para estes parámetros para especificar a solución:
RootFolderSolutionUniqueName
Este exemplo mostra como usar a acción ConnectToGit para conectar a primeira solución a un repositorio Git.
Solicitude
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
Conecta solucións extra ao mesmo repositorio Git despois de conectar a solución inicial
Despois de conectar a primeira solución, só necesitas os parámetros específicos da solución. Herdas os detalles da conexión do repositorio desde a conexión inicial.
Establece só estes parámetros:
SolutionUniqueNameBranchGitFolder
Importante
Primeiro debes conectar a primeira solución antes de que isto funcione. Ver Conectar a primeira solución a un repositorio Git.
Este exemplo mostra como usar a acción ConnectToGit para conectar solucións posteriores a un repositorio Git.
Solicitude
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
Desconecta unha solución específica do control de código Git mantendo outras solucións conectadas
Usa este enfoque para eliminar o control de versións dunha solución sen afectar ás outras.
Este exemplo mostra como usar a acción DisconnectFromGit para eliminar o control de versións dunha solución sen afectar a outras.
Solicitude
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
Manexo de erros
Nin a ConnectToGit API DisconnectFromGit nin a API devolven valor cando se completa con éxito. Cando unha API falla, devolve un erro.
Os escenarios de erro máis comúns inclúen:
- Credenciais inválidas: Asegúrate de ter unha autenticación válida co provedor Git.
- Repositorio non atopado: Verifica os nomes da organización, proxecto e repositorio.
- Permiso denegado: Asegúrate de que a túa conta de Dataverse teña permisos de xestión de control de versión.
-
Solución non atopada: Verifica que
SolutionUniqueNameexiste no teu entorno. - A rama non existe: Confirme que a rama especificada existe no repositorio.
Apoio e recursos adicionais
Para máis información sobre a integración do control de versións con Dataverse, véxase: