使用 API 自动实现 Git 集成

借助 Microsoft Fabric Git 集成工具，团队可以使用源控件进行协作，从而为其 Fabric 内容构建有效且可重复使用的发布过程。

借助 Microsoft Fabric REST API，可以自动化 Fabric 过程和流程，从而以更少的错误更快完成任务。 因此获得的效率可以节省成本并提高生产力。

本文介绍了如何使用 Git 集成 REST API 在 Microsoft Fabric 中自动化集成 Git。

Prerequisites

若要使用 Fabric Git API，需要：

• 与在 UI 中使用 Git 集成所需的先决条件相同。

• 用于 Fabric 服务的 Microsoft Entra 令牌。 该令牌将在 API 调用的授权标头中使用。 有关如何获取令牌的信息，请参阅 Fabric API 快速入门。

• 如果使用服务主体，则它需要与用户主体相同的权限。 若要为 Azure DevOps 设置服务主体，请参阅 Git 与服务主体的集成。

可以在不使用 PowerShell 的情况下使用 REST API，但本文中的脚本使用 PowerShell。 若要运行脚本，请执行以下步骤：

• 安装 PowerShell。
• 安装 Azure PowerShell Az 模块。

Git 集成 API 函数

Git 集成 REST API 有助你实现内容的持续集成和持续交付 (CI/CD)。 下面是可以使用 API 完成的几个示例：

• 连接特定工作区与 Git 仓库以及连接到它的分支以及将其断开连接。 （连接需要 Git 提供程序凭据的 connectionId。）

• 获取指定工作区的连接详细信息。

• 获取或创建 Git 提供程序凭据连接。

• 更新 Git 凭据 以更新 Git 凭据配置详细信息。 需要 Git 提供程序凭据的 connectionId。

• 获取 Git 凭据 以获取 Git 凭据配置详细信息。

• 初始化连接到 Git 的工作区的连接。

• 查看哪些项具有传入的更改，以及哪些项具有尚未通过 Git 状态 API 提交到 Git 的更改。

• 将工作区中所做的更改提交到已连接的远程分支。

• 使用推送到已连接分支的提交更新工作区。

Examples

可通过下面的 PowerShell 脚本来了解如何执行多个常见的自动化过程。 若要在 PowerShell 示例中查看或复制文本，请使用本部分中的链接。 还可以查看 Fabric Git 集成示例 GitHub 存储库中的所有示例。

连接并更新

本节介绍将工作区与 Git 连接并更新所涉及的步骤。

有关完整脚本，请参阅从 Git 连接并更新。 （脚本兼容性为 PowerShell 5.1）

1. 连接到 Azure 帐户并获取访问令牌 - 以用户或服务主体身份登录到 Fabric。 使用 Connect-AzAccount 命令进行连接。 若要获取访问令牌，请使用 Get-AzAccessToken 命令，并将 安全字符串令牌转换为纯文本

   代码应如下所示：

   • 用户主体
   • 服务主体

    $global:resourceUrl = "https://api.fabric.microsoft.com"
   
    $global:fabricHeaders = @{}
   
    function SetFabricHeaders() {
   
       #Login to Azure
       Connect-AzAccount | Out-Null
   
       # Get authentication
       $secureFabricToken = (Get-AzAccessToken -AsSecureString -ResourceUrl $global:resourceUrl).Token
   
       # Convert secure string to plain test
       $ssPtr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureFabricToken)
       try {
           $fabricToken = [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($ssPtr)
       } finally {
           [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ssPtr)
      }
   
     $global:fabricHeaders = @{
        'Content-Type' = "application/json"
        'Authorization' = "Bearer {0}" -f $fabricToken
    }
   }
   

