此页面由 Cloud Translation API 翻译。

将后端模块与您的系统集成

后端模块是一种开箱即用的解决方案，可提供有效的后端基础架构来处理大量与功能相关的消息，并与客服人员桌面界面进行交互。本教程将指导您完成将后端模块与代理系统集成的流程。

如需详细了解后台模块的概念和结构，请参阅后端模块基础知识文档。

前提条件

如果您尚未配置 Google Cloud CLI，请安装该工具。

设置环境变量

为了简化部署命令，我们建议您在 Shell 中设置以下实用环境变量。您可以使用以下示例命令设置变量：

$ export GCP_PROJECT_ID='enter_project_id_here' \
&& export SERVICE_REGION='us-central1'

设置以下环境变量：

GCP_PROJECT_ID：托管相关资源的 Cloud Platform 项目的 ID。示例：my-project。
SERVICE_REGION：您的服务和相关 Cloud Platform 资源所在的位置或区域。示例：us-central1。

设置管理员账号

我们建议您为服务管理和运行时身份使用不同的 Google Cloud 账号。服务管理主要由拥有 Google 账号的人员执行，而运行时身份使用服务账号向 Cloud Run 服务授予权限，以便访问必要的资源。

准备人工管理员账号

如果您打算使用在项目中已有 Editor 或 Owner 权限的账号，可以直接跳至下一部分。

如需管理后端基础架构，请创建一个管理员账号并向其授予以下 IAM 角色。其权限均包含在基本角色 Editor (roles/editor) 和 Owner (roles/owner) 中。

roles/secretmanager.admin（Secret Manager 管理员）：管理存储在 Secret Manager 中的密钥，以生成和验证 JWT。
roles/run.admin（Cloud Run Admin）：部署和管理 Cloud Run 服务。
roles/iam.serviceAccountUser（服务账号用户）：向 Cloud Run 运行时服务账号授予 iam.serviceAccounts.actAs 权限。
roles/cloudbuild.builds.editor（Cloud Build 编辑器）：使用 Cloud Build 为集成服务构建 Docker 映像。
Artifact Registry 管理员：存储和管理集成服务的构建 Docker 映像。
roles/pubsub.editor（Cloud Pub/Sub Editor）：创建和管理 Cloud Pub/Sub 主题和订阅。
roles/redis.admin（Redis 管理员）：创建和管理 Memorystore for Redis 资源。

如需向用户账号授予 IAM 角色，请使用 add-iam-policy-binding Google Cloud CLI 命令。以下是命令示例：

$ gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
 --member='user:test-user@gmail.com' \
 --role='roles/pubsub.editor'

在 gcloud 中设置人工管理员账号

在以下示例中，将 $ADMIN_ACCOUNT 替换为您要使用的管理员账号（例如 myaccount@gmail.com）：

$ gcloud config set account $ADMIN_ACCOUNT

设置服务账号

默认情况下，Cloud Run 服务或作业以默认 Compute Engine 服务账号的身份运行。我们建议您为每个 Cloud Run 服务分配一个用户代管式服务账号，并为其授予一组最低权限，而不是使用默认服务账号。如果您打算保留默认服务账号，可以直接跳转到设置环境变量。

为每个 Cloud Run 运行时创建两个服务账号

如需创建服务账号，请替换 $CONNECTOR_SERVICE_ACCOUNT_ID 和 $INTERCEPTOR_SERVICE_ACCOUNT_ID 的值，然后运行以下命令：

$ export CONNECTOR_SERVICE_ACCOUNT_ID='aa-ui-connector' && gcloud iam service-accounts create $CONNECTOR_SERVICE_ACCOUNT_ID
--description='Agent Assist integration - UI connector service account'
--display-name='Agent Assist integration - UI connector'

$ export INTERCEPTOR_SERVICE_ACCOUNT_ID='aa-pubsub-interceptor' && gcloud iam service-accounts create $INTERCEPTOR_SERVICE_ACCOUNT_ID
--description='Agent Assist integration - Pubsub interceptor service account'
--display-name='Agent Assist integration - Pubsub interceptor'

使用以下示例命令将以下角色分配给界面连接器和 Cloud Pub/Sub 连接器服务账号：

$ gcloud projects add-iam-policy-binding $GCP_PROJECT_ID 

--member='serviceAccount:$CONNECTOR_SERVICE_ACCOUNT_ID@$GCP_PROJECT_ID.iam.gserviceaccount.com' 

--role='roles/pubsub.editor'

向界面连接器服务账号授予以下 IAM 角色：

roles/redis.editor
roles/vpcaccess.user
roles/compute.viewer
roles/secretmanager.secretAccessor
roles/dialogflow.agentAssistClient

向 Cloud Pub/Sub 连接器服务账号授予以下角色：

roles/redis.editor
roles/vpcaccess.user
roles/compute.viewer

设置环境变量

