Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Use las ConnectToGit API y DisconnectFromGit para integrar mediante programación el entorno de Microsoft Dataverse con el control de código fuente de Git. Mediante estas API, puede conectar soluciones individuales o entornos completos a repositorios de Git compatibles y administrar esas conexiones a través del código.
Prerrequisitos
Antes de usar estas API, asegúrese de que tiene:
- Acceso a un entorno de Microsoft Dataverse
- Permisos de administrador del sistema
- Acceso de lectura y escritura a un repositorio de Git
ConnectToGit API
Crea una conexión entre una solución o un entorno de Dataverse y un repositorio de Git. Mediante esta conexión, puede administrar el control de código fuente para los componentes de Dataverse.
Parámetros
La ConnectToGit API acepta los parámetros siguientes:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
GitFolder |
Cuerda | Sí | Nombre de la carpeta a la que desea enlazar la solución o el entorno. |
Branch |
Cuerda | Sí | Nombre de la rama a la que desea conectarse. |
ConnectionType |
Entero | No | Especifica a qué conectarse. Consulte Parámetro ConnectionType. |
GitProvider |
Entero | No | Proveedor de Git. Consulte el parámetro GitProvider. |
Organization |
Cuerda | No | Nombre de la organización a la que desea conectarse. |
Project |
Cuerda | No | Nombre del proyecto al que desea conectarse. |
Repository |
Cuerda | No | Nombre del repositorio al que desea conectarse. |
RootFolder |
Cuerda | No | Nombre de la carpeta raíz donde residen todas las soluciones en el ámbito de la solución. |
SolutionUniqueName |
Cuerda | No | Nombre único de la solución que desea conectar a Git. |
UpstreamBranch |
Cuerda | No | Nombre de la rama ascendente a la que desea conectarse. El valor por defecto es la rama predeterminada del repositorio. |
GitHubConnectionId |
Cuerda | No | Identificador de conexión para la conexión GitHub de Power Platform. Obligatorio cuando GitProvider es 1 a menos que proporcione GitHubPAT. No se puede usar cuando la compatibilidad con la red virtual (VNET) está habilitada para el entorno de Dataverse. |
GitHubPAT |
Cuerda | No | token de acceso personal de GitHub con acceso al repositorio de destino. Obligatorio cuando GitProvider es 1 a menos que proporcione GitHubConnectionId. Se requiere cuando la compatibilidad con la red virtual (VNET) está habilitada para el entorno de Dataverse. |
GitHubAppConfigId |
Cuerda | No | Referencia al registro de configuración de la aplicación de GitHub. Obligatorio cuando GitProvider es 1. Use el formato githubappconfigs(<recordId>). |
Parámetro de ConnectionType
El ConnectionType parámetro controla si se va a conectar a todo el entorno de Dataverse o a una solución específica.
| Value | Etiqueta | Descripción |
|---|---|---|
| 0 | Solución | Conecta una solución específica de Dataverse a Git. |
| 1 | Ambiente | Conecta todo el entorno de Dataverse a Git. |
Parámetro GitProvider
Use el GitProvider parámetro para especificar el tipo de proveedor de Git que usa, ya sea Azure DevOps o GitHub.
| Value | Etiqueta | Descripción |
|---|---|---|
| 0 | Azure DevOps | Uso de repositorios hospedados en Azure DevOps |
| 1 | GitHub | Uso para repositorios hospedados en GitHub |
DesconectarDeGit API
Quita la conexión de Git de una solución o entorno de Dataverse y deshabilita la integración del control de código fuente.
Parámetro
La DisconnectFromGit API solo tiene un parámetro.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
SolutionUniqueName |
Cuerda | No | Nombre único de la solución que desea desconectar de Git. Omita para desconectar todas las soluciones o el entorno. |
Información adicional
Estas son algunas opciones de valor de parámetro que se deben especificar al invocar DisconnectFromGit.
-
Desconectar solución única: proporcione
SolutionUniqueNamepara desconectar una solución específica. - Desconectar todas las soluciones: no proporcione ningún parámetro para desconectar todas las conexiones de nivel de solución.
- Desconectar entorno: No proporcione ningún parámetro para desconectar la conexión a nivel de entorno.
Examples
En los ejemplos siguientes se describen escenarios para usar las ConnectToGit API y DisconnectFromGit :
- Conexión de todo el entorno de Dataverse a un repositorio de Azure DevOps
- Conexión a un repositorio de GitHub
- Conexión a un repositorio de GitHub mediante PowerShell
- Desconecte todo el entorno de Dataverse del control de código fuente de Git.
- Conexión de la primera solución a un repositorio de Git
- Conexión de soluciones adicionales al mismo repositorio de Git después de conectar la solución inicial
- Desconecte una solución específica del control de código fuente de Git mientras mantiene conectadas otras soluciones
Conexión de todo el entorno de Dataverse a un repositorio de Azure DevOps
Esta conexión habilita el control de código fuente para todas las configuraciones y componentes de nivel de entorno.
No use estos parámetros con esta conexión:
RootFolderSolutionUniqueNameUpstreamBranch
En este ejemplo se muestra cómo usar la acción ConnectToGit para conectar todo el entorno de Dataverse a un repositorio de Azure DevOps.
Solicitud
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"
}
Respuesta
HTTP/1.1 204 No Content
OData-Version: 4.0
Conexión a un repositorio de GitHub
Antes de usar la API para conectarse a GitHub, complete los pasos de configuración para crear la aplicación GitHub, instalarla en el repositorio de destino, importar su clave privada en Azure Key Vault y crear la conexión de Power Platform GitHub. Para obtener más información, consulte Conexión a GitHub.
Creación de un registro de configuración de aplicación GitHub mediante la API web
Use la API web de OData de Dataverse para crear un githubappconfig registro. Envíe una solicitud POST con el identificador de cliente de la aplicación de GitHub, Key Vault URI y el nombre de clave.
Puede usar cualquier cliente HTTP, como Insomnio, Visual Studio Code cliente REST o curl, para realizar estas llamadas. Necesita un token de portador para la autenticación. Para obtener más información, consulte Uso de la 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
Anote el identificador de registro devuelto en el encabezado de respuesta. Necesita este valor para identificar la identidad administrada, configurar RBAC y llamar a ConnectToGit. El identificador de registro usa un formato como 13d565bb-4c22-f111-a546-7ced8d6e3e85.
Después de crear el registro de configuración de la aplicación de GitHub, asigne el rol Usuario de cifrado de Key Vault a la identidad administrada de Dataverse, tal como se describe en Configurar el control de acceso basado en rol (RBAC) de Key Vault.
Llamar a la API ConnectToGit
Después de crear el registro githubappconfig y configurar Key Vault RBAC, use la API web de Dataverse para establecer la conexión al control de código fuente llamando a la acción 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>)"
}
Importante
La rama ya debe existir en el repositorio. Créelo en GitHub primero si es necesario. El GitHubAppConfigId valor debe usar el formato githubappconfigs(<recordId>).
Si recibe una respuesta correcta, el entorno se conecta a GitHub.
Conexión a un repositorio de GitHub mediante PowerShell
En el siguiente ejemplo de PowerShell se crea el registro de configuración de la aplicación de GitHub, se espera a que la identidad administrada de Dataverse aparezca en Microsoft Entra ID, se asigna el rol Usuario de criptografía de Key Vault a la identidad administrada y se invoca la acción ConnectToGit. Si ya tiene un registro de configuración de GitHub App, proporcione GitHubAppConfigId para omitir los pasos de configuración y asignación de roles de Key Vault.
Instale e importe los módulos de PowerShell Az.Accounts, Az.KeyVault y Az.Resources antes de ejecutar el ejemplo. Inicie sesión con Connect-AzAccount con una cuenta que tenga acceso al entorno de Dataverse y permisos para asignar roles de Key Vault.
Si la compatibilidad con la red virtual (VNET) está habilitada para el entorno de Dataverse, proporcione GitHubPAT. Las conexiones de GitHub no se pueden usar con compatibilidad con redes virtuales.
[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."
Desconecte todo el entorno de Dataverse del control de código fuente de Git.
Esta acción elimina la conexión de Git a nivel de entorno. No use el SolutionUniqueName parámetro para esta operación. Dataverse identifica y elimina automáticamente la conexión Git a nivel de entorno.
En este ejemplo se muestra cómo usar la acción DisconnectFromGit para desconectar todo el entorno de Dataverse del control de código fuente de Git.
Solicitud
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
Respuesta
HTTP/1.1 204 No Content
OData-Version: 4.0
Conexión de la primera solución a un repositorio de Git
Esta conexión establece el vínculo del repositorio y la estructura de carpetas para el control de código fuente a nivel de solución en la primera solución de un entorno.
Debe incluir valores para estos parámetros para especificar la solución:
RootFolderSolutionUniqueName
En este ejemplo se muestra cómo usar la acción ConnectToGit para conectar la primera solución a un repositorio de Git.
Solicitud
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"
}
Respuesta
HTTP/1.1 204 No Content
OData-Version: 4.0
Conexión de soluciones adicionales al mismo repositorio de Git después de conectar la solución inicial
Después de conectar la primera solución, solo necesita los parámetros específicos de la solución. Hereda los detalles de conexión al repositorio de la conexión inicial.
Establezca solo estos parámetros:
SolutionUniqueNameBranchGitFolder
Importante
Debe conectar primero la solución inicial para que esto funcione. Consulte Conexión de la primera solución a un repositorio de Git.
En este ejemplo se muestra cómo usar la acción ConnectToGit para conectar soluciones posteriores a un repositorio de Git.
Solicitud
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"
}
Respuesta
HTTP/1.1 204 No Content
OData-Version: 4.0
Desconecte una solución específica del control de código fuente de Git mientras mantiene conectadas otras soluciones
Use este enfoque para quitar el control de código fuente de una solución sin afectar a otros usuarios.
En este ejemplo se muestra cómo usar la acción DisconnectFromGit para quitar el control de código fuente de una solución sin afectar a otros.
Solicitud
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"
}
Respuesta
HTTP/1.1 204 No Content
OData-Version: 4.0
Control de errores
Ni la API ConnectToGit ni la API DisconnectFromGit devuelven un valor cuando se completa correctamente. Cuando se produce un error en una API, devuelve un error.
Las situaciones de error más comunes son:
- Credenciales no válidas: asegúrese de que tiene autenticación válida en el proveedor de Git.
- Repositorio no encontrado: compruebe los nombres de organización, proyecto y repositorio.
- Permiso denegado: asegúrese de que la cuenta de Dataverse tiene permisos de administración de control de código fuente.
-
Solución no encontrada: compruebe que
SolutionUniqueNameexiste en su entorno. - La rama no existe: confirme que la rama especificada existe en el repositorio.
Soporte técnico y recursos adicionales
Para obtener más información sobre la integración del control de código fuente con Dataverse, consulte: