Git - Connect

服务:: Core

API 版本:: v1

将特定工作区连接到 git 存储库和分支。
此作不会在工作区与连接的分支之间同步。若要完成同步，请使用 “初始化连接” 作，并遵循 “提交到 Git ”作或 “从 Git 更新” 作。

若要开始使用 GitHub，请参阅： Git 集成入门。

若要获取连接 ID，请参阅 Automate Git 集成。

权限

调用方必须具有工作区的 管理员 角色。

对于配置的连接 Git 凭据，调用方必须具有连接的权限。

所需的委派范围

Workspace.ReadWrite.All

局限性

使用自动凭据源时，GitHub 提供程序和服务主体会阻止此 API。

Microsoft Entra 支持的标识

此 API 支持本节中列出的Microsoft 标识。

身份	支持
用户	是的
服务主体和托管标识	仅当 myGitCredentials.source 为 ConfiguredConnection 时受支持

接口

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/git/connect

URI 参数

名称	在	必需	类型	说明
workspaceId	path	True	string (uuid)	工作区 ID。

请求正文

名称	必需	类型	说明
gitProviderDetails	True	GitProviderDetails: AzureDevOpsDetails GitHubDetails	Git 提供程序详细信息。
connectionSettings		GitConnectionSettings	可选连接设置，用于在连接时应用。如果省略，则默认适用。
myGitCredentials		GitCredentials: ConfiguredConnectionGitCredentials AutomaticGitCredentials	用户特定的 Git 凭据，用于向 GitProvider 进行身份验证。这些凭据不会与其他工作区参与者共享。对于 GitHub，此属性是必需的。对于 AzureDevOps，此属性是可选的。如果未设置，则默认值为 AutomaticGitCredentials。

响应

名称类型说明

200 OK

名称	类型	说明
200 OK		请求成功完成。
429 Too Many Requests	ErrorResponse	超出服务速率限制。服务器返回一个 `Retry-After` 标头，指示客户端在发送其他请求之前必须等待的时间（以秒为单位）。标头 Retry-After: integer
Other Status Codes	ErrorResponse	常见错误代码： UnknownError - 发生错误。 WorkspaceAlreadyConnectedToGit - 工作区已连接到 git。 WorkspaceHasNoCapacityAssigned - 没有分配给工作区的容量。 InsufficientPrivileges - 调用方没有足够的工作区权限。 PrincipalTypeNotSupported - 不支持调用方标识类型。

请求成功完成。

429 Too Many Requests

ErrorResponse

超出服务速率限制。服务器返回一个 Retry-After 标头，指示客户端在发送其他请求之前必须等待的时间（以秒为单位）。

标头

Retry-After: integer

Other Status Codes

ErrorResponse

常见错误代码：

UnknownError - 发生错误。
WorkspaceAlreadyConnectedToGit - 工作区已连接到 git。
WorkspaceHasNoCapacityAssigned - 没有分配给工作区的容量。
InsufficientPrivileges - 调用方没有足够的工作区权限。
PrincipalTypeNotSupported - 不支持调用方标识类型。

示例

Connect a workspace to Azure DevOps example

Connect a workspace to Azure DevOps using configured connection example

Connect a workspace to Azure DevOps with connection settings example

Connect a workspace to GitHub example

Connect a workspace to GitHub example - GitHub Enterprise With Data Residency (ghe.com)

Connect a workspace to Azure DevOps example

示例请求

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/1565e6a3-c020-4c0c-dda7-92bafe99eec5/git/connect

{
  "gitProviderDetails": {
    "organizationName": "Test Organization",
    "projectName": "Test Project",
    "gitProviderType": "AzureDevOps",
    "repositoryName": "Test Repo",
    "branchName": "Test Branch",
    "directoryName": "Test Directory"
  }
}

示例响应

状态代码:: 200

Connect a workspace to Azure DevOps using configured connection example

示例请求

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/1565e6a3-c020-4c0c-dda7-92bafe99eec5/git/connect

