关联 Jira Cloud

本页面介绍了如何将 Jira Cloud 连接到 Gemini Enterprise。

首次设置数据源并导入数据后，数据存储区会按照您在设置期间选择的频率同步来自该来源的数据。

支持的版本

Jira Cloud 连接器支持第 2 版 JIRA Cloud REST API。

准备工作

在设置关联之前，请先执行以下操作：

  • 确保您的 Atlassian 账号已设置为使用新的集中式用户管理模式。

  • 验证您是否对 Jira 实例和项目拥有 Jira 组织管理员访问权限。获得组织管理员访问权限后，您便可以设置最低权限，以及向用户群组提供访问权限。如需了解如何验证 Jira 组织管理员访问权限，请参阅验证 Jira 组织管理员访问权限。

  • （可选）如需从 Jira Cloud 获取用户邮箱信息（即使有设置限制了邮箱公开范围），请安装 User Identity Accessor for Jira Cloud 应用。您必须是 Jira 网站管理员 才能安装和配置此应用。安装此应用后，对其进行配置以安全地检索用户邮箱。如果邮箱信息已可供公开访问，则无需安装此应用。

  • 如需在 Gemini Enterprise 中强制执行数据源访问权限控制并保护数据安全，请确保您已配置身份提供方。

  • 如需启用 OAuth 2.0 并获取客户端 ID 和密钥，请参阅 Atlassian 开发者文档中的 OAuth 2.0 (3LO) 应用部分。

验证 Jira 组织管理员访问权限

  1. 使用您的用户凭证登录 Atlassian。

  2. 选择 Jira 应用。

    Atlassian 首页
    Atlassian 首页

  3. 点击设置。

    如果您在 Jira 设置下看到系统选项，则表明您拥有 Jira 组织管理员访问权限。否则，请让您的 Jira 组织管理员授予您相应访问权限。

    设置
    设置

创建 OAuth 2.0 集成

  1. 登录 Atlassian 开发者控制台。

  2. 点击个人资料图标，然后选择开发者控制台。

    选择开发者控制台
    选择开发者控制台

  3. 点击创建，然后选择 OAuth 2.0 集成。

    选择 OAuth 2.0 集成
    选择 OAuth 2.0 集成

  4. 为应用输入一个名称。

  5. 选中复选框以同意 Atlassian 的开发者条款。

  6. 点击创建。

    创建 OAuth 2.0
    创建新的 OAuth 2.0 集成

  7. 点击授权。

  8. 在授权类型表中，选择 OAuth 2.0 (3LO) 对应的添加。

    select-add
    添加授权类型

  9. 在回调网址字段中，输入 https://vertexaisearch.cloud.google.com/console/oauth/jira_oauth.html。

  10. 点击保存更改。

    保存更改
    保存更改

配置应用所需的最低权限

  1. 在应用页面上，点击权限。

    选择权限
    选择权限

  2. 前往 Jira API，然后点击添加。

  3. 点击配置。

  4. 前往传统范围标签页。

  5. 点击修改范围，然后选择以下权限：

    • read:jira-user
    • read:jira-work

    修改传统范围
    修改传统范围

  6. 确认已选择这两个范围，然后保存更改。

  7. 前往精细范围标签页。

  8. 点击修改范围，然后选择以下权限：

    • read:issue-security-level:jira
    • read:issue-security-scheme:jira
    • read:group:jira
    • read:user:jira
    • read:avatar:jira
    • read:audit-log:jira

    修改精细范围
    修改精细范围

最低权限

下表列出了创建 Jira Cloud 连接器所需的最低权限。

传统范围

权限 使用原因 说明
read:jira-work 数据注入 让连接器能够读取实体的详细信息（包括问题、附件、评论和属性）。
read:jira-user 强制实施访问控制列表 (ACL) 让连接器能够读取用户和群组详细信息。

精细范围

