Bitbucket 服务器 API

Bitbucket Server API 简介

开发人员可以通过功能强大的 Bitbucket Server API 以编程方式与 Bitbucket Server 代码仓库、拉取请求、分支以及其他与仓库相关的资源进行交互。它提供了一组 RESTful 端点，让用户能够有效地管理仓库、自动化流程以及与外部技术对接。团队可以利用该 API 加速代码协作流程、执行仓库规则并减少人工操作。它是大规模管理 Git 仓库的企业的重要工具，因为开发人员可以用它来建立仓库、管理访问控制、合并拉取请求以及获取提交历史记录。

Bitbucket Server 及其 API

对于需要安全、本地代码托管和协作的团队来说，Bitbucket Server 是一个企业级的 Git 仓库管理解决方案。它提供了代码审查工具、仓库访问管理以及 CI/CD 流水线集成等功能。Bitbucket Server API 在这些功能的基础上，提供了一种以编程方式与仓库、分支、提交和拉取请求进行交互的方法。

Bitbucket Cloud API 与 Bitbucket Server API 的区别

Bitbucket Cloud API 和 Bitbucket Server API 都提供相似的功能，但它们的运作方式有很大不同。Bitbucket Cloud API 用于 Bitbucket 的云托管功能，而 Bitbucket Server API 专为自托管或本地部署而设计。一个重要的区别在于认证方式。Bitbucket Cloud API 严重依赖 OAuth 2.0、API 密钥和应用密码，而 Bitbucket Server API 则提供基于会话的认证、基本认证和个人访问令牌。这使得 Bitbucket Server API 在企业安全设置方面更具适应性。

端点结构也存在差异。Bitbucket Cloud API 的请求通常使用基础 URL https://api.bitbucket.org/2.0/，而 Bitbucket Server API 的请求则使用 http://bitbucket-server.example.com/rest/api/1.0/。例如，使用 Bitbucket Cloud API 检索仓库列表的方式如下：

而在 Bitbucket Server API 中，等效的请求是：

Bitbucket Server API 的常见用例

Bitbucket Server API 的常见用途包括执行安全和合规规定、自动化仓库维护以及与外部应用程序集成。

自动化仓库是一个常见的用例。团队可以通过编程方式创建、更新和删除仓库，确保项目之间的一致性。例如，当一个新的开发项目启动时，脚本可以使用 API 自动构建所需的仓库结构。另一个用例是分支和权限管理。通过使用 API，组织可以强制执行分支限制，并确保开发人员遵循既定的工作流程。

CI/CD 流水线集成是另一个重要的用例。API 可以用于检索构建状态、将部署与仓库变更联系起来，以及在新提交被推送时启动构建。例如，DevOps 团队可以配置一个 webhook，在合并拉取请求时自动触发 Jenkins 构建。

设置 Bitbucket Server API

使用 API 的先决条件

使用 Bitbucket Server API 的先决条件是拥有一个稳定的网络连接和一个活跃的 Bitbucket Server 实例。需要一个具有必要权限的有效用户帐户来访问仓库和项目。此外，请确保服务器设置允许 API 访问，因为一些企业出于安全原因可能会限制或约束访问。还建议查阅 Bitbucket Server API 文档，以了解可用的端点及其请求语法。您可以通过使用 cURL、Postman 或任何其他 REST 客户端等工具来有效地测试 API 调用和响应。在任何编程语言中进行开发时，可以使用 HTTP 请求库，例如 Java 中的 HttpClient 和 Python 中的 requests。

生成 API 令牌和认证方法（基本认证、OAuth、个人访问令牌）

Bitbucket Server 提供多种认证选项以实现安全的 API 交互。基本认证是在请求头中发送用户名和密码或应用密码。基于令牌的认证方法比这种简单的方法更安全。OAuth 认证提供了一种更安全的认证方法，它通过提供一个访问令牌，应用程序可以使用该令牌访问 API，而无需泄露用户凭据。个人访问令牌（PATs）提供了一种无需密码即可认证 API 请求的便捷方式。您可以使用这些令牌指定范围，例如对仓库的只读或读写访问权限，这些令牌可以在 Bitbucket Server 用户设置中创建。使用个人访问令牌时，它会包含在您的 API 权限头中。

例如，使用 cURL 进行基本认证

使用个人访问令牌代替密码

如果您正在使用 OAuth，您必须首先请求一个访问令牌，然后将其包含在您的 API 请求中。

这是一个带有令牌的标准 OAuth 请求的样子

每种认证技术都有特定的用途，选择哪一种最好取决于集成需求和安全要求。