{
  "gitProviderDetails": {
    "organizationName": "Test Organization",
    "projectName": "Test Project",
    "gitProviderType": "AzureDevOps",
    "repositoryName": "Test Repo",
    "branchName": "Test Branch",
    "directoryName": "Test Directory/Test Subdirectory"
  },
  "myGitCredentials": {
    "source": "ConfiguredConnection",
    "connectionId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"
  }
}

示例响应

状态代码:: 200

Connect a workspace to Azure DevOps with connection settings example

示例请求

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/1565e6a3-c020-4c0c-dda7-92bafe99eec5/git/connect

{
  "gitProviderDetails": {
    "organizationName": "Test Organization",
    "projectName": "Test Project",
    "gitProviderType": "AzureDevOps",
    "repositoryName": "Test Repo",
    "branchName": "Test Branch",
    "directoryName": "Test Directory"
  },
  "connectionSettings": {
    "additionalRolesAuthorizedToChangeBranch": "MemberAndContributor"
  }
}

示例响应

状态代码:: 200

Connect a workspace to GitHub example

示例请求

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/1565e6a3-c020-4c0c-dda7-92bafe99eec5/git/connect

{
  "gitProviderDetails": {
    "ownerName": "Test Owner",
    "gitProviderType": "GitHub",
    "repositoryName": "Test Repo",
    "branchName": "Test Branch",
    "directoryName": "Test Directory/Test Subdirectory"
  },
  "myGitCredentials": {
    "source": "ConfiguredConnection",
    "connectionId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"
  }
}

示例响应

状态代码:: 200

Connect a workspace to GitHub example - GitHub Enterprise With Data Residency (ghe.com)

示例请求

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/1565e6a3-c020-4c0c-dda7-92bafe99eec5/git/connect

{
  "gitProviderDetails": {
    "ownerName": "Test Owner",
    "customDomainName": "my-enterprise.ghe.com",
    "gitProviderType": "GitHub",
    "repositoryName": "Test Repo",
    "branchName": "Test Branch",
    "directoryName": "Test Directory/Test Subdirectory"
  },
  "myGitCredentials": {
    "source": "ConfiguredConnection",
    "connectionId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"
  }
}

示例响应

状态代码:: 200

定义

名称	说明
AutomaticGitCredentials	自动 Git 凭据。
AzureDevOpsDetails	Azure DevOps 提供程序详细信息。
ConfiguredConnectionGitCredentials	配置的连接 Git 凭据。
ErrorParameter	一个结构化参数，提供有关错误的附加计算机可读上下文。
ErrorRelatedResource	与错误相关的资源详细信息对象。
ErrorResponse	错误响应。
ErrorResponseDetails	错误响应详细信息。
GitAdditionalBranchChangingRoles	允许更改连接的 Git 分支的管理员以外的其他工作区角色。可能会随着时间的推移添加其他值。
GitConnectionSettings	包含 Git 连接设置。
GitConnectRequest	包含 Git connect 请求数据。
GitCredentialsSource	Git 凭据源。可能会随着时间的推移添加其他 Git 凭据源。
GitHubDetails	GitHub 提供程序详细信息。
GitProviderType	Git 提供程序类型。可能会随着时间的推移添加其他提供程序类型。

AutomaticGitCredentials

对象

自动 Git 凭据。

名称	类型	说明
source	string: Automatic	Git 凭据源。

AzureDevOpsDetails

对象

Azure DevOps 提供程序详细信息。

名称	类型	说明
branchName	string maxLength: 250	分支名称。最大长度为 250 个字符。
directoryName	string maxLength: 256	目录的相对路径。最大长度为 256 个字符。
gitProviderType	string: AzureDevOps	Git 提供程序类型。可能会随着时间的推移添加其他提供程序类型。
organizationName	string maxLength: 100	组织名称。最大长度为 100 个字符。
projectName	string maxLength: 100	项目名称。最大长度为 100 个字符。
repositoryName	string maxLength: 128	存储库名称。最大长度为 128 个字符。

ConfiguredConnectionGitCredentials

对象

配置的连接 Git 凭据。

名称	类型	说明
connectionId	string (uuid)	连接的对象 ID。
source	string: ConfiguredConnection	Git 凭据源。

