Git 导出/恢复

注意： 此集成的新版本已于 2025 年 2 月发布。 旧版本的用户可以在不使用 Secret 的情况下提供令牌。 以下文档主要适用于新版本。

Dialogflow CX 可与多个 Git 提供商（GitHub、Gitlab、Bitbucket 等）集成。 通过此集成，您可以轻松将代理导出为 JSON，以便推送到 Git 提供方，以及从 Git 提供方拉取以恢复代理。推送到 Git 提供商的 JSON 导出格式是导出智能体的展开 ZIP 文件内容。

使用此功能，您可以利用 Git 提供商源代码控制功能，例如：

• 使用代码审核工具审核代理更改
• 使用差异工具检查代理差异
• 合并

限制

存在以下限制：

• [仅限旧集成版本] GitHub API 对单个提交中可更新的文件数量有限制。如果文件数量超过 500，您可能无法从 Dialogflow CX 推送到 GitHub。在这种情况下，您可以将代理导出为 ZIP 文件，然后使用机器上的 Git CLI 将代理文件推送到 GitHub。 此限制将在后续 Dialogflow CX 版本中得到解决。
• 不支持 GitHub 专用访问权限自托管代码库，因为 Dialogflow CX 无法访问这些代码库。
• Git 代码库不能包含通过智能体导出功能导出的智能体文件以外的任何文件。每次推送时，代码库中的所有其他文件都会被移除。

配置

如需配置此功能，您需要从 Git 提供方获取访问令牌，将其存储在 Secret Manager 中，并将 Secret 资源提供给 Dialogflow CX：

访问令牌

如需从 Git 提供商处获取访问令牌，请执行以下操作：

GitHub

您需要获取 GitHub 个人令牌。如果您使用精细的个人访问令牌，则需要以下权限：

• Repository Permissions > Contents：读写
• Repository Permissions > Metadata：只读（选择“Contents”权限后应自动选择）

GitLab

您需要获取 Gitlab 个人访问令牌。

Bitbucket

您需要获取 Bitbucket 访问令牌。

Secret Manager

现在，您已拥有访问令牌，接下来需要为令牌创建 Secret：

1. 启用 Secret Manager API。
2. 创建 Secret。

Dialogflow CX 配置

如需为 Dialogflow CX 配置此集成，请执行以下操作：

1. 向 Dialogflow 服务代理授予访问 Secret Manager 中的访问令牌 Secret 的权限。 向代理项目中的 gcp-sa-dialogflow. 服务账号授予 Secret Manager Secret Accessor 角色。请参阅授予对 Secret Manager 密钥的访问权限。
2. 打开 Git 集成配置：
   • Conversational Agents 控制台
     1. 点击右上角附近的设置图标，打开设置显示。
     2. 向下滚动，然后点击添加 Git 集成。
   • Dialogflow CX 控制台
     1. 点击管理标签页。
     2. 点击测试和部署部分中的 Git。
     3. 点击新建 (Create new)。
3. 提供配置详细信息：
   1. 输入以下内容：
      • GitHub 连接的显示名称。
      • Git 代码库网址（例如：https://github.com/<path-to-repo>.git）。
      • 添加智能体将与之交互的 Git 分支。 您可以点击分支旁边的星形图标，将其指定为默认分支。
      • 访问令牌 Secret，即您创建的 Secret 版本，格式为 projects/*/secrets/*/versions/*（对于特定版本）或 projects/*/secrets/*/versions/latest（对于最新版本）。
   2. 点击连接。
   3. Git 服务可能需要一分钟才能准备就绪。 控制台会显示通知。

推送和恢复

配置完成后，您就可以将代理推送到 Git 或从 Git 拉取代理。

推送按钮用于导出代理并提交到 Git 分支下拉菜单中选择的 Git 分支。此提交将包含整个代理，而不是特定更改，并且会删除代码库中的所有现有文件。

具有 Dialogflow Reader 角色的用户能够推送到 Git 代码库。为防止不必要的推送，请为这些代理配置只读个人访问令牌。

恢复按钮用于从 Git 分支下拉菜单中选择的 Git 分支中拉取您的智能体数据，并根据这些数据恢复 Dialogflow CX 智能体。这会覆盖您的代理，其行为与任何代理恢复行为相同。

用例示例

以下示例说明了多人如何使用此功能向生产代理提出不同的代理更改。

假设您的代理使用以下 Git 分支：

• Prod：生产代理的分支
• Dev1：用于智能体开发的分支
• Dev2：另一个用于智能体开发的分支

用户 1 想要提议更改代理，并采取以下步骤：

1. 将生产代理导出到新代理。
2. 根据需要对此代理副本进行更改。
3. 测试更改。
4. 将修改后的代理推送到 Dev1 分支。
5. 创建针对 Prod 分支的合并请求。

用户 2 想要提议更改代理，并执行以下步骤：

1. 将生产代理导出到新代理。
2. 根据需要对此代理副本进行更改。
3. 测试更改。
4. 将修改后的智能体推送到 Dev2 分支。
5. 创建针对 Prod 分支的合并请求。

用户 3 审核这两位用户的合并请求，并执行以下步骤：

1. 解决冲突。
2. 提交已批准的更改。
3. 将生产 Git 分支恢复到生产 Dialogflow CX 智能体。