2. REST API基础与认证机制
Atlassian Cloud 的 REST API 是集成开发的主入口。无论是同步 Jira Issue、读取 Confluence 页面，还是触发 Bitbucket Pipeline，最终都要落到一次 HTTP 请求上。理解它的设计风格与认证机制，决定了集成方案能否稳定、安全地长期运行。
一、Atlassian Cloud REST API 的设计风格
Atlassian Cloud 的 REST API 遵循 REST 架构约束，整体呈现几个鲜明特征：
- 资源化 URL：URL 表达资源层级，例如
/rest/api/3/issue/{issueIdOrKey}表示 Jira 平台 v3 版本下的单个 Issue 资源。 - 版本化路径：Jira 使用
/rest/api/3（新版）与/rest/api/2（旧版），Confluence Cloud 使用/wiki/rest/api，Bitbucket Cloud 使用/2.0。版本号是 URL 的一部分，升级时需评估兼容性。 - 标准 HTTP 方法：GET 读取、POST 创建、PUT 全量更新、DELETE 删除，语义与 HTTP 规范一致。
- JSON 载荷：请求与响应体均为 JSON，Content-Type 通常为
application/json。 - 分页与限流：列表接口普遍使用
startAt、maxResults、total字段分页；响应头中的X-RateLimit-*系列字段用于限流判断。
一个典型的 Jira Issue 查询请求如下：
GET /rest/api/3/issue/PROJ-123?fields=summary,status,assignee
Host: your-domain.atlassian.net
Accept: application/json
Authorization: Basic <base64(email:api_token)>响应体是 JSON，包含 id、key、fields 等字段。理解这种“URL 定位资源 + 方法表达动作 + JSON 承载数据”的模式，是后续所有集成工作的基础。
二、三种认证机制的适用场景
Atlassian Cloud 主要提供三种认证方式，它们并非互相替代，而是面向不同使用场景。
| 认证方式 | 典型场景 | 凭据形态 | 安全等级 |
|---|---|---|---|
| Basic Auth（邮箱 + API Token） | 脚本、CLI、个人自动化、内部工具 | Base64(email:token) | 中，凭据长期有效 |
| OAuth 2.0（3LO） | 面向多租户的第三方应用、SaaS 集成 | Access Token + Refresh Token | 高，支持细粒度授权与撤销 |
| OAuth 2.0（2LO / 服务账号） | 企业级后台服务、无用户交互的自动化 | Client Credentials | 高，权限由管理员授予 |
Basic Auth + API Token 是最容易上手的方式。API Token 在 Atlassian 账户安全设置中生成，与邮箱组合后做 Base64 编码，放入 Authorization 头。它适合个人脚本或内部工具，但 Token 一旦泄露，攻击者即可在有效期内以该用户身份操作，因此必须配合最小权限账户与定期轮换。
OAuth 2.0 3LO 是面向第三方应用的标准方案。用户授权后，应用获得 Access Token（通常 1 小时有效）和 Refresh Token（长期有效，可撤销）。它的优势在于：权限范围（scope）可精确控制，用户可随时撤销授权，且不暴露用户密码或长期凭据。适合需要分发给多个客户使用的集成产品。
OAuth 2.0 2LO 适用于企业内部的机器对机器场景。管理员在 Atlassian 管理后台为应用授予权限，应用使用 Client Credentials 直接换取 Access Token，无需用户交互。它适合后台同步服务、定时任务等场景。
三、安全配置的关键实践
无论选择哪种认证方式，以下实践都应当遵守：
- 凭据不入代码库：API Token、Client Secret 应通过环境变量或密钥管理服务注入，禁止硬编码在源码或配置文件中。
- 最小权限原则：为集成创建专用账户，只授予必要的项目权限与 scope，避免使用管理员账户。
- Token 轮换与撤销：API Token 应定期更换；OAuth Refresh Token 在检测到异常时应立即撤销。
- 传输安全：所有请求必须走 HTTPS，禁止降级到 HTTP。
- 限流与重试：遇到 429 响应时，读取
Retry-After头并做指数退避，避免触发更严格的限流。
四、认证流程与请求链路
下图展示了三种认证方式在请求链路中的差异，以及它们与 Atlassian Cloud API 网关的交互关系。理解这张图，有助于在实际集成中快速判断该用哪种认证、凭据放在哪里、失败时从哪里排查。
从图中可以看到，三种认证方式最终都汇聚到 API 网关进行统一校验。区别在于凭据的获取方式、有效期和权限粒度。Basic Auth 的凭据直接携带在请求头中，OAuth 2.0 则需要先通过 /oauth/token 端点换取 Access Token，再携带该 Token 访问资源接口。
五、实操示例：用 API Token 调用 Jira Issue 接口
以下示例展示如何用 curl 和 API Token 查询一个 Jira Issue。假设邮箱为 dev@example.com，API Token 为 ATATT3xFfGF0...（示例值，非真实 Token）。
# 1. 生成 Base64 凭据
echo -n "dev@example.com:ATATT3xFfGF0..." | base64
# 输出示例：ZGV2QGV4YW1wbGUuY29tOkFUQVRUM3hGZkdGMC4uLg==
# 2. 发起请求
curl -s -X GET \
"https://your-domain.atlassian.net/rest/api/3/issue/PROJ-123?fields=summary,status" \
-H "Authorization: Basic ZGV2QGV4YW1wbGUuY29tOkFUQVRUM3hGZkdGMC4uLg==" \
-H "Accept: application/json"若返回 200 且响应体包含 key、fields.summary、fields.status.name，说明认证与权限均正常。若返回 401，检查邮箱与 Token 是否匹配、Token 是否已撤销；若返回 403，检查该账户是否有权访问该项目；若返回 429，读取 Retry-After 头并等待后重试。