配置 API 访问权限

在 Bitbucket Server 中，用户角色和权限设置决定了对 API 的访问。用户必须拥有必要的权限才能通过 API 访问仓库、项目和管理活动。管理员可以在项目或仓库级别分配角色来配置 API 权限。Bitbucket 允许用户定义范围，以限制他们可以使用个人访问令牌执行的操作。例如，具有只读权限的令牌可以从仓库检索数据，但无法推送新代码或删除文件。如果您需要更改仓库内容，则必须创建一个具有写访问权限的令牌。

理解 Bitbucket Server API 端点

自动化和 Bitbucket Server 集成是通过 Bitbucket Server API 实现的，该 API 提供了一组用于与仓库、拉取请求、分支和用户管理进行交互的 API。开发人员可以通过使用这些 API 高效地进行代码协作、管理仓库和限制项目访问。

仓库管理 API（创建、列出、更新、删除仓库）

Bitbucket Server 的仓库管理 API 支持以编程方式创建、检索、更新和删除仓库。通过向 /rest/api/1.0/projects/{projectKey}/repos 发送包含仓库名称和设置的 POST 请求来创建仓库。向 /rest/api/1.0/projects/{projectKey}/repos 发送 GET 请求可以列出项目中的所有仓库。可以使用 PUT 请求更新仓库设置，但必须向仓库的 API 端点发送 DELETE 请求才能删除仓库。例如，可以使用 curl 命令 "my-repo" 在项目 "PROJ" 中创建一个新仓库

拉取请求 API（创建、审查、合并拉取请求）

用户可以使用拉取请求 API 创建、审查和合并拉取请求。可以通过向 /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests 发送包含源分支和目标分支信息的 POST 请求来创建拉取请求。要审查拉取请求，请向 /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments 发送带有评论的 POST 请求。您可以使用 POST 请求向 /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/merge 来合并拉取请求。例如，在仓库中，可以使用以下请求从 feature-branch 创建到 main 的拉取请求

分支管理 API（列出、创建、删除分支）

可以使用分支管理 API 添加、删除和列出仓库的分支。向 /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches 发送 GET 调用将列出所有分支。要创建分支，必须向同一端点发送包含分支名称和基础分支的 POST 请求。使用 DELETE 请求到 /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches 来删除分支。

例如，执行以下命令以从 main 创建一个名为 feature-branch 的新分支

用户和组 API（管理用户、权限和组）

Bitbucket Server 的用户和组 API 有助于管理组分配、用户访问和权限。要将用户添加到仓库，请向 /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users?name={username}&permission={permissionType} 发送 PUT 请求。使用 GET 调用 /rest/api/1.0/admin/groups/more-members?context={groupName} 获取组中用户的列表。可以使用 PUT 或 DELETE 请求更改访问级别以管理组权限。

例如，使用以下请求授予用户对仓库的读取权限

这些 API 端点简化了 Bitbucket Server 中的仓库、拉取请求、分支和用户管理，实现了自动化和与其他工具的无缝集成。

使用示例发起 API 请求

使用 Curl 发送 API 请求

通过发送带有认证信息的 HTTP 请求，您可以使用 curl 直接从命令行与 Bitbucket server API 进行交互。例如，通过替换您的登录信息和 Bitbucket server URL，您可以使用以下命令从特定项目获取仓库列表：

在此例中，URL http://your-bitbucket-server/rest/api/1.0/projects/PROJECT/repos 是用于从特定项目检索仓库的 API 端点，而 username:password 代表您的 Bitbucket 凭据。服务器的响应将以 JSON 格式返回仓库列表，以便进行进一步处理或解析。这种自动化 Bitbucket 活动而无需使用其 Web 界面的方法简单而有效。

使用 Postman 测试 API 调用

在测试 API 时，Postman 是开发人员的重要工具。它提供了一个界面，您可以快速设置头部、认证和请求参数，从而简化了向 Bitbucket API 发送调用的过程。您可以使用 Postman 测试 Bitbucket API，方法是将请求方法设置为 GET，使用基本认证输入您的 Bitbucket 凭据，并提供 Bitbucket API URL。例如，您可以将 Postman 设置为发送与上述相同的 GET 请求来获取仓库，Postman 将显示结果。在使用脚本或其他程序自动化您的 API 调用之前，您可以通过这种可见的反馈快速进行故障排除或验证。还支持 POST、PUT 和 DELETE 等其他方法。

与 API 交互的 Python 脚本示例