权限 使用原因 说明
read:issue-security-level:jira 强制实施 ACL 根据问题的具体安全等级，对问题强制实施 ACL。
read:issue-security-scheme:jira 强制实施 ACL 根据问题关联的安全方案，对问题强制实施 ACL。
read:group:jira 强制实施 ACL 让连接器能够读取群组信息，以便强制实施与群组成员资格相关的 ACL。
read:user:jira 强制实施 ACL 让连接器能够读取用户信息，以便强制实施个人与用户权限相关的 ACL。
read:avatar:jira 强制实施 ACL 让连接器能够读取用户和群组信息以强制实施 ACL。不会使用头像，但它是与群组和用户捆绑在一起的精细范围的一部分。
read:audit-log:jira 监控 ACL 让连接器能够读取 Jira 的审核日志，以便验证和监控 ACL。

获取客户端 ID 和客户端密钥

  1. 点击分发，然后选择修改。
  2. 选择共享，以便修改其他字段。
  3. 填写剩余字段：
    1. 在供应商部分，输入 Google。
    2. 在隐私权政策部分，输入 https://policies.google.com。
    3. 在您的应用是否会存储个人数据？部分，选择是。
    4. 选中我确认已实现个人数据报告 API 复选框。如需了解详情，请参阅个人数据报告 API。
      修改分发
      修改分发

  4. 点击保存更改。

  5. 点击设置以复制您的客户端 ID 和客户端密钥。

    复制客户端 ID 和客户端密钥
    复制您的客户端 ID 和客户端密钥

获取实例 ID 和实例网址

  1. 获取实例 ID：

    1. 打开一个新标签页，复制实例网址，然后将 /_edge/tenant_info 附加到实例网址。例如 https://YOUR_INSTANCE.atlassian.net/_edge/tenant_info。

    2. 点击相应链接，找到 cloudId 值。cloudId 便是您的实例 ID。

      select
      获取实例 ID

  2. 获取实例网址：

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

授予管理员角色

如需在 Google Cloud 控制台中向 Jira 管理员授予 Discovery Engine Editor 角色，请执行以下操作：

  1. 在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

  2. 前往 IAM。

    转到 IAM

  3. 找到在 Jira 中具有管理员访问权限的用户账号，然后点击修改图标 。

  4. 向管理员授予 Discovery Engine Editor 角色。

如需向用户授予 Atlassian 管理员角色，请执行以下操作：

  1. 使用组织管理员账号登录 Atlassian。

  2. 点击菜单图标，然后选择您的组织。或者，您也可以访问 admin.atlassian.com。

  3. 在管理页面上，点击相应产品，然后选择管理用户按钮。

    manage-users
    管理用户

  4. 在用户管理下，点击群组。

  5. 在群组页面上：

    1. 点击创建群组。
    2. 为该节点组输入一个名称。

    create-group
    创建群组

此群组会获得连接器所需的权限。添加到此群组的用户会继承这些权限。连接器会使用此群组进行身份验证和提取文档。

  1. 在群组页面上，点击添加产品。

  2. 为 Jira 选择 User access admin 角色。

  3. 为 Jira 管理 选择 Product admin 角色。

    jira-user-access-admin
    Jira 用户访问权限管理员

  4. 点击授予访问权限。

  5. 点击添加群组成员，添加连接器用于进行身份验证和访问所需资源的用户账号或群组成员。

    add-group-members
    添加群组成员

管理用户公开范围

如需让 Atlassian 账号中的任何人都能看到用户的邮箱，请按以下步骤操作：

  1. 登录 Atlassian 开发者控制台。

  2. 点击个人资料图标，然后选择开发者控制台。

  3. 点击用户个人资料图标，然后选择管理账号。

    管理账号
    管理账号

  4. 前往个人资料和公开范围。

    profile-visibility
    个人资料和公开范围

  5. 前往联系信息，将谁可以查看此信息设置为任何人。

    联系人
    联系