2. 调用连接 API，以将工作区连接到 Git 存储库和分支。 （可能需要先 创建连接 ）

   有关如何获取连接详细信息（ID、名称）的信息，请参阅 获取或创建 Git 提供程序凭据连接。

   • Azure DevOps
   • GitHub （用户或服务主体）

   $global:baseUrl = "https://api.fabric.microsoft.com/v1"
   $workspaceName = "<WORKSPACE NAME>"
   $getWorkspacesUrl = "{0}/workspaces" -f $global:baseUrl
   $workspaces = (Invoke-RestMethod -Headers $global:fabricHeaders -Uri $getWorkspacesUrl -Method GET).value
   
   # Find the workspace by display name
   $workspace = $workspaces | Where-Object {$_.DisplayName -eq $workspaceName}
   
   # Connect to Git
   Write-Host "Connecting the workspace '$workspaceName' to Git."
   $connectUrl = "{0}/workspaces/{1}/git/connect" -f $global:baseUrl, $workspace.Id
   
   # AzureDevOps details
   $azureDevOpsDetails = @{
       gitProviderType = "AzureDevOps"
       organizationName = "<ORGANIZATION NAME>"
       projectName = "<PROJECT NAME>"
       repositoryName = "<REPOSITORY NAME>"
       branchName = "<BRANCH NAME>"
       directoryName = "<DIRECTORY NAME>"
   }
   
   $connectToGitBody = @{}
   #Leave only one of the following two (delete the other one):
   #-----------------------------------------------------------------------------------------------
   # 1. Automatic (SSO)
   $connectToGitBody = @{
       gitProviderDetails = $gitProviderDetails
   } | ConvertTo-Json
   #-----------------------------------------------------------------------------------------------
   # 2. ConfiguredConnection (User or service principal)
   # Get workspaces
   $connectionName = "<CONNECTION Name>"
   $getConnectionsUrl = "{0}/connections" -f $global:baseUrl
   $connections = (Invoke-RestMethod -Headers $global:fabricHeaders -Uri $getConnectionsUrl -Method GET).value
   
   # Find the connection by display name
   $connection = $connections | Where-Object {$_.DisplayName -eq $connectionName}
   $connectToGitBody = @{
       gitProviderDetails = $azureDevOpsDetails
       myGitCredentials = @{
           source = "ConfiguredConnection"
           connectionId = $connection.id
           }
       } | ConvertTo-Json
   #-----------------------------------------------------------------------------------------------
   
   Invoke-RestMethod -Headers $global:fabricHeaders -Uri $connectUrl -Method POST -Body $connectToGitBody
   

3. 调用初始化连接 API，以初始化工作区与 Git 存储库/分支之间的连接。

   # Initialize Connection
   
   Write-Host "Initializing Git connection for workspace '$workspaceName'."
   
   $initializeConnectionUrl = "{0}/workspaces/{1}/git/initializeConnection" -f $global:baseUrl, $workspace.Id
   $initializeConnectionResponse = Invoke-RestMethod -Headers $global:fabricHeaders -Uri $initializeConnectionUrl -Method POST -Body "{}"
   

4. 根据初始化连接 API 的响应，调用从 Git 更新 API 以完成更新，或者在不需要任何操作的情况下不执行任何操作。

   以下脚本更新并监视进度：

   if ($initializeConnectionResponse.RequiredAction -eq "UpdateFromGit") {
   
       # Update from Git
       Write-Host "Updating the workspace '$workspaceName' from Git."
   
       $updateFromGitUrl = "{0}/workspaces/{1}/git/updateFromGit" -f $global:baseUrl, $workspace.Id
   
       $updateFromGitBody = @{ 
           remoteCommitHash = $initializeConnectionResponse.RemoteCommitHash
     workspaceHead = $initializeConnectionResponse.WorkspaceHead
       } | ConvertTo-Json
   
       $updateFromGitResponse = Invoke-WebRequest -Headers $global:fabricHeaders -Uri $updateFromGitUrl -Method POST -Body $updateFromGitBody
   
       $operationId = $updateFromGitResponse.Headers['x-ms-operation-id']
       $retryAfter = $updateFromGitResponse.Headers['Retry-After']
       Write-Host "Long Running Operation ID: '$operationId' has been scheduled for updating the workspace '$workspaceName' from Git with a retry-after time of '$retryAfter' seconds." -ForegroundColor Green
   
       # Poll Long Running Operation
       $getOperationState = "{0}/operations/{1}" -f $global:baseUrl, $operationId
       do
       {
           $operationState = Invoke-RestMethod -Headers $global:fabricHeaders -Uri $getOperationState -Method GET
   
           Write-Host "Update from Git operation status: $($operationState.Status)"
   
           if ($operationState.Status -in @("NotStarted", "Running")) {
               Start-Sleep -Seconds $retryAfter
           }
       } while($operationState.Status -in @("NotStarted", "Running"))
   }
   

