Esta página foi traduzida pela API Cloud Translation.

Integrar módulos de back-end ao seu sistema

Os módulos de back-end são uma solução pronta para uso que fornece uma infraestrutura de back-end eficaz para processar grandes volumes de mensagens relacionadas a recursos e interagir com a UI para computador do agente. Neste tutorial, orientamos você no processo de integração de módulos de back-end com o sistema do agente.

Para mais informações sobre os conceitos e a estrutura dos módulos em segundo plano, consulte a documentação noções básicas de módulos de back-end.

Pré-requisitos

Instale a Google Cloud CLI, caso ainda não tenha configurado.

Configure as variáveis de ambiente

Para simplificar os comandos de implantação, recomendamos definir as seguintes variáveis de ambiente úteis no shell. Você pode definir as variáveis usando o comando de exemplo abaixo:

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

Configure as variáveis de ambiente a seguir:

GCP_PROJECT_ID: o ID do projeto do Cloud Platform que hospeda os recursos relacionados. Exemplo: my-project.
SERVICE_REGION: o local ou a região dos seus serviços e recursos relacionados do Cloud Platform. Exemplo: us-central1.

Configurar uma conta administrativa

Recomendamos o uso de contas Google Cloud separadas para a administração do serviço e a identidade de execução. A administração de serviços é realizada principalmente por pessoas com contas do Google, enquanto a identidade de execução concede permissões aos serviços do Cloud Run usando contas de serviço para permitir o acesso aos recursos necessários.

Preparar a conta administrativa humana

Se você planeja usar uma conta que já tem permissões de editor ou proprietário no seu projeto, pule para a próxima seção.

Para gerenciar a infraestrutura de back-end, estabeleça uma conta de administrador e conceda os seguintes papéis do IAM. As permissões deles estão incluídas nos papéis básicos Editor (roles/editor) e Proprietário (roles/owner).

roles/secretmanager.admin (Administrador do Secret Manager): gerenciar os segredos armazenados no Secret Manager para geração e verificação de JWTs.
roles/run.admin (administrador do Cloud Run): implanta e gerencia serviços do Cloud Run.
roles/iam.serviceAccountUser (Usuário da conta de serviço): conceda permissões iam.serviceAccounts.actAs às contas de serviço do ambiente de execução do Cloud Run.
roles/cloudbuild.builds.editor (Editor do Cloud Build): crie imagens do Docker para os serviços de integração usando o Cloud Build.
Administrador do Artifact Registry: armazena e gerencia imagens do Docker criadas para os serviços de integração.
roles/pubsub.editor (editor do Cloud Pub/Sub): crie e gerencie tópicos e assinaturas do Cloud Pub/Sub.
roles/redis.admin (administrador do Redis): crie e gerencie os recursos do Memorystore para Redis.

Para conceder papéis do IAM a uma conta de pessoa, use o comando add-iam-policy-binding da Google Cloud CLI. Confira um exemplo de comando:

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

Definir a conta administrativa humana no gcloud

Substitua $ADMIN_ACCOUNT pela conta de administrador que você quer usar (por exemplo, myaccount@gmail.com) no exemplo a seguir:

$ gcloud config set account $ADMIN_ACCOUNT

Configurar contas de serviço

Por padrão, os serviços ou jobs do Cloud Run são executados como a conta de serviço padrão do Compute Engine. Em vez de deixar o padrão, recomendamos dar a cada serviço do Cloud Run uma identidade dedicada, atribuindo a ele uma conta de serviço gerenciado pelo usuário com o conjunto mínimo de permissões necessárias. Se você planeja manter a conta de serviço padrão, pule para a etapa de definição de variáveis de ambiente.

Crie duas contas de serviço para cada ambiente de execução do Cloud Run

Para criar as contas de serviço, substitua o valor de $CONNECTOR_SERVICE_ACCOUNT_ID e $INTERCEPTOR_SERVICE_ACCOUNT_ID se e execute os seguintes comandos:

$ 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'

Use o comando de exemplo abaixo para atribuir os seguintes papéis ao conector da UI e às contas de serviço do conector do 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'

Conceda os seguintes papéis do IAM à conta de serviço do conector da UI:

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

Conceda os seguintes papéis à conta de serviço do conector do Cloud Pub/Sub:

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

Defina as variáveis de ambiente