将以下环境变量的值设置为您刚刚创建的服务账号，或项目中的默认 Compute Engine 服务账号。

CONNECTOR_SERVICE_ACCOUNT：界面连接器运行时的服务账号。示例：aa-ui-connector@my-project-id.iam.gserviceaccount.com。
INTERCEPTOR_SERVICE_ACCOUNT：Cloud Pub/Sub 拦截器运行时的服务账号。示例：aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com。

自定义用户身份验证方法

代码库同时支持 Genesys Cloud 和 Twilio 的后端用户和前端模块用户。

在代码库中，打开 ui_connector/auth.py 文件。
通过设置环境变量 AUTH_OPTION 指定支持的身份提供程序，或使用 auth.check_auth 实现身份验证方法。

默认情况下，AUTH_OPTION 为空，并且任何用户都无法向界面连接器服务注册 JWT。支持的值：
- “Salesforce”：使用 Salesforce OpenID Connect 验证身份验证令牌。必需的环境变量：SALESFORCE_ORGANIZATION_ID。
- 'GenesysCloud'：使用 Genesys SDK UsersAPI 验证身份验证令牌。
- “Twilio”：验证 Twilio 的身份验证令牌。必需的环境变量：TWILIO_FLEX_ENVIRONMENT。
示例：
```
$ export AUTH_OPTION='Salesforce'
```
每种令牌类型可能都有不同的验证方式。令牌的验证方式由您决定。如果不进行任何更改，auth.check_auth 会针对每个请求返回 false。

生成并存储 JWT 密钥

为了让界面连接器服务将安全的身份验证令牌发回给客户端，它必须使用 JWT 密钥对这些令牌进行加密。键的值可以是任意字符串，但应是唯一且难以猜测的字符串。

此 Secret 密钥将存储在 Secret Manager 中。

设置环境变量

JWT_SECRET_NAME：Secret Manager 中的 Secret 密钥的名称。它可以是任意名称。推荐的值：aa-integration-jwt-secret。

生成密钥

我们建议您生成一个随机哈希作为 JWT 密钥，以免被攻击者猜到。为此，您可以使用 python secrets 为其生成安全的随机数。

将密钥存储在 Secret Manager 中

在以下示例命令中，将 my_key 替换为您计划使用的密钥。

printf "my_key" | gcloud secrets create $JWT_SECRET_NAME --data-file=- --replication-policy=user-managed --locations=$SERVICE_REGION

设置 Memorystore for Redis

如需设置 Redis，您需要以下环境变量：

VPC_CONNECTOR_NAME：用于将 Cloud Run 服务连接到 Memorystore for Redis 的 Serverless VPC Access 连接器的名称。建议值：aa-integration-vpc。
VPC_NETWORK：要将无服务器 VPC 访问通道连接器附加到的 VPC 网络。如果您未为 Google Cloud 项目设置 VPC，则此值应为 default。
REDIS_IP_RANGE：无服务器 VPC 访问通道连接器的未预留内部 IP 网络。必须提供 /28 的未分配空间。建议的值：10.8.0.0/28（此值适用于大多数新项目）。
REDIS_INSTANCE_ID：Redis 实例的名称。推荐的值：aa-integration-redis。

在 Cloud Run 服务所在的区域创建 Redis 实例

运行以下命令：

$ gcloud redis instances create $REDIS_INSTANCE_ID --size=5 --region=$SERVICE_REGION

创建 Serverless VPC Access 连接器

确保已为您的项目启用 Serverless VPC Access API：

$ gcloud services enable vpcaccess.googleapis.com

使用自定义 IP 范围创建无服务器 VPC 访问通道连接器：

$ gcloud compute networks vpc-access connectors create $VPC_CONNECTOR_NAME \
  --network $VPC_NETWORK \
  --region $SERVICE_REGION \
  --range $REDIS_IP_RANGE

将 Redis 主机和 Redis 端口保存为环境变量

将 Redis 实例的 IP 地址设置为环境变量 REDIS_HOST。
将 Redis 实例的端口号设置为环境变量 REDIS_PORT。

部署界面连接器服务

对于界面连接器服务，您需要以下环境变量：

CONNECTOR_SERVICE_NAME：界面连接器的 Cloud Run 服务名称。推荐的值：ui-connector。
CONNECTOR_IMAGE_NAME：界面连接器服务的映像名称。它可以与 CONNECTOR_SERVICE_NAME 相同。推荐的值：ui-connector。

构建 Docker 映像

在 /ui-connector 文件夹下，运行以下命令：

$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME

将界面连接器部署到 Cloud Run

在 /ui-connector 文件夹下，运行以下命令。记下已部署的界面连接器的服务网址，客户端（代理桌面）将使用该网址。