requests 包使得使用 Python（一种灵活的语言）与 RESTful API（如 Bitbucket 的 API）进行通信非常简单。以下 Python 脚本演示了如何使用 requests 获取项目的仓库列表。您可以通过更改 URL、项目密钥和您的登录信息来为自己的 Bitbucket 实例修改该脚本：

此脚本中使用的 API 端点 url 用于获取指定项目的仓库列表。auth 元组包含您的 Bitbucket 用户名和密码，用于身份验证。如果请求成功（200 OK），脚本会在验证响应状态码后输出包含仓库数据的 JSON 响应。否则，它会打印状态码和错误消息以帮助您调试。

这种方法对于自动化诸如通过 API 调用处理拉取请求、创建新仓库以及检索仓库详情等流程非常有效。您甚至可以扩展脚本以管理更多 API 操作，例如创建分支、启动构建或与拉取请求交互，从而让您完全控制 Bitbucket 的功能。

使用 Bitbucket Server API 自动化工作流

Bitbucket Server API 是一个强大的工具，使开发人员能够自动化流程，提高生产力并减少仓库管理所需的人工劳动。通过 API 端点可以自动化仓库创建、CI/CD 流水线集成和仓库活动监控等流程，确保更快的开发周期和更可靠的部署。

自动化仓库创建和管理

开发人员可以使用 Bitbucket Server API 自动化仓库的创建和管理。用户可以向指定的 API 端点发送带有必需参数（如仓库名称、项目密钥和版本控制系统类型（例如 Git））的 POST 请求，而不是通过用户界面手动设置新仓库。这不仅节省了时间，还降低了人为错误的可能性，并确保仓库始终以正确的配置建立。例如，API 允许您为需要它们的多个项目批量创建新仓库，从而为您的团队节省大量的设置时间。

使用 API 设置 CI/CD 流水线触发器

Bitbucket Server API 的一个主要特性是能够自动化 CI/CD 流水线触发器。您可以使用 webhooks 将 Bitbucket 与外部 CI/CD 工具连接。当特定的仓库事件发生时，这些 webhooks 会通知您的 CI/CD 系统。例如，您可以配置一个 webhook，以便每当有提交上传到仓库，或者有拉取请求被提交或合并时，就启动一个 Jenkins 构建。通过消除手动触发的需求，代码更改可以持续地进行测试、构建和发布。此外，您可以通过使用 API 选择要监控的事件（如仓库更改、拉取请求更新或分支合并）来根据团队的需求定制自动化。

使用 API 监控仓库活动

团队还可以使用 Bitbucket Server API 实时跟踪仓库活动，这对于跟踪开发进度和确保代码质量特别有用。例如，开发人员可以检索最近的提交日志、拉取请求状态和分支更新，以获取仓库活动的最新情况。通过自动化此过程，团队可以快速发现问题，如未解决的拉取请求或失败的构建，而无需手动检查 Bitbucket 界面。这使得跟踪项目开发变得更容易，确保代码审查按时完成，并遵循开发流水线的所有阶段。

最佳实践和安全注意事项

API 速率限制和性能优化

Bitbucket Server API 通过实施速率限制来确保公平使用和系统稳定性，防止过多的请求损害服务器性能。您可以通过只检索必要的数据字段而不是整个数据集来减少重复 API 调用的数量并提高性能。在处理大型数据库时，使用分页将响应分成可管理的部分，以减少内存消耗并改善响应时间。对经常检索的数据使用缓存技术，以减少 API 请求的次数并提高效率。当仓库事件（如拉取请求、提交或分支修改）发生时，使用 webhooks 获取实时通知，而不是依赖定期轮询。为避免服务器过载，如果 API 请求达到速率限制，请使用指数退避技术，逐渐延长重试之间的等待时间。例如，如果 API 请求返回 429 错误（请求过多），请等待几秒钟再重试。如果这不起作用，请延长延迟时间。

保护 API 密钥和认证令牌

认证令牌和 API 密钥是需要保护的重要安全元素，因为它们提供了对 Bitbucket Server API 的访问权限。不要将 API 密钥留在日志、配置文件或公开可用的仓库中，因为它们可能被恶意用户使用。应使用环境变量、密钥管理软件或像 AWS Secrets Manager 或 HashiCorp Vault 这样的保险库解决方案来安全地存储它们。定期轮换 API 密钥以降低未经授权访问的可能性，并确保泄露的密钥不会永远保持活动状态。如果怀疑 API 密钥泄露，建议立即删除该密钥并创建一个新的。使用基于角色的访问控制（RBAC）将 API 令牌限制在必要的操作范围内，而不是授予完整的管理访问权限。为提高安全性，请使用 OAuth 2.0 认证而不是基本认证，因为 OAuth 令牌限制了令牌的范围和有效期，从而提高了安全性。