Defina os valores das variáveis de ambiente a seguir como as contas de serviço que você acabou de criar ou a conta de serviço padrão do Compute Engine no seu projeto.

CONNECTOR_SERVICE_ACCOUNT: a conta de serviço para o ambiente de execução do conector da UI. Exemplo: aa-ui-connector@my-project-id.iam.gserviceaccount.com.
INTERCEPTOR_SERVICE_ACCOUNT: a conta de serviço para o ambiente de execução do Interceptor do Cloud Pub/Sub. Exemplo: aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com.

Personalizar o método de autenticação do usuário

O repositório de código oferece suporte a usuários de back-end e usuários do módulo de front-end para Genesys Cloud e Twilio.

No repositório de código, abra o arquivo ui_connector/auth.py.
Especifique o provedor de identidade compatível definindo a variável de ambiente AUTH_OPTION ou implemente seu método de autenticação com auth.check_auth.

Por padrão, AUTH_OPTION está vazio, e nenhum usuário pode registrar JWTs com o serviço de conector de interface. Valores aceitos:
- 'Salesforce': verifique o token de autenticação usando o OpenID Connect do Salesforce. Variável de ambiente obrigatória: SALESFORCE_ORGANIZATION_ID.
- 'GenesysCloud': verifique o token de autenticação usando a API Users do SDK Genesys.
- 'Twilio': verifique o token de autenticação do Twilio. Variável de ambiente obrigatória: TWILIO_FLEX_ENVIRONMENT.
Exemplo:
```
$ export AUTH_OPTION='Salesforce'
```
Cada tipo de token pode ter um meio de validação diferente. Você decide como o token é validado. Sem nenhuma mudança, auth.check_auth retorna false para cada solicitação.

Gerar e armazenar uma chave secreta JWT

Para que o serviço de conector da UI envie tokens de autenticação seguros de volta ao cliente, ele precisa criptografá-los usando uma chave secreta JWT. O valor da chave pode ser qualquer string arbitrária, mas precisa ser exclusivo e difícil de adivinhar.

Essa chave secreta será armazenada no Secret Manager.

Definir variável de ambiente

JWT_SECRET_NAME: o nome da chave secreta no Secret Manager. Pode ser qualquer nome arbitrário. Valor recomendado: aa-integration-jwt-secret.

Gerar a chave

Recomendamos gerar um hash aleatório como a chave secreta do JWT para que ela não possa ser adivinhada por invasores. Para fazer isso, use python secrets para gerar números aleatórios seguros.

Armazenar a chave no Secret Manager

No exemplo de comando abaixo, substitua my_key pela chave secreta que você planeja usar.

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

Configurar o Memorystore para Redis

Para configurar o Redis, você precisa das seguintes variáveis de ambiente:

VPC_CONNECTOR_NAME: o nome do conector de acesso VPC sem servidor para conectar os serviços do Cloud Run ao Memorystore para Redis. Valor recomendado: aa-integration-vpc.
VPC_NETWORK: a rede VPC a que o conector de acesso VPC sem servidor será anexado. O valor precisa ser default se você não configurar a VPC para o projeto Google Cloud .
REDIS_IP_RANGE: uma rede IP interna não reservada para o conector de acesso VPC sem servidor. É necessário ter /28 de espaço não alocado. Valor recomendado: 10.8.0.0/28 (esse valor deve funcionar na maioria dos novos projetos).
REDIS_INSTANCE_ID: um nome para a instância do Redis. Valor recomendado: aa-integration-redis.

Criar uma instância do Redis na região dos seus serviços do Cloud Run

Execute este comando:

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

Criar um conector de acesso VPC sem servidor

Verifique se a API Serverless VPC Access está ativada para seu projeto:

$ gcloud services enable vpcaccess.googleapis.com

Crie um conector de acesso VPC sem servidor com um intervalo de IP personalizado:

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

Salve o host e a porta do Redis como variáveis de ambiente

Defina o endereço IP da sua instância do Redis como a variável de ambiente REDIS_HOST.
Defina o número da porta da sua instância do Redis como a variável de ambiente REDIS_PORT.

Implantar o serviço de conector da UI

Para o serviço de conector da UI, você precisa das seguintes variáveis de ambiente:

CONNECTOR_SERVICE_NAME: o nome do serviço do Cloud Run do conector da interface. Valor recomendado: ui-connector.
CONNECTOR_IMAGE_NAME: o nome da imagem do serviço do conector de interface. Pode ser igual a CONNECTOR_SERVICE_NAME. Valor recomendado: ui-connector.

