本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Atlassian Jira 云集成
<a name="jira-integration"></a>

使用 Atlassian Jira Cloud 操作连接器，通过自然语言直接在 Amazon Quick 中创建、更新、搜索和管理 Jira 事务、项目、冲刺和用户。

设置此集成涉及两个步骤。首先，在 Atlassian 开发者控制台中创建 OAuth 2.0 (3LO) 应用程序并配置其权限。然后，您可以在 Amazon Quick 中创建集成并将其连接到您的 Atlassian 应用程序。有关 Amazon Quick 支持的身份验证方法的信息，请参阅[身份验证方法](quick-action-auth.md)。

## 开始前的准备工作
<a name="jira-integration-prerequisites"></a>

在设置集成之前，请确保您具备以下条件。
+ Atlassian Jira Cloud。
+ 访问 [Atlassian 开发者控制台](https://developer.atlassian.com/console/myapps/)以创建或管理应用程序。 OAuth 
+ 有关订阅要求，请参阅[在控制台中设置集成](integration-console-setup-process.md)。

## 配置 Atlassian 开发者控制台
<a name="jira-atlassian-setup"></a>

如果您计划使用用户身份验证 (3LO)，请在配置 Amazon Quick 之前在 Atlassian 开发者控制台中创建 OAuth 2.0 应用程序。在移至 Amazon Quick 控制台之前，请完成以下所有步骤。

如果您计划仅使用服务身份验证（API 密钥），则可以跳过本节继续操作[在 Amazon Quick 中设置集成](#jira-integration-setup)。

有关 OAuth 2.0 (3LO) 应用程序的更多信息，请参阅 Atlassian 开发者文档中的 [OAuth 2.0 (3LO) 应用程序](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)。

### 创建一个 OAuth 2.0 (3LO) 应用程序
<a name="atlassian-oauth-app"></a>

Amazon Quick 使用 Atlassian OAuth 2.0 (3LO) 应用程序代表您的用户使用您的 Atlassian Cloud 产品进行身份验证。在配置 Amazon Quick 之前，请在 Atlassian 开发者控制台中创建此应用程序。

1. 打开 [Atlassian 开发者控制台](https://developer.atlassian.com/console/myapps/)，然后使用您的 Atlassian 账户登录。

1. 选择 “**创建**”，然后选择 **OAuth 2.0 集成**。

1. 例如`your-app-name connector`，在**名称**中输入集成的描述性名称。

1. 查看并接受 Atlassian 开发者条款。

1. 选择**创建**。

### 配置 权限
<a name="atlassian-oauth-permissions"></a>

创建 OAuth 2.0 应用程序后，添加 Amazon Quick 与你的 Atlassian 产品交互所需的 API 权限。

1. 在 Atlassian 开发者控制台中的应用程序中，选择左侧**导航栏中的权限**。

1. **找到适用于你的 Atlassian 产品的 API（例如 **Jira API 或 **Confluence** API**），然后选择添加。**添加 API 后，按钮变为**配置**。

1. 选择**配置**。范围页面打开时会显示**经典作用域**和**精细范围**选项卡。

1. 在**经典范围**选项卡上，选择**编辑范围**。选择所需的经典示波器，然后选择**保存**。

1. 选择**精细范围**选项卡，然后选择**编辑范围**。选择所需的粒度范围，然后选择**保存**。

有关集成所需的特定范围，请参阅后面的作用域部分。

### 配置 API 权限
<a name="jira-oauth-scopes"></a>

将以下范围添加到您的 OAuth 2.0 应用程序中，以实现 Jira Cloud 操作集成。

**经典瞄准镜**

在 “**经典范围**” 选项卡上，选择 **“编辑范围**”，然后选择以下范围。


**Jira 动作集成 — 经典范围**  

| Scope | 说明 | 
| --- | --- | 
| read:jira-work | 阅读 Jira 项目和事务数据，搜索议题以及与议题相关的对象，例如附件和工作日志。 | 
| manage:jira-project | 创建和编辑项目设置并创建新的项目级对象（例如，版本和组件）。 | 
| manage:jira-configuration | 采取 Jira 管理操作（例如，创建项目和自定义字段、查看工作流程、管理事务链接类型）。 | 
| read:jira-user | 在 Jira 中查看用户有权访问的用户信息，包括用户名、电子邮件地址和头像。 | 
| write:jira-work | 在 Jira 中创建和编辑议题，以用户身份发表评论，创建工作日志，删除议题。 | 
| manage:jira-webhook | 获取、注册、刷新和删除动态声明的 Jira Webhook。 | 

**精细瞄准镜**

选择**精细范围**选项卡，然后选择**编辑范围**。使用搜索栏查找以下范围。例如，搜索`sprint:jira-software`以查找与冲刺相关的范围。


**Jira 操作集成 — 精细范围**  

| Scope | 说明 | 
| --- | --- | 
| read:board-scope:jira-software | 阅读主板配置。 | 
| read:sprint:jira-software | 阅读冲刺信息。 | 
| write:sprint:jira-software | 创建和修改冲刺。 | 
| delete:sprint:jira-software | 删除冲刺。 | 
| write:board-scope:jira-software | 管理主板配置。 | 
| read:project:jira | 阅读项目详情。 | 

### 配置授权
<a name="atlassian-oauth-authorization"></a>

设置回传网址，以便 Atlassian 可以在用户授权应用程序后将其重定向回 Amazon Quick。

1. 在 Atlassian 开发者控制台中的应用程序中，选择左侧**导航栏中的授权**。

1. 在 **OAuth 2.0 (3LO)** 旁边，选择**添加**。

1. 在**回**拨 URLs中，输入`https://region.quicksight.aws.amazon.com/sn/oauthcallback`。例如，*region*替换为部署您的 Amazon Quick 实例的 Amazon 区域`us-east-1`。

1. 选择**保存更改**。

### 记录您的凭证
<a name="atlassian-oauth-credentials"></a>

在离开 Atlassian 开发者控制台之前，请确认您具有以下值。您需要它们来配置 Amazon Quick。

1. 在 Atlassian 开发者控制台中的应用程序中，选择左侧**导航栏中的设置**。

1. 在 “**身份验证详细信息**” 下，复制 “**客户端 ID**” 和 “**密钥**” 值。


**来自 Atlassian 开发者控制台的所需凭证**  

| 值 | 在哪里可以找到它 | 
| --- | --- | 
| 客户端 ID | 设置页面，在 “身份验证详情” 下 | 
| Secret | 设置页面，在 “身份验证详情” 下 | 

## 在 Amazon Quick 中设置集成
<a name="jira-integration-setup"></a>

准备好身份验证凭证后，在 Amazon Quick 中创建集成。

1. 在 Amazon Quick 控制台中，选择**集成。**

1. 选择**操作**选项卡。

1. 在 “**为操作设置新的应用程序集成**” 下，找到 **Atlassian Jira Cloud**，然后选择添加（加上 “\$1”）按钮。

1. 在**创建集成**向导中，填写以下字段：
   + **名称**-您的 Jira 集成的描述性名称。
   + **描述**（可选）-有关如何使用此连接的说明。
   + **连接类型**-选择**公共网络**。

1. 在 **“身份验证设置”** 下，选择您的身份验证方法并填写必填字段：

   1. 对于**用户身份验证**，请配置以下字段：
      + **基本网址** — 用于调用 API 的 Jira 实例网址。这与用户登录的 URL 不同。它类似于以下内容:`https://api.atlassian.com/ex/jira/yourInstanceId`. 要查找您的实例 ID，请导航至`https://your-domain.atlassian.net/_edge/tenant_info`。
      + **客户端 ID** — 来自 Atlassian 应用程序的 “设置” 页面的客户端 ID。 OAuth 
      + **客户密钥**-来自 Atlassian 应用程序的 “设置” 页面的密钥。 OAuth 
      + **代币网址** — `https://auth.atlassian.com/oauth/token`
      + **授权网址** — `https://auth.atlassian.com/authorize`
      + **重定向 URL** — 此字段已预先填充您的 Amazon Quick 回传网址。

   1. 对于**服务身份验证**，请配置以下字段：
      + **API 密钥** — Jira API 令牌。
      + **基本网址** — 用于调用 API 的 Jira 实例网址。
      + **电子邮件**-关联用户帐户电子邮件。

1. 选择**创建并继续**。

1. （可选）在**共享集成**页面上，选择要与之共享集成的用户。

**重要**  
即使 API 令牌被撤销或配置不当，Jira Cloud 也可能返回 HTTP 200 成功响应。有关更多信息，请参阅 [JRACLOUD-82932](https://jira.atlassian.com/browse/JRACLOUD-82932)。如果您的集成似乎成功连接，但操作意外失败，请验证您的 API 令牌是否有效且未被撤销。

## 可用操作
<a name="jira-integration-actions"></a>

设置集成后，可以使用以下操作。


**Jira Cloud 的可用操作**  

| Action | 说明 | 
| --- | --- | 
| 添加附件 | 为议题添加附件。 | 
| 添加评论 | 添加新评论。 | 
| 更改问题状态 | 更改议题的任务状态。 | 
| 创建问题 | 创建新议题或子任务。 | 
| 创建项目 | 创建新项目。 | 
| 创建冲刺 | 在项目中创建冲刺。 | 
| 删除评论 | 移除评论。 | 
| 删除问题 | 删除项目中的议题。 | 
| 删除项目 | 移除项目。 | 
| 删除 Sprint | 删除项目中的冲刺。 | 
| 编辑问题 | 修改问题。 | 
| 查找用户 | 搜索 Jira 用户。 | 
| 获取所有标签 | 查看所有标签。 | 
| 获取所有用户 | 列出所有 Jira 用户。 | 
| 获取附件内容 | 查看附件的内容。 | 
| 获取评论 | 查看问题评论。 | 
| 获取问题 | 查看项目中某个问题的详细信息。 | 
| 获取项目的问题类型 | 查看项目问题类型。 | 
| 获取优先级 | 查看问题优先级。 | 
| 获取项目 | 查看项目详情。 | 
| 开始冲刺吧 | 查看项目中冲刺的详细信息。 | 
| 将议题移至待办事项列表 | 将议题移至待办事项列表。 | 
| 将问题移至 Sprint 并进行排名 | 将议题分配给冲刺。 | 
| 搜索问题 | 搜索问题。 | 
| 搜索项目 | 查找可见的项目。 | 
| 搜索状态 | 搜索问题状态。 | 
| 更新评论 | 编辑评论。 | 
| 更新项目 | 修改项目。 | 
| 更新 Sprint | 更新冲刺详情。 | 

**注意**  
您可以使用的操作取决于您的 Jira Cloud 实例中配置的权限和身份验证方法。

## 管理和故障排除
<a name="jira-integration-troubleshooting"></a>

要编辑、共享或删除您的集成，请参阅[管理现有集成](integration-workflows.md#managing-existing-integrations)。

### 身份验证问题
<a name="jira-troubleshooting-auth"></a>
+ **应用程序配置不正确**-验证 Atlassian 开发者控制台中的 OAuth 应用程序是否包含所需的范围，并且重定向 URI 是否与您的 Amazon Quick 配置相匹配。
+ **API 令牌已过期或已撤销** — 如果使用服务身份验证，请检查 API 令牌是否已过期或已撤销。由于已知的 Jira Cloud 行为 ([JRACLOUD-82932](https://jira.atlassian.com/browse/JRACLOUD-82932))，即使使用无效的令牌，集成也可能看起来成功连接。
+ **基本网址不正确** — API 调用的基本网址与 Jira Cloud 登录网址不同。确认您使用的是 API 网址格式：`https://api.atlassian.com/ex/jira/yourInstanceId`。要查找您的实例 ID，请导航至`https://your-domain.atlassian.net/_edge/tenant_info`。

### 常见错误消息
<a name="jira-troubleshooting-errors"></a>
+ **`Access denied. You do not have permission to perform this action`**— 经过身份验证的用户在 Jira Cloud 中没有所需的权限。请联系您的 Jira Cloud 管理员以验证并授予相应的权限。
+ **`OAuth 2.0 authorization failed`**— 验证在 Atlassian 开发者控制台和 Amazon Quick 中是否正确配置了客户端 ID、客户端密钥和 OAuth 范围。