如需让 Jira 中的任何人都能看到用户的邮箱，请按以下步骤操作：

  1. 使用您的用户凭证登录 Atlassian。

  2. 选择一个 Jira 应用。

  3. 依次点击设置 > 系统。

  4. 在左侧窗格中，选择常规配置。

  5. 点击 Edit Settings（修改设置）。

  6. 在用户邮箱公开范围部分，选择公开。

    选择电子邮件地址公开范围
    选择电子邮件地址公开范围

  7. 点击更新。

安装和配置 User Identity Accessor for Jira Cloud

如果由于 Jira Cloud 中的隐私设置，导致用户邮箱信息默认情况下无法公开访问，那么您必须安装 User Identity Accessor for Jira Cloud 应用才能安全地检索用户邮箱信息。如果用户邮箱信息已公开显示，则您可能不需要安装该应用。如需详细了解邮箱信息受限公开范围相关的设置，请参阅管理用户公开范围。

角色与权限

如需安装和配置 User Identity Accessor for Jira Cloud 应用，您必须拥有相应的管理员角色并授予所需的应用级权限。

  • 所需角色：您必须是 Jira Site administrator 才能安装和配置该应用。
  • 应用级权限：您必须在应用安装期间授予以下权限：
    • Read Email Address：让应用能够安全地检索用户邮箱信息，即使用户的个人资料公开范围受到限制也是如此。
    • App Storage scope：让应用能够读取和写入其存储设备。

安装 User Identity Accessor for Jira Cloud

如需在 Jira 网站上安装 User Identity Accessor for Jira Cloud 应用，请按以下步骤操作：

  1. 前往 Atlassian 开发者控制台。

  2. 查看读取电子邮件地址和应用存储范围权限，然后点击获取应用。

    configure-uia-button-jira
    查看权限并获取应用

  3. 在选择要安装此应用的网站列表中，选择要安装该应用的 Jira 网站。此列表仅显示您拥有管理员访问权限的网站。

    注意：您必须是至少一个 Jira 网站的管理员，才能安装该应用。

  4. 点击安装以完成应用安装。

配置 User Identity Accessor for Jira Cloud

安装 User Identity Accessor for Jira Cloud 应用后，请配置一个 API 密钥，供您的外部系统（例如 Jira Cloud 连接器）用于安全地调用该应用的 Web 触发器来提取邮箱信息。

访问配置页面

如需访问 User Identity Accessor for Jira Cloud 应用的配置页面，请按以下步骤操作：

  1. 在 Jira Cloud 实例中，点击导航菜单中的设置 ⚙️ 图标。
  2. 从菜单中选择应用。
  3. 在应用管理页面上，从管理应用列表中找到 User Identity Accessor for Jira Cloud 应用。

  4. 点击配置或与您的应用相关联的链接。Jira Cloud 中随即会打开该应用的专用配置页面。

    configure-uia-button-jira
    配置 User Identity Accessor for Jira Cloud 应用

设置 API 密钥

如需在配置页面上设置 API 密钥，请按照以下步骤操作：

  1. 在 API 密钥配置部分，指定用于对向应用的 Web 触发器发出的请求进行身份验证的密钥。您可以使用以下任一方法对请求进行身份验证：

    • 输入您自己的密钥：在“API 密钥”字段中输入或粘贴您自己的唯一强 API 密钥。使用至少包含 20-30 个字符的密钥，其中混合使用大写字母、小写字母、数字和符号。

      save-key
      输入您自己的密钥

    • 生成密钥：点击生成新密钥按钮。系统会在该字段中生成并显示一个随机强密钥。

      generate-key
      生成密钥

      重要提示：请立即复制该字段中显示的 API 密钥。出于安全考虑，保存或离开此页面后，您可能无法再次查看完整密钥。如果该密钥丢失，您需要设置或生成一个新密钥。

  2. 点击保存 API 密钥。成功保存后，系统会显示一条消息确认密钥已安全保存。

测试应用配置

通过从外部系统发送请求并确认用户邮箱成功返回，验证 User Identity Accessor for Jira Cloud 应用已正确配置。