Compilar a imagem Docker

Na pasta /ui-connector, execute o seguinte comando:

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

Implantar o conector de interface no Cloud Run

Na pasta /ui-connector, execute o seguinte comando. Anote o URL do serviço do conector UI implantado, que será usado pelos clientes (computadores de agentes).

$ 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

Implantar o serviço de interceptação do Cloud Pub/Sub

Para o serviço de interceptação do Pub/Sub, você precisa das seguintes variáveis de ambiente:

INTERCEPTOR_SERVICE_NAME: o nome do serviço do Cloud Run do interceptor do Cloud Pub/Sub. Valor recomendado: cloud-pubsub-interceptor.
INTERCEPTOR_IMAGE_NAME: o nome da imagem do serviço de interceptação do Cloud Pub/Sub. Pode ser igual a INTERCEPTOR_SERVICE_NAME. Valor recomendado: cloud-pubsub-interceptor.

Compilar a imagem Docker

Na pasta /cloud-pubsub-interceptor, execute o seguinte comando:

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

Implantar o interceptor do Pub/Sub no Cloud Run

Na pasta /cloud-pubsub-interceptor, execute o seguinte comando:

$ 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

Salvar o URL implantado

Defina o URL implantado como a variável de ambiente INTERCEPTOR_SERVICE_URL.

Configurar assinaturas do Cloud Pub/Sub

As assinaturas do Cloud Pub/Sub usam:

Tópicos
Perfil de conversa
Conta de serviço
Permissão da conta de serviço para o serviço de interceptação
Eventos de ciclo de vida da conversa

Criar tópicos do Cloud Pub/Sub

Crie um tópico do Cloud Pub/Sub para cada tipo de notificação de evento que você precisa do Dialogflow. Os tipos de notificação de evento disponíveis são:

Eventos de nova sugestão: eventos enviados quando novas sugestões do Assistente são disponibilizadas (por exemplo, novas sugestões de Resposta inteligente em resposta a uma declaração do cliente).
Eventos de nova mensagem: eventos enviados sempre que uma nova frase é reconhecida por um agente ou cliente (por exemplo, o cliente diz Hi).
Novos eventos de ciclo de vida da conversa: eventos enviados para determinadas mudanças no ciclo de vida da conversa (por exemplo, quando uma conversa é iniciada ou concluída).
Novos eventos de notificação de resultado de reconhecimento: eventos enviados quando a transcrição intermediária é reconhecida de um agente ou cliente (por exemplo, o cliente diz Hi, how can I help you?, uma transcrição intermediária é Hi how can enquanto o cliente fala).

Anote o ID e o nome do tópico para a implantação do back-end.

Configurar um perfil de conversa

Configure um perfil de conversa com os tópicos do Cloud Pub/Sub que você criou na etapa anterior.

Ao criar um novo perfil de conversa, selecione Notificações do Pub/Sub e Ativar notificações do Pub/Sub. Depois de ativar, marque as caixas ao lado dos tipos de notificações que você quer ativar e insira o ID do tópico do Cloud Pub/Sub associado à notificação.
Selecione JSON como o formato da mensagem para cada tópico.

Criar uma conta de serviço para a identidade da assinatura do Pub/Sub

Crie uma conta de serviço que represente a identidade da assinatura do Pub/Sub usando o seguinte comando:

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

Conceda permissão à conta de serviço para invocar o serviço de interceptação

Execute este comando:

$ 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

Criar assinaturas do Cloud Pub/Sub para tópicos

Para cada tópico criado, você precisa criar uma assinatura correspondente do Cloud Pub/Sub.

Eventos de nova sugestão

Substitua your-new-suggestion-topic-id pelo tópico do Cloud Pub/Sub que você configurou para novas sugestões:

$ 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

Eventos de nova mensagem

Substitua your-new-message-event-topic-id pelo tópico do Cloud Pub/Sub que você configurou para novos eventos de mensagem:

$ 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

Eventos de ciclo de vida da conversa

Substitua your-conversation-lifecycle-event-topic pelo tópico do Cloud Pub/Sub que você configurou para novos eventos do ciclo de vida da conversa:

$ 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

Novos eventos de notificação de resultado de reconhecimento

$ 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