バックエンド モジュールをシステムと統合する

バックエンド モジュールは、大量の機能関連メッセージを処理し、エージェントのデスクトップ UI とやり取りするための効果的なバックエンド インフラストラクチャを提供する、すぐに使えるソリューションです。このチュートリアルでは、バックエンド モジュールをエージェント システムと統合するプロセスについて説明します。

バックグラウンド モジュールのコンセプトと構造の詳細については、バックエンド モジュールの基本のドキュメントをご覧ください。

前提条件

  • Google Cloud CLI をまだ構成していない場合は、インストールします。

環境変数を設定する

デプロイのコマンドを簡素化するために、シェルで次の便利な環境変数を設定することをおすすめします。変数を設定するには、次のコマンドの例を使用します。

$ 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

管理者アカウントを設定する

サービス管理とランタイム ID には、別の Google Cloud アカウントを使用することをおすすめします。サービスの管理は主に Google アカウントを持つ人間によって行われますが、ランタイム ID は サービス アカウントを使用して Cloud Run サービスに権限を付与し、必要なリソースへのアクセスを有効にします。

人間の管理者アカウントを準備する

プロジェクトで編集者権限またはオーナー権限がすでに付与されているアカウントを使用する場合は、次のセクションに進んでください。

バックエンド インフラストラクチャを管理するには、管理者アカウントを設定し、次の IAM ロールを付与します。これらの権限はすべて、基本ロールの編集者（roles/editor）とオーナー（roles/owner）に含まれています。

  • roles/secretmanager.admin（Secret Manager 管理者）: JWT の生成と検証のために Secret Manager に保存されているシークレットを管理します。
  • roles/run.admin（Cloud Run 管理者）: 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 エディタ）: 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 サービスに専用 ID を与えることをおすすめします。デフォルトのサービス アカウントを保持する場合は、環境変数を設定するまでスキップできます。

Cloud Run ランタイムごとに 2 つのサービス アカウントを作成する

  1. サービス アカウントを作成するには、$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'

  2. 次のサンプル コマンドを使用して、UI コネクタと 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'

UI コネクタのサービス アカウントに次の 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 サービス アカウントに設定します。

  1. CONNECTOR_SERVICE_ACCOUNT: UI コネクタ ランタイムのサービス アカウント。例: aa-ui-connector@my-project-id.iam.gserviceaccount.com
  2. INTERCEPTOR_SERVICE_ACCOUNT: Cloud Pub/Sub インターセプタ ランタイムのサービス アカウント。例: aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com

ユーザー認証方法をカスタマイズする

コード リポジトリは、Genesys Cloud と Twilio のバックエンド ユーザーとフロントエンド モジュールのユーザーの両方をサポートしています。

  1. コード リポジトリ内で ui_connector/auth.py ファイルを開きます。

  2. 環境変数 AUTH_OPTION を設定してサポートされている ID プロバイダを指定するか、auth.check_auth を使用して認証方法を実装します。

    デフォルトでは、AUTH_OPTION は空で、どのユーザーも UI コネクタ サービスに 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 シークレット鍵を生成し、保存する

UI コネクタ サービスが安全な認証トークンをクライアントに返すには、JWT 秘密鍵を使用してトークンを暗号化する必要があります。キーの値は任意の文字列にできますが、一意で推測しにくいものにする必要があります。

この秘密鍵は Secret Manager に保存されます。

環境変数を設定する

  • JWT_SECRET_NAME: Secret Manager の秘密鍵の名前。任意の名前にできます。推奨値: 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 に接続する サーバーレス VPC アクセス コネクタの名前。推奨値: 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

サーバーレス VPC アクセス コネクタを作成する

プロジェクトでサーバーレス VPC アクセスが有効になっていることを確認します。

$ 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 に設定します。

UI コネクタ サービスをデプロイする

UI コネクタ サービスには、次の環境変数が必要です。

  • CONNECTOR_SERVICE_NAME: UI コネクタの Cloud Run サービス名。推奨値: ui-connector
  • CONNECTOR_IMAGE_NAME: UI コネクタ サービスのイメージ名。CONNECTOR_SERVICE_NAME と同じ値を指定できます。推奨値: ui-connector

Docker イメージをビルドする

/ui-connector フォルダで、次のコマンドを実行します。

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

UI コネクタを Cloud Run にデプロイする

/ui-connector フォルダで、次のコマンドを実行します。デプロイされた UI コネクタのサービス URL をメモします。この URL は、クライアント（エージェント デスクトップ）で使用されます。

$ 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

デプロイされた URL を保存する

デプロイされた URL を INTERCEPTOR_SERVICE_URL 環境変数として設定します。

Cloud Pub/Sub サブスクリプションを構成する

Cloud Pub/Sub サブスクリプションは、次のものを使用します。

  • トピック
  • 会話プロファイル
  • サービス アカウント
  • インターセプタ サービスのサービス アカウントの権限
  • 会話のライフサイクル イベント

Cloud Pub/Sub トピックを作成する

Dialogflow から必要なイベント通知の種類ごとに Cloud Pub/Sub トピックを作成します。使用可能なイベント通知の種類は次のとおりです。

  • 新しい候補イベント: 新しいエージェント アシストの候補が利用可能になったときに送信されるイベント（お客様の発話に応じた新しいスマート リプライの候補など）。
  • 新しいメッセージ イベント: エージェントまたはお客様から新しい発話が認識されるたびに送信されるイベント（お客様が 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 サブスクリプション ID のサービス アカウントを作成する

次のコマンドを使用して、Pub/Sub サブスクリプション ID を表すサービス アカウントを作成します。

$ 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