从 Git 更新

在本节中，我们将介绍使用 Git 中的更改更新工作区所涉及的步骤。 在此脚本中，我们将使用 Git 中的更改来更新工作区项，但会保留 Git 存储库不变。

有关完整脚本，请参阅从 Git 更新工作区。

1. 登录到 Git 并获取身份验证。
2. 调用获取状态 API 以根据 Git 请求正文生成更新。
3. 调用从 Git 更新 API，以使用推送到已连接分支的提交更新工作区。

全部提交

本节分步说明了如何以编程方式将工作区中的所有更改提交到 Git。

有关完整脚本，请参阅将所有更改提交到 Git。

1. 登录到 Git 并获取身份验证。
2. 连接到工作区。
3. 调用提交到 Git REST API。
4. 获取用于轮询操作状态的长期运行 OperationId。

选择性提交

本节介绍仅将工作区的特定更改提交到 Git 所涉及的步骤。

有关完整脚本，请参阅将选定更改提交到 Git。

1. 登录到 Git 并获取身份验证。
2. 连接到工作区。
3. 调用获取状态 API 以查看工作区的哪些项发生了更改。
4. 选择要提交的特定项。
5. 调用提交到 Git API，以将工作区的选定更改提交到连接的远程分支。

监视长期运行操作的进度

有关完整脚本，请参阅轮询长期运行的操作。

1. 从“通过 Git 更新”或“提交到 Git”脚本检索 operationId。
2. 按指定的间隔（以秒为单位）调用获取 LRO 状态 API 并打印状态。

获取或创建 Git 提供程序凭据连接

若要 连接到 Git 存储库或 更新 Git 凭据 ，需要提供 connectionId。 connectionId 可以来自你创建的新连接或现有连接。

• 使用 Git 提供程序凭据创建新的连接
• 请使用您有权限的现有连接。

创建存储 Git 凭据的新连接

# Connection with ServicePrincipal details for AzureDevOpsSourceControl
$adoSPConnection = @{
    connectivityType = "ShareableCloud"
    displayName = "<CONNECTION NAME>"
    connectionDetails = @{
        type = "AzureDevOpsSourceControl"
        creationMethod = "AzureDevOpsSourceControl.Contents"
        parameters = @(
            @{
                dataType = "Text"
                name = "url"
                value = "<Repo url in Azure DevOps>"
            }
        )
    }
    credentialDetails = @{
        credentials = @{
            credentialType = "ServicePrincipal"
            tenantId = "<SP tenant (directory) id (Guid)>"
            servicePrincipalClientId = "<SP APP (client) id (Guid)>"
            servicePrincipalSecret = "<SP Secret>"
        }
    }
}

#Note: AzureDevOps for UserPrincipal is not supported (since it requires interactive OAuth2)

POST https://api.fabric.microsoft.com/v1/connections

