通过 API 令牌连接 Jira

API 令牌可以让 Planning Poker Web 读取你 Jira 中的问题（issue），并将已接受的估算写回，而无需经过登录界面。本页说明如何创建令牌、它能做什么，以及出现问题时应检查哪些内容。本方法适用于 Jira Cloud（形如 your-team.atlassian.net 的地址），不支持 Jira Data Center。

开始之前

你需要在组织中拥有管理计划扑克的权限。所有者默认拥有该权限。
令牌所属的 Jira 账户在你要使用的每个项目中，需要具备浏览项目的权限（用于导入问题）和编辑问题的权限（用于回传估算）。如果你只导入而从不回传估算，浏览权限就够了。
建议使用专为此用途创建的共享账户，例如 [email protected]，而不是某个人的私人账户。估算会以该账户的名义出现在问题历史记录中，而个人令牌会在该人离职或失去访问权限的当天失效。

第一步：在 Atlassian 中创建令牌

使用你选定的账户登录 Atlassian，打开 id.atlassian.com → Security → API tokens。
选择创建 API 令牌。请使用普通版本，不要选择“创建带作用域的 API 令牌”：带作用域的令牌无法用于此连接。
为它起一个你能识别的名称，例如“Planning Poker Web”，并选择有效期。
请立即复制该令牌。Atlassian 只会显示一次。如果遗失，请重新创建一个。

如果你没有看到该选项，可能是你的 Atlassian 管理员限制了可以创建令牌的人员，请让他们为你选定的账户开放此权限。

第二步：在 Planning Poker Web 中连接

打开设置 → 集成，选择 Jira，再选择连接，然后选择 API 令牌选项。
填写三个字段：
- Jira 站点：你 Jira 的地址，例如 https://your-team.atlassian.net。仅接受 https://….atlassian.net 格式的地址。
- 账户邮箱：创建该令牌的 Atlassian 账户的邮箱地址。
- API 令牌：你刚复制的令牌。
选择测试。如果成功，你将看到该 Jira 账户的名称。你的令牌会以加密方式存储，之后不会再显示出来。
在配置步骤中，选择是否将已接受的估算回传到 Jira，以及写入哪个字段。请参阅回传估算。

工作原理

每个请求都由我们的服务器发往你的 Jira，并使用你的邮箱和令牌进行签名。该令牌拥有与创建它的账户完全相同的权限，不多也不少。Planning Poker Web 只会执行以下操作：

读取你的项目，以及某个项目的状态、问题类型、史诗（epic）和冲刺（sprint），以便导入对话框能够提供相应的筛选项。
读取问题：键值、标题和描述，以便将其带入房间。
写入一个数字到某个问题上：即你所选字段中的已接受估算。

它绝不会创建或删除问题，绝不会更改问题状态，也绝不会添加评论。只有当该账户能够在 Jira Software 中打开项目看板时，才会读取冲刺信息；否则，冲刺筛选项就只是空的。

如果无法正常工作

“Jira 拒绝了该凭证”：邮箱或令牌有误，令牌已被吊销，或已经过期。请创建一个新令牌并使用重新连接。
“Jira 拒绝了访问请求（403）”：Jira 理解了该密钥，但拒绝了该请求。请按以下顺序检查：该账户是否确实对该站点的 Jira 有访问权限（以该账户登录并打开该站点）；该账户是否能浏览该项目（如需回传估算，还需能编辑问题）；你的 Atlassian 管理员是否将 API 访问限制在了特定网络；以及该令牌是否为普通类型，而非“带作用域”的类型。如果 Jira 给出了自身的说明，会显示在冒号之后。
你的项目没有出现在列表中：说明该账户无法浏览该项目。请将该账户添加到项目中，或改用已属于该项目的账户。
估算未发送，并提示该字段不在屏幕上：该字段必须出现在该项目中问题的编辑屏幕上。Jira 有两个相似的字段，Story points 和 Story point estimate，请选择你看板上显示的那一个。
“请使用你的 Jira Cloud 地址”：站点字段的格式必须类似 https://your-team.atlassian.net，其后不能带有任何路径。

令牌过期或你想要停止时

Atlassian 的令牌不会永久有效。当你的令牌过期时，请创建一个新令牌并使用重新连接，你的估算设置会被保留。如需停止该连接，请在 Planning Poker Web 中选择断开连接；如果需要，还可以在 id.atlassian.com → Security → API tokens 中吊销该令牌。此后，任何请求都无法再访问你的 Jira。