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 interface 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 CLI do Google Cloud, 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. É possível 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 do ambiente 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 CLI do Google Cloud. 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 gerenciada 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 interface 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 IU:

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 interface. 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 JWT 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 interface 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 IU

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

CONNECTOR_SERVICE_NAME: o nome do serviço do Cloud Run do conector de 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 de interface 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:

Novos eventos de sugestão: eventos enviados quando novas sugestões do Assistente do Google estão disponíveis (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 do 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