获取 Web 触发器网址
  1. 在应用管理页面上，找到 Web 触发器网址部分，其中显示了您的 Jira 网站和此应用安装的专属唯一网址：
    • 您的外部系统必须调用此网址才能请求获取用户邮箱。
    • 该网址通常如下所示：http://uuid/domain.net/x1/randomId。例如 https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID，其中 YOUR_INSTANCE_ID 是您的 Jira Cloud 实例标识符，WEBTRIGGER_ID 是为您的应用生成的 Web 触发器端点的唯一标识符。
  2. 点击复制网址按钮或复制整个网址。
配置外部系统

  • 使用在上文所述步骤中获得的 API 密钥和 Web 触发器网址配置需要提取 Jira 用户邮箱的外部系统。

  • 端点网址：您复制的 Web 触发器网址。

  • HTTP 方法：POST

  • 所需标头：

    • Content-Type：application/json

    • X-Api-Key：YOUR_API_KEY

      将 YOUR_API_KEY 替换为您在设置 API 密钥部分中设置或生成的 API 密钥。

示例 curl 命令

此示例演示了如何调用 User Identity Accessor for Jira Cloud 的 Web 触发器，该触发器会接受一组账号 ID 并返回相应的邮箱。

curl --location --request POST 'https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/ENDPOINT_PATH' \
--header 'X-Api-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
   "accountIds": [
       "ACCOUNT_ID_1",
       "ACCOUNT_ID_2"
   ]
}'

您需要进行如下替换：

  • 将 YOUR_INSTANCE_ID 替换为您的 Jira Cloud 实例 ID
  • 将 ENDPOINT_PATH 替换为 API 端点路径
  • 将 YOUR_API_KEY 替换为您在设置 API 密钥部分中设置或生成的 API 密钥
  • 将 ACCOUNT_ID 替换为要作为目标的 Atlassian 账号 ID
预期响应
[{"accountId":"ACCOUNT_ID_1","emailAddress":"EMAIL_ADDRESS_1"},
 {"accountId":"ACCOUNT_ID_2","emailAddress":"EMAIL_ADDRESS_2"}]

您需要进行如下替换：

  • 将 ACCOUNT_ID_X 替换为实际的 Atlassian 账号 ID
  • 将 USER_EMAIL_X 替换为通过 API 调用返回的用户邮箱

实施安全方面的最佳实践

为确保 API 密钥的安全，请遵循以下建议：

  • 在 Jira Cloud 连接器的配置中安全地存储 API 密钥。
  • 验证与网络钩子网址的所有通信是否都是通过 HTTPS 进行。这是 User Identity Accessor for Jira Cloud Web 触发器的默认设置。

为 User Identity Accessor for Jira Cloud 提供支持

Google 为 User Identity Accessor for Jira Cloud 应用提供了多种支持服务，包括维护和定期更新，以确保应用保持最新状态。如果您遇到任何问题或对应用功能有具体疑问，请与 Google Cloud 支持团队联系。如需了解详情，请参阅获取 Cloud Customer Care 支持服务。

创建 Jira Cloud 数据存储区

控制台

