本页面介绍了如何将 Confluence Cloud 连接到 Gemini Enterprise。
首次设置数据源并导入数据后,数据存储区会按照您在设置期间选择的频率同步来自该来源的数据。
支持的版本
Confluence Cloud 连接器支持 v1 和 v2 版 Confluence REST API。
准备工作
在设置关联之前,请先执行以下操作:
验证您是否对 Confluence 实例和项目拥有管理员访问权限。
(可选)如需从 Confluence Cloud 获取用户邮箱信息(即使有设置限制了邮箱公开范围),请安装 User Identity Accessor for Confluence Cloud 应用。您必须是
Confluence Site administrator
才能安装和配置此应用。安装此应用后,对其进行配置以安全地检索用户邮箱信息。如果邮箱信息可供公开访问,则无需安装此应用。授予 Discovery Engine Editor 角色 (
roles/discoveryengine.editor
)。用户必须具有此角色才能创建数据存储区。如需授予此角色,请执行以下操作:在 Google Cloud 控制台中,前往 IAM 页面。
找到相应用户账号,然后点击修改图标
。向用户授予 Discovery Engine Editor 角色。
如需在 Gemini Enterprise 中强制执行数据源访问权限控制并保护数据安全,请确保您已配置身份提供方。
在 Confluence 中设置身份验证和权限
您可以使用 OAuth 客户端凭证或基于 API 令牌的身份验证向 Confluence 进行身份验证。以下部分介绍了如何创建 OAuth 客户端凭证和 API 令牌。
创建 OAuth 客户端凭证
请按照以下说明创建客户端 ID 和客户端密钥、配置所需的 OAuth 2.0 范围、为用户设置权限、检索实例网址和 ID、配置角色,以及进行身份验证以在 Confluence Cloud 和 Gemini Enterprise 之间同步数据。如需启用 OAuth 2.0 并获取客户端 ID 和密钥,请参阅 Atlassian 开发者文档中的 OAuth 2.0 (3LO) 应用部分。
在 Atlassian 开发者控制台中创建 OAuth 2.0 集成:
- 登录 Atlassian 开发者控制台。
点击个人资料图标,然后选择开发者控制台。
选择 Play 管理中心 点击创建,然后选择 OAuth 2.0 集成。
选择 OAuth 2.0 集成 为应用输入一个名称,然后执行以下操作:
- 勾选条款及条件复选框。
点击创建。
创建新的 OAuth 2.0 集成 点击授权。
在授权类型表中,点击 OAuth 2.0 (3LO) 对应的添加。
添加授权类型
在回调网址字段中,输入
https://vertexaisearch.cloud.google.com/console/oauth/confluence_oauth.html
点击保存更改。
保存更改
如果您看到以下警告消息:您的应用没有任何 API。请向应用添加 API,请继续执行后续步骤来配置 OAuth 2.0。否则,请跳到该流程中的第 4 步。
如需配置 OAuth 2.0 并获取 Confluence 连接器设置所需的凭证,请执行以下操作:
启用 OAuth 2.0:
点击权限。
选择权限 前往 Confluence API。
点击添加。
点击配置。
前往精细范围标签页,然后点击修改范围。
修改范围 选择以下范围。
read:attachment:confluence
read:configuration:confluence
read:content.metadata:confluence
read:content-details:confluence
read:whiteboard:confluence
read:group:confluence
read:space:confluence
read:user:confluence
确认已选择这 8 个范围,然后保存更改。
获取客户端 ID 和客户端密钥:
- 点击分发。
选择修改。
修改分发 选择共享,以便修改其他字段。
填写剩余字段。请务必将供应商名称设置为 Google,并将隐私权政策设置为
https://policies.google.com
。在个人数据声明部分中,执行以下操作:
- 在您的应用是否会存储个人数据?列表中,选择是。
如需确认您已实现 Personal Data Reporting API,请选中我确认已实现 Personal Data Reporting API 复选框。
点击保存更改。
选择设置,然后复制客户端 ID 和客户端密钥字段中的值。
复制您的客户端 ID 和客户端密钥
获取实例网址:
- 访问 atlassian.net,然后使用您的管理员账号登录。
- 选择要同步的应用。例如,同步第一个应用。
- 找到实例网址。它会作为子网域显示在地址栏中。
获取实例 ID:
- 打开一个新标签页,将实例网址复制进去,并在实例网址末尾添加
/_edge/tenant_info
。例如https://<var>YOUR-INSTANCE</var>.atlassian.net/_edge/tenant_info
。 点击相应链接,找到
cloudId
值。cloudId
便是您的实例 ID。获取实例 ID
- 打开一个新标签页,将实例网址复制进去,并在实例网址末尾添加
最小 OAuth 范围
下表列出了创建 Confluence Cloud 连接器所需的最小 OAuth 范围:
权限 | 使用原因 | 说明 |
---|---|---|
read:content-details:confluence | 数据注入 | 让连接器能够读取 Confluence 中的内容详细信息。 |
read:content.metadata:confluence | 数据注入 | 让连接器能够读取内容元数据。 |
read:space:confluence | 数据注入 | 让连接器能够读取空间。 |
read:whiteboard:confluence | 数据注入 | 让连接器能够读取白板内容。 |
read:attachment:confluence | 数据注入 | 让连接器能够读取附件。 |
read:configuration:confluence | 强制实施 ACL | 对 Confluence 网站访问强制实施 ACL。 |
read:group:confluence | 强制实施 ACL | 对用户和群组详细信息读取强制实施 ACL。 |
read:user:confluence | 强制实施 ACL | 对用户详细信息读取强制实施 ACL。 |
在 Confluence 中设置 API 令牌
如果您计划使用 API 令牌进行身份验证,则必须创建没有范围限制的 API 令牌。此连接器不支持有范围限制的 API 令牌。
- 登录 Atlassian 控制台。
- 点击创建 API 令牌。
- 为 API 令牌输入一个名称。
- 为 API 令牌选择一个失效日期。令牌的有效期可为 1 到 365 天。
- 点击创建。
- 保存令牌以备后用。
获取实例网址
- 访问 atlassian.net,然后使用您的管理员账号登录。
- 选择要同步的应用。例如,同步第一个应用。
- 找到实例网址。它会作为子网域显示在地址栏中。
管理用户公开范围和授予角色
如需设置用户公开范围,请执行以下操作:
登录 Atlassian 开发者控制台。
点击用户个人资料图标,然后前往管理账号。
管理账号 前往个人资料和公开范围。
个人资料和公开范围 前往联系信息,将谁可以查看此信息设置为任何人。
联系
向用户授予管理员角色
(可选)您可以向其他用户授予 Atlassian 管理员角色。
使用管理员账号登录 Atlassian。
点击菜单图标,然后选择您的组织。或者,您也可以前往 admin.atlassian.com。
在应用页面上,点击 Confluence 旁边的 more_horiz(省略号图标),然后选择管理用户按钮。
管理用户 在用户管理下,点击群组。
在群组页面上:
- 点击创建群组。
- 为该节点组输入一个名称。
创建群组 此群组会获得连接器所需的权限。添加到此群组的用户会继承这些权限。连接器会使用此群组进行身份验证和提取文档。
在群组页面上,点击添加产品。
- 选择 User access admin 作为产品角色。
点击 Add(添加)。
Confluence 用户访问权限管理员
点击添加群组成员,添加连接器用于进行身份验证的用户账号或群组成员。
添加群组成员
安装和配置 User Identity Accessor for Confluence Cloud
如果由于 Confluence Cloud 中的隐私设置,导致用户邮箱信息默认情况下无法公开访问,那么您必须安装 User Identity Accessor for Confluence Cloud 应用才能安全地检索用户邮箱信息。如果用户邮箱信息已公开显示,则您可能不需要安装该应用。如需详细了解邮箱信息受限公开范围相关的设置,请参阅管理用户公开范围和授予角色。
角色与权限
如需安装和配置 User Identity Accessor for Confluence Cloud 应用,您必须拥有相应的管理员角色并授予所需的应用级权限。
- 所需角色:您必须是
Confluence Site administrator
才能安装和配置该应用。 - 应用级权限:您必须在应用安装期间授予以下权限:
Read Email Address
:让应用能够安全地检索用户邮箱信息,即使用户的个人资料公开范围受到限制也是如此。App Storage scope
:让应用能够读取和写入其存储设备。
安装 User Identity Accessor for Confluence Cloud
如需在 Confluence 网站上安装 User Identity Accessor for Confluence Cloud 应用,请按以下步骤操作:
- 前往 Atlassian 开发者控制台。
查看读取电子邮件地址和应用存储范围权限,然后点击获取应用。
查看权限并获取应用 在选择要安装此应用的网站列表中,选择要安装该应用的 Confluence 网站。此列表仅显示您拥有管理员访问权限的网站。
注意:您必须是至少一个 Confluence 网站的管理员,才能安装该应用。
点击安装以完成应用安装。
配置 User Identity Accessor for Confluence Cloud
安装 User Identity Accessor for Confluence Cloud 应用后,请配置一个 API 密钥,供您的外部系统(例如 Confluence Cloud 连接器)用于安全地调用该应用的 Web 触发器来提取邮箱信息。
访问配置页面
如需在 Confluence Cloud 中访问 User Identity Accessor for Confluence Cloud 应用的配置页面,请按以下步骤操作:
- 在 Confluence Cloud 实例中,点击导航菜单中的设置 ⚙️ 图标。
- 从菜单中选择应用。
- 在应用管理页面上,从管理应用列表中找到 User Identity Accessor for Confluence Cloud 应用。
点击配置或与您的应用相关联的链接。Confluence 中随即会打开该应用的专用配置页面。
配置 User Identity Accessor for Confluence Cloud 应用
设置 API 密钥
如需在配置页面上设置 API 密钥,请按照以下步骤操作:
在 API 密钥配置部分,指定用于对向应用的 Web 触发器发出的请求进行身份验证的密钥。您可以使用以下任一方法对请求进行身份验证:
输入您自己的密钥:在“API 密钥”字段中输入或粘贴您自己的唯一强 API 密钥。使用至少包含 20-30 个字符的密钥,其中混合使用大写字母、小写字母、数字和符号。
输入您自己的密钥 生成密钥:点击生成新密钥按钮。系统会在该字段中生成并显示一个随机强密钥。
生成密钥 重要提示:请立即复制该字段中显示的 API 密钥。出于安全考虑,保存或离开此页面后,您可能无法再次查看完整密钥。如果该密钥丢失,您需要设置或生成一个新密钥。
点击保存 API 密钥。成功保存后,系统会显示一条消息确认密钥已安全保存。
测试应用配置
通过从外部系统发送请求并确认用户邮箱成功返回,验证 User Identity Accessor for Confluence Cloud 应用已正确配置。
获取 Web 触发器网址
- 在应用管理页面上,找到 Web 触发器网址部分,其中显示了您的 Confluence 网站和此应用安装的专属唯一网址:
- 您的外部系统必须调用此网址才能请求获取用户的邮箱信息。
- 该网址通常如下所示:
http://uuid/domain.net/x1/randomId
。 例如https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID
,其中YOUR_INSTANCE_ID
是您的 Confluence Cloud 实例标识符,WEBTRIGGER_ID
是为您的应用生成的 Web 触发器端点的唯一标识符。
- 点击复制网址按钮或复制整个网址。
配置外部系统
使用在上文所述步骤中获得的 API 密钥和 Web 触发器网址配置需要提取 Confluence 用户邮箱信息的外部系统。
- 端点网址:您先前复制的 Web 触发器网址。
- HTTP 方法:
POST
所需标头:
- Content-Type:
application/json
X-Api-Key:
YOUR_API_KEY
将
YOUR_API_KEY
替换为您在设置 API 密钥部分中设置或生成的 API 密钥。
- Content-Type:
示例 curl 命令
此示例演示了如何调用 User Identity Accessor for Confluence 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
替换为您的 Confluence 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 密钥的安全,请遵循以下建议:
- 在 Confluence Cloud 连接器的配置中安全地存储 API 密钥。
- 验证与网络钩子网址的所有通信是否都是通过 HTTPS 进行。这是 User Identity Accessor for Confluence Cloud Web 触发器的默认设置。
为 User Identity Accessor for Confluence Cloud 提供支持
Google 为 User Identity Accessor for Confluence Cloud 应用提供了多种支持服务,包括维护和定期更新,以确保应用保持最新状态。如果您遇到任何问题或对应用功能有具体疑问,请与 Google Cloud 支持团队联系。
管理 Confluence Cloud 数据存储区
本部分提供了有关如何创建、更新和升级 Confluence Cloud 数据存储区的说明。
创建 Confluence Cloud 数据存储区
控制台
如需使用 Google Cloud 控制台将 Confluence Cloud 中的数据同步到 Gemini Enterprise,请按以下步骤操作:
在 Google Cloud 控制台中,前往 Gemini Enterprise 页面。
在导航菜单中,点击数据存储区。
点击
创建数据存储区。在选择数据源页面上,滚动查找或搜索 Confluence Cloud 以关联该第三方来源。
在为数据存储区指定 Confluence Cloud 来源页面上,执行以下操作:
选择身份验证方法:
输入身份验证详细信息 如需使用 OAuth 进行身份验证,请选择 OAuth 2.0 客户端凭证,然后指定实例 URI、实例 ID、客户端 ID 和客户端密钥。
- 点击登录,为应用选择一个网站。
- 点击接受。
刷新令牌的默认过期时间为 365 天。如果刷新令牌过期或被撤消,您可以执行以下任一操作:
- 重新发起 OAuth 流程。重新进行身份验证的用户必须具有管理员权限。
- 使用刷新令牌获取新的访问令牌和刷新令牌对。
如需了解详情,请参阅访问令牌过期或被撤消。
选择要使用该应用的网站 如需使用 API 令牌进行身份验证,请选择 API 令牌,然后指定实例 URI、Confluence 用户名和 API 令牌。
点击继续。
(可选)在高级选项部分,执行以下操作:
- 如需仅将一组静态 IP 地址列入许可名单,请选中启用静态 IP 地址复选框。
- 如需对连接器发送到 Confluence 实例的查询应用速率限制,请在每秒查询次数上限字段中指定每秒查询次数上限。默认值为 20 QPS。您可以根据 Confluence 服务器的性能逐步提高 QPS 值。在提高 QPS 值之前,请考虑以下事项:
- Confluence 服务器上的现有负载。
- 使用服务器的其他第三方应用的吞吐量。
- 在 Confluence Identity Sync Forge 网址字段中,输入由 User Identity Accessor for Confluence Cloud 应用生成的网址。
- 在 Confluence Identity Sync Forge 客户端密钥字段中,输入在 User Identity Accessor for Confluence Cloud 中配置的客户端密钥,即您在设置 API 密钥部分生成或创建的 API 密钥。
在要同步的实体部分中,执行以下操作:
选择要同步的实体:
页面
Whiteboard
博客
附件
备注
系统会根据您在创建数据存储时所拥有的管理员权限注入数据。除了管理员权限之外,您还必须有权访问特定的实体记录,例如博客或帖子。
选择要同步的实体 (可选)如需从特定空间同步,请执行以下操作:
- 点击过滤。
- 如需将实体从索引中排除,请选择从索引中排除;如需确保实体被纳入索引中,请选择纳入索引中。
- 输入空间键。每次按空间键后按 Enter 键。
- 点击保存。
指定用于包含或排除实体的过滤条件。 点击继续。
为完全同步选择同步频率,为增量数据同步选择增量同步频率。如需了解详情,请参阅同步时间表。
如果您想分开安排实体数据和身份数据的完全同步,请展开完全同步下的菜单,然后选择自定义选项。
为完全实体同步和完全身份同步单独设置时间表。 为您的数据连接器选择一个区域。
为数据连接器输入名称。
点击创建。Gemini Enterprise 会创建数据存储区,并在数据存储区页面上显示这些数据存储区。
如需查看数据注入状态,请前往数据存储区页面,然后点击数据存储区名称,在其数据页面查看相关详情。当连接器开始同步数据时,连接器状态会从正在创建变为正在运行。注入完成后,状态会变为活跃,表明已设置与数据源之间的关联,并在等待下一次的计划同步。
注入过程可能需要几分钟或几小时才能完成,具体取决于数据的大小。
更新数据存储区
您可以更新以下数据存储区参数:
- 数据存储区名称
- 身份验证凭证,例如客户端 ID、客户端密钥、用户账号和 API 令牌。
- 每秒查询次数上限和 Forge 应用参数,例如 Confluence 身份同步 Forge 网址和客户端密钥。
- 完全同步频率、增量同步频率和实时同步。
- 注入实体数据时要使用的过滤条件。
如需更新数据存储区,请按以下步骤操作:
在 Google Cloud 控制台中,前往 Gemini Enterprise 页面。
在导航菜单中,点击数据存储区。
点击要更新的数据存储区的名称。
更新以下值:
- 如需更新数据存储区名称、完全同步频率或增量同步频率,请点击修改图标 。
- 如需更新实时同步频率,请点击实时同步旁边的查看/修改。
- 如需更新身份验证凭证,请点击重新进行身份验证,然后指定相应的值。
- 如需更新每秒查询次数上限或 Forge 应用参数,请点击查看/修改参数,然后指定相应的值。
- 如需更新实体过滤条件,请在实体部分点击修改参数,然后点击过滤条件。
升级到新的数据存储区
如果您遇到网页实体搜索结果不准确的问题,请按照以下步骤将数据存储区升级到最新版本:
- 请确认您当前使用的数据存储区是否为最新版本:
- 在导航菜单中,点击数据存储区。
- 点击数据存储区的名称。
- 在显示的数据存储区详情页面中,进入实体标签页,然后点击页面实体。
- 在数据页面上,检查类型字段的值是否正确。如果该值为
Unstructured data
,则说明您正在使用最新版本的数据存储区,无需执行任何操作。如果值为Structured data
,请按照以下步骤创建新的数据存储区并迁移至该存储区。
- 创建新的数据存储区。
- 确保新数据存储区完成了一次包含所需数据的完整同步。
- 将新的数据存储区添加到应用中。
- 暂停之前的数据存储区中的同步。
- 在您确认新数据存储区能够按预期支持网页实体搜索后,请从应用中删除之前的数据存储区。
启用实时同步
实时同步只会同步文档实体,不会同步与身份实体相关的数据。下表显示了哪些文档事件支持实时同步。
Confluence 实体 | 创建 | 更新 | 删除 | 权限更改 |
---|---|---|---|---|
空间 | ||||
页面 | ||||
博客 | ||||
附件 | ||||
评论 | ||||
白板 |
在创建 Confluence Cloud 数据存储区 20 分钟后启用实时同步。 如需为 Confluence 数据源启用实时同步,请按以下步骤操作:
生成网络钩子网址
- 前往 Gemini Enterprise 页面,在导航菜单中点击数据存储区。
- 选择一个 Confluence 数据存储区。
在实时同步行中,点击查看/修改。
实时同步:已停用状态 在查看和修改实时同步参数对话框中,执行以下操作:
- 如需开启实时同步,请点击启用实时同步切换开关。
- 在客户端密钥字段中,输入一个占位值,例如
clientsecret
。 - 点击保存。
启用实时同步
当实时同步的状态变为
Running
后,点击查看/修改。实时同步:运行状态 在查看和修改实时同步参数对话框中,执行以下操作:
- 复制 Webhook 网址。
- 点击关闭。
复制 Webhook 网址
使用 API 订阅事件
如需接收来自 Confluence 的实时更新,您必须使用 POST 请求订阅特定事件。如需进行 API 调用,请使用在 Confluence 中设置身份验证和权限所用的同一管理员账号来创建数据存储区。
curl -X POST \
INSTANCE_URL/wiki/rest/webhooks/1.0/webhook \
-H "Content-Type: application/json" \
-u "USERNAME:API_TOKEN" \
-d '{
"name": "SUBSCRIPTION_NAME",
"url": "LISTENER_URL",
"events": [
"EVENT_TYPE_1",
"EVENT_TYPE_2"
],
"active": true
}'
INSTANCE_URL:Atlassian Cloud 网站的基本网址。
USERNAME:Atlassian Cloud 用户名。
API_TOKEN:从您的 Atlassian 账号生成的 API 令牌。如需了解详情,请参阅在 Confluence 中设置 API 令牌
SUBSCRIPTION_NAME:您的事件订阅的唯一名称。
LISTENER_URL:在数据存储区中启用实时同步 (RTS) 后,从 Google Cloud 控制台中复制的网络钩子网址。
EVENT_TYPE:您要订阅的事件类型。您可以订阅附件、博文、页面、空间和评论的创建、更新和删除事件。
用户可以订阅以下事件:
space_created
space_updated
page_created
page_updated
attachment_created
attachment_updated
comment_created
comment_updated
blog_created
blog_updated
API 错误代码
下表列出了用户在创建网络钩子时遇到的常见 API 错误代码。
错误类 | 错误代码 | 错误消息 | 问题排查 |
---|---|---|---|
403 |
FORBIDDEN |
当前用户无权使用 Confluence。 | 确保管理员账号中的令牌有效且 API 端点正确。 |
错误消息
下表列出了将 Confluence Cloud 与 Gemini Enterprise 相关联时可能会出现的常见错误消息、说明及可能的解决方法。
错误代码 | 错误消息 | 说明 | 问题排查 |
---|---|---|---|
CONFLUENCE_INVALID_AUTHENTICATION_1 | 身份验证错误。更多信息: | 连接器无法向 Confluence Cloud 进行身份验证。 | 使用管理员凭证重新向数据存储区进行身份验证。 |
CONFLUENCE_INVALID_AUTHORIZATION_1 | 授权错误。更多信息: | 没有管理员权限的用户账号尝试访问 Confluence Cloud。 | 使用管理员凭证重新向数据存储区进行身份验证。 |
CONFLUENCE_TOO_MANY_REQUEST | 向 Confluence Cloud 发送的 429 HTTP 请求过多。 | 连接器发送的请求数超过了默认 QPS 值。 | 如果此问题持续存在,请使用每秒查询次数上限字段降低数据存储区的 QPS 值。 |
已知限制
- 旧版用户管理模式不支持与 Confluence Cloud 集成。仅支持集中式用户管理模式。如需了解详情,请参阅 Atlassian 组织整合指南
- 您在 Confluence 页面上添加的宏的外观可能会因用户的访问权限而异。
- 此连接器不支持对空间实体进行增量同步。
- 您无法使用 Google Cloud 服务账号向 Confluence Cloud 进行身份验证。
后续步骤
如需将数据存储区挂接到应用,请按照创建应用中的步骤创建应用并选择数据存储区。
如需在设置应用和数据存储区后预览搜索结果以了解其显示方式,请参阅预览搜索结果。
如需为数据存储区启用提醒,请参阅为第三方数据存储区配置提醒。