ErrorParameter

对象

一个结构化参数，提供有关错误的附加计算机可读上下文。

名称	类型	说明
message	string	参数含义的可读说明。
name	string	参数标识符。
value	string	参数值。

ErrorRelatedResource

对象

与错误相关的资源详细信息对象。

名称	类型	说明
resourceId	string	错误中涉及的资源 ID。
resourceType	string	错误中涉及的资源的类型。

ErrorResponse

对象

错误响应。

名称	类型	说明
errorCode	string	提供有关错误条件的信息的特定标识符，允许服务与其用户之间的标准化通信。
isRetriable	boolean	如果为 true，可以重试请求。 `Retry-After`使用响应标头确定延迟（如果可用）。
message	string	错误的人工可读表示形式。
moreDetails	ErrorResponseDetails[]	其他错误详细信息的列表。
parameters	ErrorParameter[]	提供有关错误的其他计算机可读上下文的结构化参数。
relatedResource	ErrorRelatedResource	与错误相关的资源详细信息。
requestId	string (uuid)	与错误关联的请求的 ID。

ErrorResponseDetails

对象

错误响应详细信息。

名称	类型	说明
errorCode	string	提供有关错误条件的信息的特定标识符，允许服务与其用户之间的标准化通信。
message	string	错误的人工可读表示形式。
parameters	ErrorParameter[]	提供有关错误的其他计算机可读上下文的结构化参数。
relatedResource	ErrorRelatedResource	与错误相关的资源详细信息。

GitAdditionalBranchChangingRoles

枚举

允许更改连接的 Git 分支的管理员以外的其他工作区角色。可能会随着时间的推移添加其他值。

值	说明
None	除了管理员之外，没有其他角色可以更改分支。这是默认值。
MemberAndContributor	除了管理员之外，成员和参与者还可以更改分支。

GitConnectionSettings

对象

包含 Git 连接设置。

名称	类型	说明
additionalRolesAuthorizedToChangeBranch	GitAdditionalBranchChangingRoles	允许更改连接的 Git 分支的管理员以外的其他工作区角色。

GitConnectRequest

对象

包含 Git connect 请求数据。

名称	类型	说明
connectionSettings	GitConnectionSettings	可选连接设置，用于在连接时应用。如果省略，则默认适用。
gitProviderDetails	GitProviderDetails: AzureDevOpsDetails GitHubDetails	Git 提供程序详细信息。
myGitCredentials	GitCredentials: AutomaticGitCredentials ConfiguredConnectionGitCredentials	用户特定的 Git 凭据，用于向 GitProvider 进行身份验证。这些凭据不会与其他工作区参与者共享。对于 GitHub，此属性是必需的。对于 AzureDevOps，此属性是可选的。如果未设置，则默认值为 AutomaticGitCredentials。

GitCredentialsSource

枚举

Git 凭据源。可能会随着时间的推移添加其他 Git 凭据源。

值	说明
ConfiguredConnection	Git 凭据是通过配置的连接获取的。
Automatic	系统会使用默认凭据（如果可用）自动获取 Git 凭据。
None	未配置 Git 凭据。

GitHubDetails

对象

GitHub 提供程序详细信息。

名称	类型	说明
branchName	string maxLength: 250	分支名称。最大长度为 250 个字符。
customDomainName	string maxLength: 100	如果未 github.com 企业GitHub域的名称。仅支持具有数据驻留域（ghe.com）的 GitHub Enterprise。最大长度为 100 个字符。
directoryName	string maxLength: 256	目录的相对路径。最大长度为 256 个字符。
gitProviderType	string: GitHub	Git 提供程序类型。可能会随着时间的推移添加其他提供程序类型。
ownerName	string maxLength: 100	所有者名称。最大长度为 100 个字符。
repositoryName	string maxLength: 128	存储库名称。最大长度为 128 个字符。

GitProviderType

枚举

Git 提供程序类型。可能会随着时间的推移添加其他提供程序类型。

值	说明
AzureDevOps	Azure DevOps 提供程序
GitHub	GitHub 提供程序