如需使用 Google Cloud 控制台将 Jira Cloud 中的数据同步到 Gemini Enterprise，请按照以下步骤操作：

  1. 以拥有组织管理员凭证的用户身份登录 Atlassian 网站。

  2. 在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

    Gemini Enterprise

  3. 在导航菜单中，点击数据存储区。

  4. 点击 创建数据存储区。

  5. 在选择数据源页面上，滚动或搜索 Jira Cloud 以连接第三方来源，然后点击选择。

  6. 在身份验证设置部分，输入实例 URI、实例 ID、客户端 ID 和客户端密钥。

  7. 点击 Login（登录）。

  8. 验证您已以管理员用户身份登录，选择将使用该应用的站点，点击接受。

    选择网站
    选择要使用该应用的网站

  9. 点击继续。

  10. 在高级选项部分中：

    • 可选。如要允许系统使用一组静态 IP 地址，请在注册时选择启用静态 IP 地址。

    • 在 QPS 上限字段中，输入一个整数来定义每秒发送到 Jira Cloud 实例的查询次数上限。默认值为 12 QPS。

    • 在 Jira Identity Sync Forge 网址字段中，输入由 User Identity Accessor for Jira Cloud 应用生成的网址。

    • 在 Jira Identity Sync Forge 客户端密钥字段中，输入在 User Identity Accessor for Jira Cloud 中配置的客户端密钥，即您在设置 API 密钥部分中生成或创建的 API 密钥。

    • 点击继续。

  11. 在要同步的实体部分中，执行以下操作：

    1. 选择要同步的实体：

      • 问题

      • 附件

      • 备注

      • 工作日志

    2. （可选）如需同步特定项目，请执行以下操作：

      1. 点击过滤。
      2. 如需将实体从索引中排除，请选择从索引中排除；如需确保实体被纳入索引中，请选择纳入索引中。
      3. 输入项目键。每输入一个项目键后按 Enter 键。
      4. 点击保存。

    指定用于包含或排除实体的过滤条件
    指定用于包含或排除实体的过滤条件。

  12. 点击继续。

  13. 为完全同步选择同步频率，为增量数据同步选择增量同步频率。如需了解详情，请参阅同步时间表。

    如果您想分开安排实体数据和身份数据的完全同步，请展开完全同步下的菜单，然后选择自定义选项。

    用于设置数据的完全同步的自定义选项。
    为完全实体同步和完全身份同步单独设置时间表。

  14. 点击继续。

  15. 在配置数据连接器部分：

    1. 为您的数据存储区选择一个区域。您以后无法更改该区域。如需详细了解多区域位置，请参阅 Gemini Enterprise 位置。

    2. 为数据连接器输入名称。 您日后可以更改此名称。

    3. 可选。如要在输入名称后更改数据连接器 ID，请点击修改并更改相应值。创建数据存储区后，便无法更改数据连接器 ID。

    4. 点击创建。Gemini Enterprise 会创建数据存储区，并将其显示在数据存储区页面上。

如需查看数据注入状态，请前往数据存储区页面，然后点击数据存储区名称，在其数据页面查看相关详情。当连接器开始同步数据时，连接器状态会从正在创建变为正在运行。注入完成后，状态会变为活跃，表明已设置与数据源的连接，并且正在等待下一次预定同步。注入过程可能需要几分钟或几小时才能完成，具体取决于数据的大小。

如需详细了解配额（包括默认限制和有关申请更高配额的说明），请参阅配额和限制。

启用实时同步

实时同步只会同步文档实体，不会同步与身份实体相关的数据。下表显示了哪些文档事件支持实时同步。

Jira 实体 创建 更新 删除 权限更改
问题
工作日志
项目
备注
附件

如需为 Jira Cloud 数据源连接器启用实时同步，请按以下步骤操作：

生成网络钩子网址

  1. 前往 Gemini Enterprise 页面，在导航菜单中点击数据存储区。
  2. 选择一个 Jira Cloud 数据存储区。

  3. 在实时同步行中，点击查看/修改。

    Jira Cloud 实时同步
    实时同步：已停用状态

  4. 在查看和修改实时同步参数对话框中，执行以下操作：

    1. 如需开启实时同步，请点击启用实时同步切换开关。
    2. 在客户端密钥字段中输入一个值，然后复制该值。在 Jira 管理控制台中创建网络钩子时，您需要再次使用该值。
    3. 点击保存。
      Jira Cloud 启用实时同步
      启用实时同步

  5. 当实时同步的状态变为 Running 后，点击查看/修改。

    正在运行
    实时同步：运行状态

  6. 在查看和修改实时同步参数对话框中，执行以下操作：

    1. 复制 Webhook 网址。
    2. 点击关闭。
      Jira Cloud 复制网络钩子网址
      复制 Webhook 网址