处理 API 错误和异常

在使用 Bitbucket Server API 时有效管理错误可确保应用程序平稳运行并增强用户体验。API 响应中包含的错误代码提供了有关请求失败的信息，其中包括错误代码 400（错误请求）、401（未经授权的访问）、403（受限请求）、404（资源未找到）和 500（内部服务器问题）。为避免客户端问题并确保数据格式正确，请务必验证 API 请求的参数。通过评估 API 响应并记录详细的错误消息以进行调试，您可以提供结构化的错误处理。例如，如果请求失败并出现 500 错误（内部服务器错误），请记录请求数据并通知系统管理员进行调查。对于临时问题，如 429（请求过多）或 503（服务不可用），请使用带指数退避的重试逻辑，以避免向 API 发送过多的快速重试。如果身份验证失败，请请求用户重新验证或更新其 OAuth 令牌。在 API 响应中包含有见地的错误消息可以提高系统可靠性，并帮助开发人员有效地解决问题。

真实世界用例和示例

使用 Bitbucket API 自动化代码审查

Bitbucket API 与多个拉取请求端点交互，提供强大的代码审查自动化功能。例如，当功能分支被提交时，您可以使用自动化根据特定标准自动生成拉取请求。可以根据分支名称或代码中的修改自动分配审查者，确保合适的人在合适的时间参与。能够检索拉取请求状态信息（无论是开放、合并还是拒绝）使您能够监控代码审查进度，而无需主动检查 Bitbucket 界面。一个真实世界的例子是使用 API 根据代码所有者自动分配审查者。例如，发送到名为 "feature/user-authentication" 的分支的拉取请求可以自动分配给处理身份验证功能的高级开发人员。

动态管理权限和访问控制

Bitbucket API 使访问控制变得极其动态和可配置，能够对分支和仓库权限进行细粒度控制。您可以根据组织角色自动控制仓库访问。例如，您可以授予开发人员写权限，同时授予其他利益相关者（如 QA 或产品经理）只读权限。您还可以为不同的分支分配不同级别的权限，以确保敏感分支（如生产分支）受到比功能分支更严格的控制。此外，如果团队成员离开或更改角色，可以使用 API 快速撤销或更新对仓库或分支的访问权限，而无需手动修改设置。一个实际的例子是，一旦前团队成员从帐户中移除，脚本就会拒绝其访问权限。

将 Bitbucket API 与其他 DevOps 工具集成

Bitbucket API 的一个主要优势是能够轻松地与各种其他 DevOps 工具连接，并创建一个连贯的工作流程。例如，您可以通过将 Bitbucket 连接到 Jenkins 来自动化您的持续集成（CI）流水线。这将导致每当创建或更改拉取请求时自动启动构建。同样，集成 Jira 可以确保代码和项目管理系统之间的可追溯性，使您能够将提交直接链接到特定的 Jira 问题或任务。此外，当 Bitbucket 中发生特定事件时，例如拉取请求被合并或构建失败，与 Slack 等通信平台的接口可以自动通知相关渠道。当拉取请求被集成到主分支时，Slack 机器人可以通知团队的渠道，并提供指向成功构建和更新代码的链接。这种类型的集成可以让团队保持更新，同时也增强了协作并减少了手动检查。

结论

Bitbucket Server API 是一个强大的工具，用于增强团队协作、自动化仓库管理以及与 CI/CD 流水线连接。它提供了各种 RESTful API，方便地管理拉取请求、配置权限、构建仓库和管理分支工作流。这种自动化程度使开发团队受益，因为它简化了流程并确保了项目的一致性。与 Bitbucket Cloud API 相比，Bitbucket Server API 专为自托管环境而设计，对基础设施、安全性和合规性有更多的控制。OAuth、个人访问令牌和基本认证等一些认证技术可确保安全访问，同时在用户和权限管理方面提供灵活性。开发人员应遵循推荐的做法，例如限制 API 调用速率、使用适当的 HTTP 方法（GET、POST、PUT、DELETE）以及熟练地管理响应，以优化效率。此外，实施错误处理和日志记录方法可以增强稳定性和调试能力。组织可以通过利用 Bitbucket Server API 来强制执行开发策略、自动化繁琐的任务，并轻松地与第三方技术连接。对于在本地环境中管理 Git 仓库的团队来说，它是一个有用的工具，可以改善软件交付工作流程、版本控制和安全性。