此页面由 Cloud Translation API 翻译。

添加 Jira Cloud 操作

启用 Jira 操作后，最终用户可以要求助理执行以下 Jira Cloud 操作：

创建 Jira 问题
修改 Jira 问题

例如，用户可以在您的应用中输入“在项目 ABC 中创建一个名为‘启动项目 Y’的 Jira 故事”或“将 Jira 工单 JCD-1 的标题更新为‘启动项目 Y’”。助理会根据需要询问更多详细信息，然后要求用户确认创建或修改请求。

助理可以通过操作读取和修改以下 Jira 字段：

字段	说明
问题 ID	必需。要修改的问题的 ID，例如 KAN-123。
标题	问题标题。
问题类型	问题类型。
优先级	问题优先级。
状态	问题状态。
说明	采用 Markdown 格式的问题描述。
组件	问题组件。
接收方	问题的指派对象，例如 user@google.com。

在 Jira 中设置身份验证和权限

在启用 Jira 操作之前，Jira 管理员必须在 Jira 中为操作设置专用的 OAuth 2.0 凭据。这是连接 Jira 集成并允许对操作进行读写所必需的。

Jira 操作的授权客户端与用于提取 Jira 数据的授权客户端不同。它们使用不同的权限和不同的回调网址配置。如需了解如何为 Jira Cloud 连接器设置授权客户端以提取数据，请参阅连接 Jira Cloud。

以下说明介绍了如何通过 Atlassian 开发者控制台创建客户端 ID 和客户端密钥、配置所需的 OAuth 2.0 范围，以及为用户设置权限。最后，检索实例网址和 ID，配置角色，并进行身份验证，以便在 Jira Cloud 和 Google 之间读取和写入数据。

创建客户端 ID 和客户端密钥

登录 developer.atlassian.com。
点击右上角的个人资料图标，然后选择开发者控制台。
点击创建，然后选择 OAuth 2.0 集成。
输入应用的名称。
- 勾选条款及条件复选框。
- 点击创建。
点击授权。
在授权类型表中，选择 OAuth 2.0 (3LO) 对应的添加。
在回调网址字段中，输入 https://vertexaisearch.cloud.google.com/oauth-redirect，然后点击保存更改。
点击权限：
1. 前往 Jira API，点击添加，然后点击配置。
2. 前往传统范围标签页，然后点击修改范围。选择以下范围，然后保存更改：
  - 传统范围：
    - read:jira-work
    - read:jira-user
    - write:jira-work
  - 精细范围：
    - read:user:jira
点击分发，选择修改，然后执行以下操作：
1. 首先选择共享单选按钮，以便修改其他字段。
2. 填写其余字段。
  1. 在供应商部分，选择 Google。
  2. 在隐私权政策部分，输入 https://policies.google.com。
  3. 在您的应用是否会存储个人数据？部分，选择 Yes。
  4. 选中我确认已实现个人数据报告 API 复选框。
3. 点击保存更改。
选择设置以复制您的客户端 ID 和客户端密钥。

检索实例网址和实例 ID

如需获取实例网址，请执行以下操作：

访问 atlassian.net，然后使用您的管理员账号登录。
选择要同步的应用。例如，同步第一个应用。
找到实例网址（地址栏中的子网域）。

如需获取实例 ID，请执行以下操作：

打开一个新标签页，将实例网址复制进去，并在实例网址末尾添加 /_edge/tenant_info。例如 https://YOUR-INSTANCE.atlassian.net/_edge/tenant_info。
点击相应链接，找到 cloudId 值。cloudId 是您的实例 ID。

设置权限和角色

使用您的管理员账号登录 atlassian.com。
点击左上角的菜单图标，或前往 admin.atlassian.com。
在管理页面上，点击管理用户，然后前往群组页面。
点击创建群组。为群组输入名称并创建群组。
在新群组的群组产品访问权限部分中，点击向群组添加产品。
对于 Jira，选择 User access admin 作为产品角色。
对于 Jira Admin，请选择 Product admin 作为产品角色，然后保存更改。
在群组页面上，点击添加群组成员，然后添加连接器将进行身份验证的用户或账号。

获取刷新令牌

如果您计划使用 Google Cloud 控制台配置 Jira 操作，则无需获取刷新令牌。

如果您需要使用 API 来配置 Jira 操作，则需要刷新令牌。如需获取刷新令牌，请执行以下操作：