{
  "displayName": "<CONNECTION NAME>",
  "connectivityType": "ShareableCloud",
  "connectionDetails": {
    "creationMethod": "AzureDevOpsSourceControl.Contents",
    "type": "AzureDevOpsSourceControl",
    "parameters": [
     {
      "dataType": "Text",
      "name": "url",
      "value": "<Repo url in Azure DevOps>”
     }
    ]
  },
  "credentialDetails": {
    "credentials": {
      "credentialType": "ServicePrincipal",
      "tenantId": “<SP tenant (directory) id (Guid)>”,
      "servicePrincipalClientId": “<SP APP (client) id (Guid)>”,
      "servicePrincipalSecret": “<SP Secret>”
    }
  }
}
 

{
  "allowConnectionUsageInGateway": false,
  "id": "********-****-****-****-c13b543982ac",
  "displayName": "<CONNECTION NAME>",
  "connectivityType": "ShareableCloud",
  "connectionDetails": {
    "path": "<Repo url in Azure DevOps>",
    "type": "AzureDevOpsSourceControl"
  },
  "privacyLevel": "Organizational",
  "credentialDetails": {
    "credentialType": "ServicePrincipal",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
  }
}

POST https://api.fabric.microsoft.com/v1/connections

{
 "connectivityType": "ShareableCloud",
 "displayName": "MyGitHubPAT",
 "connectionDetails": {
  "type": "GitHubSourceControl",
  "creationMethod": "GitHubSourceControl.Contents",
  "parameters": [
   {
    "dataType": "Text",
    "name": "url",
    "value": "https://github.com/OrganizationName/RepositoryName"
   }
  ]
 },
 "credentialDetails": {
  "credentials": {
   "credentialType": "Key",
   "key": "*********"  //Enter your GitHub Personal Access Token
  }
 }
}

{
  "id": "3aba8f7f-d1ba-42b1-bb41-980029d5a1c1",
   "connectionDetails": {
       "path": "https://github.com/OrganizationName/RepositoryName",
       "type": "GitHubSourceControl"
   },
   "connectivityType": "ShareableCloud",
   "credentialDetails": {
       "connectionEncryption": "NotEncrypted",
       "credentialType": "Key",
       "singleSignOnType": "None",
       "skipTestConnection": false
   },
   "displayName": "MyGitHubPAT",
   "gatewayId": null,
   "privacyLevel": "Organizational"
}

获取现有连接的列表

使用 列表连接 API 获取你有权访问的现有连接的列表及其属性。

示例请求

GET https://api.fabric.microsoft.com/v1/connections

示例响应

{
 "value": [
  {
   "id": "e3607d15-6b41-4d11-b8f4-57cdcb19ffc8",
   "displayName": "MyGitHubPAT1",
   "gatewayId": null,
   "connectivityType": "ShareableCloud",
   "connectionDetails": {
    "path": "https://github.com",
    "type": "GitHubSourceControl"
   },
   "privacyLevel": "Organizational",
   "credentialDetails": {
    "credentialType": "Key",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
   }
  },
  {
   "id": "3aba8f7f-d1ba-42b1-bb41-980029d5a1c1",
   "displayName": "MyGitHubPAT2",
   "gatewayId": null,
   "connectivityType": "ShareableCloud",
   "connectionDetails": {
    "path": "https://github.com/OrganizationName/RepositoryName",
    "type": "GitHubSourceControl"
   },
   "privacyLevel": "Organizational",
   "credentialDetails": {
    "credentialType": "Key",
    "singleSignOnType": "None",
    "connectionEncryption": "NotEncrypted",
    "skipTestConnection": false
   }
  }
 ]
}

复制所需的连接的 ID，并将其用于 Git - 连接 或 Git - 更新我的 Git 凭据 API。

注意事项和限制

• 使用 API 进行 Git 集成的限制与使用 Git 集成用户界面时相同。
• 使用增强刷新 API刷新语义模型后，每次刷新都会导致产生 Git 差异。

相关内容

• Git 集成 - 入门
• Fabric API
• Git 最佳做法