$ gcloud run deploy $CONNECTOR_SERVICE_NAME \
--image gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME \
--platform managed \
--service-account=$CONNECTOR_SERVICE_ACCOUNT \
--allow-unauthenticated \
--timeout 3600 \
--region $SERVICE_REGION \
--vpc-connector $VPC_CONNECTOR_NAME \
--set-env-vars REDISHOST=$REDIS_HOST,REDISPORT=$REDIS_PORT,GCP_PROJECT_ID=$GCP_PROJECT_ID \
--update-secrets=/secret/jwt_secret_key=${JWT_SECRET_NAME}:latest

部署 Cloud Pub/Sub 拦截器服务

对于 Pub/Sub 拦截器服务，您需要以下环境变量：

INTERCEPTOR_SERVICE_NAME：Cloud Pub/Sub 拦截器的 Cloud Run 服务名称。推荐的值：cloud-pubsub-interceptor。
INTERCEPTOR_IMAGE_NAME：Cloud Pub/Sub 拦截器服务的映像名称。它可以与 INTERCEPTOR_SERVICE_NAME 相同。推荐的值：cloud-pubsub-interceptor。

构建 Docker 映像

在 /cloud-pubsub-interceptor 文件夹下，运行以下命令：

$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$INTERCEPTOR_IMAGE_NAME

将 Pub/Sub 拦截器部署到 Cloud Run

在 /cloud-pubsub-interceptor 文件夹下，运行以下命令：

$ gcloud run deploy $INTERCEPTOR_SERVICE_NAME \
--image gcr.io/$GCP_PROJECT_ID/$INTERCEPTOR_IMAGE_NAME \
--platform managed \
--service-account=$INTERCEPTOR_SERVICE_ACCOUNT_NAME \
--region $SERVICE_REGION \
--vpc-connector $VPC_CONNECTOR_NAME \
--ingress=internal \
# You can also add LOGGING_FILE here to specify the logging file path on Cloud Run. 
--set-env-vars REDISHOST=$REDIS_HOST,REDISPORT=$REDIS_PORT

保存已部署的网址

将已部署的网址设置为 INTERCEPTOR_SERVICE_URL 环境变量。

配置 Cloud Pub/Sub 订阅

Cloud Pub/Sub 订阅使用以下内容：

主题
对话资料
服务账号
拦截器服务的服务账号权限
对话生命周期事件

创建 Cloud Pub/Sub 主题

为您需要从 Dialogflow 接收的每种事件通知创建一个 Cloud Pub/Sub 主题。可用的事件通知类型如下：

新建议事件：有新的 Agent Assist 建议可用时发送的事件（例如，针对客户表述做出的新的智能回复建议）。
新消息事件：每当系统识别到客服人员或客户的新话语时（例如，客户说 Hi），都会发送事件。
新的对话生命周期事件：针对特定对话生命周期变化（例如，对话开始或完成时）发送的事件。
新的识别结果通知事件：在系统识别出客服人员或客户的中间转写内容时发送的事件（例如，客户说 Hi, how can I help you?，中间转写内容为 Hi how can，同时客户正在说话）。

记下主题 ID 和主题名称，以备稍后进行后端部署。

配置对话配置文件

使用您在上一步中创建的 Cloud Pub/Sub 主题配置对话个人资料。

创建新的对话个人资料时，选择 Pub/Sub 通知，然后选择启用 Pub/Sub 通知。启用后，您可以选中要启用的通知类型旁边的复选框，然后输入通知关联的 Cloud Pub/Sub 主题的主题 ID。
为每个主题选择 JSON 作为消息格式。

为 Pub/Sub 订阅身份创建服务账号

使用以下命令创建一个表示 Pub/Sub 订阅身份的服务账号：

$ gcloud iam service-accounts create cloud-run-pubsub-invoker \
     --display-name "Cloud Run Pub/Sub Invoker"

向服务账号授予调用拦截器服务的权限

运行以下命令：

$ gcloud run services add-iam-policy-binding $INTERCEPTOR_SERVICE_NAME \ 
  --member=serviceAccount:cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/run.invoker

为主题创建 Cloud Pub/Sub 订阅

对于您创建的每个主题，您都必须创建相应的 Cloud Pub/Sub 订阅。

新的建议事件

将 your-new-suggestion-topic-id 替换为您为获取新建议而配置的 Cloud Pub/Sub 主题：

$ export TOPIC_ID='your-new-suggestion-topic-id' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/human-agent-assistant-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com

新消息事件

将 your-new-message-event-topic-id 替换为您为新消息事件配置的 Cloud Pub/Sub 主题：

$ export TOPIC_ID='your-new-message-event-topic-id' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/new-message-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com

对话生命周期事件

将 your-conversation-lifecycle-event-topic 替换为您为新的对话生命周期事件配置的 Cloud Pub/Sub 主题：

$ export TOPIC_ID='your-conversation-lifecycle-event-topic' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/conversation-lifecycle-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com

新的识别结果通知事件

$ export TOPIC_ID='your-new-recognition-result-notification-event-topic' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/new-recognition-result-notification-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com