前往 Google Cloud 控制台中的应用。
选择授权。
选择 OAuth 2.0 (3LO) 旁边的配置。
对于重定向网址，请使用占位网址，例如 https://example.com。
如需在初始授权流程中获取刷新令牌，请将 offline_access 添加到授权网址的 scope 参数中。例如： https://auth.atlassian.com/authorize?audience=api.atlassian.com&client_id=your_client_id**&scope=offline_access**%20read%3Ajira-user&redirect_uri=https%3A%2F%2Fyour-redirect-url&state=%24%7BYOUR_USER_BOUND_VALUE%7D&response_type=code&prompt=consent
获得授权后，系统会将您重定向回重定向网址。在地址栏中，您应该会看到一个名为“code”的查询参数。记下其值。
使用 curl 或 Postman 等工具向 https://auth.atlassian.com/oauth/token 发送 POST 请求，其中包含具有以下键的 JSON 对象：
1. grant_type：authorization_code
2. client_id：您的客户端 ID
3. client_secret：您的客户端密钥
4. code：您在第 6 步中获得的代码
5. redirect_uri：您的重定向 URI
您将在响应中获得 refresh_token

如需详细了解刷新令牌，请参阅 Atlassian 文档中的实现刷新令牌流程。

配置 Jira 操作

本部分介绍如何为动作创建 Jira 连接器，以及如何为助理启用 Jira 动作。

准备工作

在配置操作之前，请确保完成以下步骤：

您的项目必须添加到助理操作的许可名单中
Jira 管理员已完成在 Jira 中设置身份验证和权限中的步骤，并向您提供了以下信息：
- 客户端 ID
- 客户端密钥
- 实例 ID
- 刷新令牌。仅在通过 API（而非通过 Google Cloud 控制台）创建 Jira 操作时需要。Google 建议通过 Google Cloud 控制台创建操作。

在 Google Cloud 控制台中配置 Jira 操作

Google 建议通过 Google Cloud 控制台创建操作。

如需使用控制台向应用添加操作，请执行以下操作：

在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。
前往相应应用。
在导航菜单中，点击操作。
对于 Jira，请点击关联。
选择一个 Jira 实例。
如果系统提示，请输入连接器的授权信息。仅当实例尚未配置任何操作时，才需要执行此步骤。
选择要启用的操作。
点击完成设置。您的操作会显示在操作页面上。

使用 API 创建和启用 Jira 操作

Google 建议您通过 Google Cloud 控制台创建操作。如果您需要使用 API 创建操作，请执行以下操作：

创建 Jira 连接器并将其配置为用于搜索：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-GFE-SSL: yes" \
-H "X-Goog-User-Project: PROJECT_NUMBER" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/global:setUpDataConnector" \
-d '{
  "collectionId": "COLLECTION_ID",
  "collectionDisplayName": "COLLECTION_DISPLAY_NAME",
  "dataConnector": {
    "dataSource": "jira",
    "params": {
      "client_id": "{Client ID of your Jira integration}",
      "client_secret": "{Client Secret of your Jira integration}",
      "refresh_token": "{Refresh Token of your Jira integration}",
      "instance_id": "{Your Jira Cloud instance ID}"
    },
    "refreshInterval": "{ >1800 }s",
    "entities": [
      {
        "entityName" : "project",
        "params" : {
          "inclusion_filters" : {}
        }
      },
      {
        "entityName": "{attachment/comment/issue/worklog}" // Optional, you can build up to 4 different entities
      }
    ],
    "syncMode": "PERIODIC"
  }
}

替换以下内容：

PROJECT_NUMBER：您的 Google Cloud 项目的编号。
COLLECTION_ID：集合的 ID。
COLLECTION_DISPLAY_NAME：集合的显示名称。

在 Jira 连接器中添加操作配置：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "PROJECT_NUMBER")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/global/collections/COLLECTION_ID/dataConnector?update_mask=action_config" \
  -d '{
  "name": "projects/PROJECT_NUMBER/locations/global/collections/COLLECTION_ID/dataConnector",
  "action_config": {
    "is_action_configured": true,
    "action_params": {
        "client_id": "{Client id from Jira integration}",
        "client_secret": "{Client secret from Jira integration}",
        "instance_uri": "{instance URI of your Jira instance}"
      }
    }
  }'

为 Google 助理启用 Jira 操作：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "<var>PROJECT_NUMBER</var>")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant?update_mask=enabledActions" \
  -d '{
    "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant",
    "enabledActions": {
      "projects/PROJECT_NUMBER/locations/global/collections/CONNECTOR_ID/dataConnector": {
        "actionInfo": [
          {
            "actionName": "create_jira_issue",
            "actionDisplayName": "Create Jira Issue"
          }
        ]
      }
    }
  }'