Les modules backend sont une solution prête à l'emploi qui fournit une infrastructure backend efficace pour traiter de grands volumes de messages liés aux fonctionnalités et interagir avec l'interface utilisateur de bureau de l'agent. Ce tutoriel vous explique comment intégrer des modules backend à votre système d'agents.
Pour en savoir plus sur les concepts et la structure des modules en arrière-plan, consultez la documentation sur les principes de base des modules backend.
Prérequis
- Installez la Google Cloud CLI si vous ne l'avez pas déjà configurée.
Configurer des variables d'environnement
Pour simplifier les commandes de déploiement, nous vous recommandons de définir les variables d'environnement utiles suivantes dans votre shell. Vous pouvez définir les variables à l'aide de l'exemple de commande suivant:
$ export GCP_PROJECT_ID='enter_project_id_here' \ && export SERVICE_REGION='us-central1'
Définissez les variables d'environnement suivantes :
GCP_PROJECT_ID
: ID de votre projet Cloud Platform qui héberge les ressources associées. Exemple :my-project
.SERVICE_REGION
: emplacement ou région de vos services et des ressources Cloud Platform associées. Exemple :us-central1
.
Configurer un compte administrateur
Nous vous recommandons d'utiliser des comptes Google Cloud distincts pour l'administration des services et l'identité d'exécution. L'administration des services est principalement effectuée par des humains disposant de comptes Google, tandis que l'identité d'exécution accorde des autorisations aux services Cloud Run à l'aide de comptes de service pour permettre l'accès aux ressources nécessaires.
Préparer le compte administrateur humain
Si vous prévoyez d'utiliser un compte disposant déjà des autorisations Éditeur ou Propriétaire dans votre projet, vous pouvez passer à la section suivante.
Pour gérer l'infrastructure backend, créez un compte administrateur et attribuez-lui les rôles IAM suivants. Leurs autorisations sont toutes incluses dans les rôles de base Éditeur (roles/editor) et Propriétaire (roles/owner).
roles/secretmanager.admin
(administrateur Secret Manager): permet de gérer les secrets stockés dans Secret Manager pour la génération et la validation des jetons JWT.roles/run.admin
(administrateur Cloud Run): permet de déployer et de gérer les services Cloud Run.roles/iam.serviceAccountUser
(Utilisateur du compte de service): accordez des autorisationsiam.serviceAccounts.actAs
aux comptes de service d'exécution Cloud Run.roles/cloudbuild.builds.editor
(Éditeur Cloud Build): créez des images Docker pour les services d'intégration à l'aide de Cloud Build.- Administrateur Artifact Registry: stocke et gère les images Docker compilées pour les services d'intégration.
roles/pubsub.editor
(Éditeur Cloud Pub/Sub): créez et gérez des sujets et des abonnements Cloud Pub/Sub.roles/redis.admin
(administrateur Redis): créez et gérez les ressources Memorystore pour Redis.
Pour attribuer des rôles IAM à un compte utilisateur, utilisez la commande Google Cloud CLI add-iam-policy-binding
. Voici un exemple de commande:
$ gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \ --member='user:test-user@gmail.com' \ --role='roles/pubsub.editor'
Définir le compte administrateur humain dans gcloud
Remplacez $ADMIN_ACCOUNT
par le compte administrateur que vous souhaitez utiliser (par exemple, myaccount@gmail.com
) dans l'exemple suivant :
$ gcloud config set account $ADMIN_ACCOUNT
Configurer des comptes de service
Par défaut, les services ou jobs Cloud Run s'exécutent en tant que compte de service Compute Engine par défaut. Plutôt que de laisser l'identité par défaut, nous vous recommandons d'attribuer une identité dédiée à chaque service Cloud Run en lui attribuant un compte de service géré par l'utilisateur avec l'ensemble minimal d'autorisations requis. Si vous prévoyez de conserver le compte de service par défaut, vous pouvez passer directement à la section Définir des variables d'environnement.
Créer deux comptes de service pour chaque environnement d'exécution Cloud Run
Pour créer les comptes de service, remplacez la valeur de
$CONNECTOR_SERVICE_ACCOUNT_ID
et$INTERCEPTOR_SERVICE_ACCOUNT_ID
si nécessaire, puis exécutez les commandes suivantes:$ 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'Utilisez l'exemple de commande suivant pour attribuer les rôles suivants aux comptes de service du connecteur d'interface utilisateur et du connecteur 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'
Attribuez les rôles IAM suivants au compte de service du connecteur d'interface utilisateur:
roles/redis.editor
roles/vpcaccess.user
roles/compute.viewer
roles/secretmanager.secretAccessor
roles/dialogflow.agentAssistClient
Attribuez les rôles suivants au compte de service du connecteur Cloud Pub/Sub:
roles/redis.editor
roles/vpcaccess.user
roles/compute.viewer
Définir des variables d'environnement
Définissez les valeurs des variables d'environnement suivantes sur les comptes de service que vous venez de créer ou sur le compte de service Compute Engine par défaut de votre projet.
CONNECTOR_SERVICE_ACCOUNT
: compte de service pour l'environnement d'exécution du connecteur d'interface utilisateur. Exemple :aa-ui-connector@my-project-id.iam.gserviceaccount.com
.INTERCEPTOR_SERVICE_ACCOUNT
: compte de service pour l'environnement d'exécution de l'intercepteur Cloud Pub/Sub. Exemple :aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com
.
Personnaliser la méthode d'authentification des utilisateurs
Le dépôt de code est compatible avec les utilisateurs du backend et ceux du module d'interface pour Genesys Cloud et Twilio.
- Dans le dépôt de code, ouvrez le fichier
ui_connector/auth.py
. Spécifiez le fournisseur d'identité compatible en définissant la variable d'environnement
AUTH_OPTION
ou implémentez votre méthode d'authentification avecauth.check_auth
.Par défaut,
AUTH_OPTION
est vide et aucun utilisateur n'est autorisé à enregistrer un jeton JWT auprès du service UI Connector. Valeurs autorisées :- "Salesforce": vérifiez le jeton d'autorisation à l'aide de Salesforce OpenID Connect. Variable d'environnement requise: SALESFORCE_ORGANIZATION_ID.
- 'GenesysCloud': vérifiez le jeton d'autorisation à l'aide de l'API Users du SDK Genesys.
- "Twilio": vérifiez le jeton d'authentification pour Twilio. Variable d'environnement requise: TWILIO_FLEX_ENVIRONMENT.
Exemple :
$ export AUTH_OPTION='Salesforce'
Chaque type de jeton peut avoir un mode de validation différent. C'est vous qui décidez de la manière dont le jeton est validé. Sans modification,
auth.check_auth
renvoiefalse
pour chaque requête.
Générer et stocker une clé secrète JWT
Pour que le service de connecteur d'interface utilisateur renvoie des jetons d'authentification sécurisés au client, il doit les chiffrer à l'aide d'une clé secrète JWT. La valeur de la clé peut être n'importe quelle chaîne arbitraire, mais elle doit être unique et difficile à deviner.
Cette clé secrète sera stockée dans Secret Manager.
Définir une variable d'environnement
JWT_SECRET_NAME
: nom de la clé secrète dans Secret Manager. Il peut s'agir de n'importe quel nom arbitraire. Valeur recommandée:aa-integration-jwt-secret
.
Générer la clé
Nous vous recommandons de générer un hachage aléatoire comme clé secrète JWT afin qu'il ne puisse pas être deviné par des pirates informatiques. Pour ce faire, vous pouvez utiliser des secrets Python pour générer des nombres aléatoires sécurisés.
Stocker la clé dans Secret Manager
Dans l'exemple de commande suivant, remplacez my_key
par la clé secrète que vous prévoyez d'utiliser.
printf "my_key" | gcloud secrets create $JWT_SECRET_NAME --data-file=- --replication-policy=user-managed --locations=$SERVICE_REGION
Configurer Memorystore pour Redis
Pour configurer Redis, vous avez besoin des variables d'environnement suivantes:
VPC_CONNECTOR_NAME
: nom de votre connecteur d'accès au VPC sans serveur pour connecter les services Cloud Run à Memorystore pour Redis. Valeur recommandée:aa-integration-vpc
.VPC_NETWORK
: réseau VPC auquel associer le connecteur d'accès au VPC sans serveur. La valeur doit êtredefault
si vous ne configurez pas de VPC pour votre Google Cloud projet.REDIS_IP_RANGE
: réseau IP interne non réservé pour votre connecteur d'accès au VPC sans serveur. Un espace non attribué de/28
est requis. Valeur recommandée :10.8.0.0/28
(cette valeur devrait fonctionner pour la plupart des nouveaux projets).REDIS_INSTANCE_ID
: nom de votre instance Redis. Valeur recommandée :aa-integration-redis
.
Créer une instance Redis dans la région de vos services Cloud Run
Exécutez la commande suivante :
$ gcloud redis instances create $REDIS_INSTANCE_ID --size=5 --region=$SERVICE_REGION
Créez un connecteur d'accès au VPC sans serveur.
Assurez-vous que l'API Serverless VPC Access est activée pour votre projet:
$ gcloud services enable vpcaccess.googleapis.com
Créez un connecteur d'accès au VPC sans serveur avec une plage d'adresses IP personnalisée:
$ gcloud compute networks vpc-access connectors create $VPC_CONNECTOR_NAME \ --network $VPC_NETWORK \ --region $SERVICE_REGION \ --range $REDIS_IP_RANGE
Enregistrer l'hôte et le port Redis en tant que variables d'environnement
- Définissez l'adresse IP de votre instance Redis sur la variable d'environnement
REDIS_HOST
. - Définissez le numéro de port de votre instance Redis sur la variable d'environnement
REDIS_PORT
.
Déployer le service de connecteur d'interface utilisateur
Pour le service de connecteur d'interface utilisateur, vous avez besoin des variables d'environnement suivantes:
CONNECTOR_SERVICE_NAME
: nom du service Cloud Run de votre connecteur d'interface utilisateur. Valeur recommandée:ui-connector
.CONNECTOR_IMAGE_NAME
: nom de l'image de votre service de connecteur d'interface utilisateur. Il peut être identique àCONNECTOR_SERVICE_NAME
. Valeur recommandée:ui-connector
.
Compiler l'image Docker
Dans le dossier /ui-connector
, exécutez la commande suivante:
$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME
Déployer le connecteur d'interface utilisateur dans Cloud Run
Dans le dossier /ui-connector
, exécutez la commande suivante. Notez l'URL du service du connecteur d'interface utilisateur déployé, qui sera utilisée par les clients (ordinateurs de bureau des agents).
$ 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
Déployer le service d'intercepteur Cloud Pub/Sub
Pour le service d'intercepteur Pub/Sub, vous avez besoin des variables d'environnement suivantes:
INTERCEPTOR_SERVICE_NAME
: nom du service Cloud Run de votre intercepteur Cloud Pub/Sub. Valeur recommandée:cloud-pubsub-interceptor
.INTERCEPTOR_IMAGE_NAME
: nom de l'image de votre service d'intercepteur Cloud Pub/Sub. Il peut être identique àINTERCEPTOR_SERVICE_NAME
. Valeur recommandée:cloud-pubsub-interceptor
.
Compiler l'image Docker
Dans le dossier /cloud-pubsub-interceptor
, exécutez la commande suivante:
$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$INTERCEPTOR_IMAGE_NAME
Déployer un intercepteur Pub/Sub dans Cloud Run
Dans le dossier /cloud-pubsub-interceptor
, exécutez la commande suivante:
$ 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
Enregistrer l'URL déployée
Définissez l'URL déployée comme variable d'environnement INTERCEPTOR_SERVICE_URL
.
Configurer des abonnements Cloud Pub/Sub
Les abonnements Cloud Pub/Sub utilisent les éléments suivants:
- Thèmes
- Profil de conversation
- Compte de service
- Autorisation du compte de service pour le service d'intercepteur
- Événements de cycle de vie des conversations
Créer des sujets Cloud Pub/Sub
Créez un sujet Cloud Pub/Sub pour chaque type de notification d'événement dont vous avez besoin de la part de Dialogflow. Les types de notifications d'événements disponibles sont les suivants:
- Événements de nouvelle suggestion: événements envoyés lorsque de nouvelles suggestions Agent Assist sont disponibles (par exemple, de nouvelles suggestions de réponse intelligente en réponse à une déclaration du client).
- Événements de nouveau message: événements envoyés chaque fois qu'une nouvelle expression est reconnue par un agent ou un client (par exemple, le client dit
Hi
). - Nouveaux événements du cycle de vie des conversations: événements envoyés pour certains changements du cycle de vie des conversations (par exemple, au début ou à la fin d'une conversation).
- Nouveaux événements de notification de résultats de reconnaissance: événements envoyés lorsqu'une transcription intermédiaire est reconnue à partir d'un agent ou d'un client (par exemple, le client dit
Hi, how can I help you?
, une transcription intermédiaire estHi how can
pendant que le client parle).
Notez l'ID et le nom du thème pour le déploiement du backend ultérieur.
Configurer un profil de conversation
Configurez un profil de conversation avec les sujets Cloud Pub/Sub que vous avez créés à l'étape précédente.
- Lorsque vous créez un profil de conversation, sélectionnez Notifications Pub/Sub, puis Activer les notifications Pub/Sub. Une fois l'option activée, vous pouvez cocher les cases à côté des types de notifications que vous souhaitez activer et saisir l'ID du sujet Cloud Pub/Sub associé à la notification.
- Sélectionnez
JSON
comme format de message pour chaque sujet.
Créer un compte de service pour l'identité de l'abonnement Pub/Sub
Créez un compte de service représentant l'identité de l'abonnement Pub/Sub à l'aide de la commande suivante:
$ gcloud iam service-accounts create cloud-run-pubsub-invoker \ --display-name "Cloud Run Pub/Sub Invoker"
Autorisez le compte de service à appeler votre service d'intercepteur
Exécutez la commande suivante :
$ 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
Créer des abonnements Cloud Pub/Sub pour des sujets
Pour chaque sujet que vous avez créé, vous devez créer un abonnement Cloud Pub/Sub correspondant.
Événements de nouvelle suggestion
Remplacez your-new-suggestion-topic-id
par le sujet Cloud Pub/Sub que vous avez configuré pour les nouvelles suggestions:
$ 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
Événements de nouveaux messages
Remplacez your-new-message-event-topic-id
par le sujet Cloud Pub/Sub que vous avez configuré pour les nouveaux événements de message:
$ 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
Événements de cycle de vie des conversations
Remplacez your-conversation-lifecycle-event-topic
par le sujet Cloud Pub/Sub que vous avez configuré pour les nouveaux événements de cycle de vie de la conversation:
$ 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
Nouveaux événements de notification des résultats de reconnaissance
$ 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