创建网络钩子

  1. 登录 Jira 管理控制台。
  2. 点击设置，然后选择系统。
  3. 在系统设置窗格中，选择网络钩子。
  4. 点击创建网络钩子。如需了解网络钩子，请参阅网络钩子。
  5. 为网络钩子输入一个名称。
  6. 将状态选择为 Enabled。
  7. 在网址字段中，粘贴从 Gemini Enterprise 复制的网址，然后附加 /{issue.id}。

  8. 在密钥字段中，输入您在 Gemini Enterprise 中生成网络钩子网址时输入的相同值。

    Jira 管理员设置 Webhook
    网络钩子

  9. 在问题相关事件部分，选择以下选项：

    实体 已创建 已更新 已删除
    问题 是 是 是
    工作日志 是 是 是
    评论 是 是 是
    附件 是 否 是

    Jira 管理员问题相关事件
    与问题相关的事件

  10. 在项目相关事件部分，为项目实体选中已创建、已更新和已删除复选框。

  11. 点击创建。

错误消息

下表列出了将 Jira Cloud 与 Gemini Enterprise 相关联时可能会出现的常见错误消息及其说明和可能的解决方法。

错误代码 错误消息 说明 问题排查
JIRA_INVALID_AUTH_1 OAuth 设置失败。 令牌刷新调用遇到问题，可能与凭证、Secret Manager 或连接有关。 完整错误消息中提供了异常详细信息。可能的原因和解决方法包括：
  • 连接问题：通常通过内部重试可以解决此类问题。
  • 凭证无效：验证或更正凭证。
JIRA_INVALID_AUTH_2 身份验证失败。 连接器无法向 Jira Cloud 进行身份验证，因为用户账号缺少足够的 API 访问权限。 使用管理员凭证重新向数据存储区进行身份验证。
JIRA_MISSING_PERMISSION_1 非管理员用户无权获取问题相关安全机制的信息。 没有管理员权限的用户账号尝试获取问题相关安全机制的信息。 向相关用户账号授予必要的管理员权限。
JIRA_MISSING_PERMISSION_2 非管理员用户无法获取权限方案。 没有管理员权限的用户账号尝试获取权限机制信息。 向相关用户账号授予必要的管理员权限。
JIRA_MISSING_PERMISSION_3 提取项目权限时出现问题。 没有管理员权限的用户账号尝试检索项目详细信息。 向相关用户账号授予必要的管理员权限。
JIRA_IO_CONNECTION 关联到 Jira 时出现问题。 连接器未能关联到 Jira Cloud 实例，并表示无法与 Jira 服务器建立或保持通信。 验证 Jira 网址，并仔细检查您的身份验证凭证。验证 Jira 实例是否正常运行，以及 API 令牌或 OAuth 范围是否授予了必要的权限。
JIRA_INVALID_INSTANCE_ID 未能从 Jira 实例中提取必需的详细信息。请检查 Jira 实例 ID。Jira 实例 ID 必须是 UUID。 系统无法从 Jira 实例检索必要的详细信息，因为提供的 Jira Cloud 实例 ID 无效。Jira 实例 ID 必须是 UUID。 确保您输入的实例 ID 是正确的 UUID。

已知限制

  • 对于非结构化数据，每种媒体类型都有不同的限制。如需了解详情，请参阅为自定义数据源准备数据。

  • 对于结构化数据，每个文档的大小不得超过 500 KB。

  • 具有特定（非空）角色的应用角色无法获授 Browse project 或安全级别权限。

  • 不支持通过用户自定义字段或群组自定义字段定义的文档权限。

  • Jira Cloud 不允许在工作日志级别施加任何限制。

  • Jira Cloud 不会将超过 2,000 页的 PDF 附件编入索引。

  • 添加到不公开评论中的附件不会继承评论的访问限制 (ACL)。

  • 系统只会提取 Jira Cloud 中问题的前 20 条评论。

  • 无法注入 Sprint 表。

  • 旧版用户管理模型不支持与 Jira Cloud 集成。仅支持集中式用户管理模型。如需了解详情，请参阅 Atlassian 组织整合指南。

后续步骤