Halaman ini diterjemahkan oleh Cloud Translation API.

Mengintegrasikan modul backend dengan sistem Anda

Modul backend adalah solusi siap pakai yang menyediakan infrastruktur backend yang efektif untuk memproses pesan terkait fitur dalam jumlah besar dan berinteraksi dengan UI desktop agen. Tutorial ini akan memandu Anda melalui proses integrasi modul backend dengan sistem agen Anda.

Untuk informasi selengkapnya tentang konsep dan struktur modul latar belakang, lihat dokumentasi dasar-dasar modul backend.

Prasyarat

Instal Google Cloud CLI jika Anda belum mengonfigurasinya.

Menyiapkan variabel lingkungan

Untuk mempermudah perintah deployment, sebaiknya tetapkan variabel lingkungan yang berguna berikut di shell Anda. Anda dapat menetapkan variabel menggunakan contoh perintah berikut:

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

Tetapkan variabel lingkungan berikut:

GCP_PROJECT_ID: Project ID project Cloud Platform Anda yang menghosting resource terkait. Contoh: my-project.
SERVICE_REGION: Lokasi atau region layanan Anda dan resource Cloud Platform terkait. Contoh: us-central1.

Menyiapkan akun administratif

Sebaiknya gunakan akun Google Cloud terpisah untuk layanan administrasi dan identitas runtime. Administrasi layanan terutama dilakukan oleh manusia dengan akun Google, sedangkan identitas runtime memberikan izin layanan Cloud Run menggunakan akun layanan untuk mengaktifkan akses ke resource yang diperlukan.

Menyiapkan akun administratif manusia

Jika berencana menggunakan akun yang sudah memiliki izin Editor atau Pemilik di project, Anda dapat langsung melanjutkan ke bagian berikutnya.

Untuk mengelola infrastruktur backend, buat akun administrator dan beri peran IAM berikut. Semua izin mereka disertakan dalam peran dasar Editor (roles/editor) dan Pemilik (roles/owner).

roles/secretmanager.admin (Secret Manager Admin): Mengelola secret yang disimpan di secret manager untuk pembuatan dan verifikasi JWT.
roles/run.admin (Cloud Run Admin): Men-deploy dan mengelola layanan Cloud Run.
roles/iam.serviceAccountUser (Pengguna Akun Layanan): Memberikan izin iam.serviceAccounts.actAs ke akun layanan runtime Cloud Run.
roles/cloudbuild.builds.editor (Cloud Build Editor): Mem-build image Docker untuk layanan integrasi menggunakan Cloud Build.
Administrator Artifact Registry: Menyimpan dan mengelola image Docker yang di-build untuk layanan integrasi.
roles/pubsub.editor (Cloud Pub/Sub Editor): Membuat dan mengelola topik serta langganan Cloud Pub/Sub.
roles/redis.admin (Redis Admin): Membuat dan mengelola resource Memorystore for Redis.

Untuk memberikan peran IAM ke akun manusia, gunakan perintah Google Cloud CLI add-iam-policy-binding. Berikut adalah contoh perintah:

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

Menetapkan akun administratif manusia di gcloud

Ganti $ADMIN_ACCOUNT dengan akun administrator yang ingin Anda gunakan (misalnya: myaccount@gmail.com) dalam contoh berikut:

$ gcloud config set account $ADMIN_ACCOUNT

Menyiapkan akun layanan

Secara default, layanan atau tugas Cloud Run dijalankan sebagai Akun layanan Compute Engine default. Daripada menggunakan akun layanan default, sebaiknya berikan identitas khusus pada setiap layanan Cloud Run dengan menetapkan akun layanan yang dikelola pengguna dengan kumpulan izin minimum yang diperlukan. Jika berencana mempertahankan akun layanan default, Anda dapat langsung melanjutkan ke bagian menetapkan variabel lingkungan.

Membuat dua akun layanan untuk setiap runtime Cloud Run

Untuk membuat akun layanan, ganti nilai $CONNECTOR_SERVICE_ACCOUNT_ID dan $INTERCEPTOR_SERVICE_ACCOUNT_ID jika dan jalankan perintah berikut:

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

Gunakan contoh perintah berikut untuk menetapkan peran berikut ke akun layanan konektor UI dan konektor Cloud Pub/Sub:

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

--member='serviceAccount:$CONNECTOR_SERVICE_ACCOUNT_ID@$GCP_PROJECT_ID.' 

--role='roles/pubsub.editor'

Berikan peran IAM berikut ke akun layanan konektor UI:

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

Berikan peran berikut ke akun layanan konektor Cloud Pub/Sub:

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

Menetapkan variabel lingkungan

Tetapkan nilai variabel lingkungan berikut sebagai akun layanan yang baru saja Anda buat atau akun layanan Compute Engine default dalam project Anda.

CONNECTOR_SERVICE_ACCOUNT: Akun layanan untuk runtime konektor UI. Contoh: aa-ui-connector@my-project-id..
INTERCEPTOR_SERVICE_ACCOUNT: Akun layanan untuk runtime Cloud Pub/Sub Interceptor. Contoh: aa-pubsub-interceptor@my-project-id..

Menyesuaikan metode autentikasi pengguna

Repositori kode mendukung pengguna backend dan pengguna modul frontend untuk Genesys Cloud dan Twilio.

Dalam repositori kode, buka file ui_connector/auth.py.
Tentukan penyedia identitas yang didukung dengan menetapkan variabel lingkungan AUTH_OPTION atau terapkan metode autentikasi Anda dengan auth.check_auth.

Secara default, AUTH_OPTION kosong dan tidak ada pengguna yang diizinkan untuk mendaftarkan JWT dengan layanan UI Connector. Nilai yang didukung:
- 'Salesforce': Memverifikasi token autentikasi menggunakan Salesforce OpenID Connect. Variabel lingkungan yang diperlukan: SALESFORCE_ORGANIZATION_ID.
- 'GenesysCloud': Memverifikasi token autentikasi menggunakan Genesys SDK UsersAPI.
- 'Twilio': Memverifikasi token autentikasi untuk Twilio. Variabel lingkungan yang diperlukan: TWILIO_FLEX_ENVIRONMENT.
Contoh:
```
$ export AUTH_OPTION='Salesforce'
```
Setiap jenis token mungkin memiliki cara validasi yang berbeda. Anda yang menentukan cara token divalidasi. Tanpa perubahan apa pun, auth.check_auth akan menampilkan false untuk setiap permintaan.

Membuat dan menyimpan kunci rahasia JWT

Agar layanan konektor UI dapat mengirim token autentikasi yang aman kembali ke klien, layanan tersebut harus mengenkripsinya menggunakan kunci rahasia JWT. Nilai kunci dapat berupa string arbitrer apa pun, meskipun harus unik dan sulit ditebak.

Kunci rahasia ini akan disimpan di Secret Manager.

Menetapkan variabel lingkungan

JWT_SECRET_NAME: Nama untuk kunci secret di Secret Manager. Nama ini dapat berupa nama arbitrer apa pun. Nilai yang direkomendasikan: aa-integration-jwt-secret.

Membuat kunci

Sebaiknya buat hash acak sebagai kunci rahasia JWT agar tidak dapat ditebak oleh penyerang. Untuk melakukannya, Anda dapat menggunakan secret python untuk membuat angka acak yang aman.

Menyimpan kunci di Secret Manager

Pada contoh perintah berikut, ganti my_key dengan kunci rahasia yang ingin Anda gunakan.

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

Menyiapkan Memorystore for Redis

Untuk menyiapkan Redis, Anda memerlukan variabel lingkungan berikut:

VPC_CONNECTOR_NAME: Nama konektor Akses VPC Serverless Anda untuk menghubungkan layanan Cloud Run ke Memorystore untuk Redis. Nilai yang direkomendasikan: aa-integration-vpc.
VPC_NETWORK: Jaringan VPC yang akan dipasangkan dengan konektor Akses VPC Serverless Anda. Nilainya harus default jika Anda tidak menyiapkan VPC untuk project Google Cloud .
REDIS_IP_RANGE: Jaringan IP internal yang belum direservasi untuk konektor Akses VPC Serverless Anda. Diperlukan ruang /28 yang belum dialokasikan. Nilai yang direkomendasikan: 10.8.0.0/28 (nilai ini akan berfungsi untuk sebagian besar project baru).
REDIS_INSTANCE_ID: Nama untuk instance Redis Anda. Nilai yang direkomendasikan: aa-integration-redis.

Membuat instance Redis di region layanan Cloud Run Anda

Jalankan perintah berikut:

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

Membuat konektor Akses VPC Serverless

Pastikan API Akses VPC Serverless diaktifkan untuk project Anda:

$ gcloud services enable vpcaccess.googleapis.com

Buat konektor Akses VPC Serverless dengan rentang IP kustom:

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

Menyimpan host Redis dan port Redis sebagai variabel lingkungan

Tetapkan Alamat IP instance Redis Anda ke variabel lingkungan REDIS_HOST.
Tetapkan nomor port instance Redis Anda ke variabel lingkungan REDIS_PORT.

Men-deploy layanan konektor UI

Untuk layanan konektor UI, Anda memerlukan variabel lingkungan berikut:

CONNECTOR_SERVICE_NAME: Nama layanan Cloud Run Konektor UI Anda. Nilai yang direkomendasikan: ui-connector.
CONNECTOR_IMAGE_NAME: Nama image layanan Konektor UI Anda. URL ini dapat sama dengan CONNECTOR_SERVICE_NAME. Nilai yang direkomendasikan: ui-connector.

Membangun gambar Docker

Di folder /ui-connector, jalankan perintah berikut:

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

Men-deploy konektor UI ke Cloud Run

Di bagian folder /ui-connector, jalankan perintah berikut. Catat URL layanan untuk Konektor UI yang di-deploy, yang akan digunakan oleh klien (desktop agen).

$ 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

Men-deploy layanan interceptor Cloud Pub/Sub

Untuk layanan interceptor Pub/Sub, Anda memerlukan variabel lingkungan berikut:

INTERCEPTOR_SERVICE_NAME: Nama layanan Cloud Run dari interceptor Cloud Pub/Sub Anda. Nilai yang direkomendasikan: cloud-pubsub-interceptor.
INTERCEPTOR_IMAGE_NAME: Nama image layanan interceptor Cloud Pub/Sub Anda. Link ini dapat sama dengan INTERCEPTOR_SERVICE_NAME. Nilai yang direkomendasikan: cloud-pubsub-interceptor.

Membangun gambar Docker

Di folder /cloud-pubsub-interceptor, jalankan perintah berikut:

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

Men-deploy interceptor Pub/Sub ke Cloud Run

Di folder /cloud-pubsub-interceptor, jalankan perintah berikut:

$ 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

Menyimpan URL yang di-deploy

Tetapkan URL yang di-deploy sebagai variabel lingkungan INTERCEPTOR_SERVICE_URL.

Mengonfigurasi langganan Cloud Pub/Sub

Langganan Cloud Pub/Sub menggunakan hal berikut:

Topik
Profil percakapan
Akun layanan
Izin akun layanan untuk layanan interceptor
Peristiwa siklus proses percakapan

Membuat topik Cloud Pub/Sub

Buat topik Cloud Pub/Sub untuk setiap jenis notifikasi peristiwa yang Anda perlukan dari Dialogflow. Jenis notifikasi peristiwa yang tersedia adalah:

Peristiwa saran baru: Peristiwa yang dikirim saat saran Agent Assist baru tersedia (misalnya, saran Smart Reply baru sebagai respons terhadap ucapan pelanggan).
Peristiwa pesan baru: Peristiwa yang dikirim setiap kali ucapan baru dikenali dari agen atau pelanggan (misalnya, pelanggan mengucapkan Hi).
Peristiwa siklus proses percakapan baru: Peristiwa yang dikirim untuk perubahan siklus proses percakapan tertentu (misalnya, saat percakapan dimulai, atau saat percakapan selesai).
Peristiwa notifikasi hasil pengenalan baru: Peristiwa yang dikirim saat transkrip perantara dikenali dari agen atau pelanggan (misalnya, pelanggan mengucapkan Hi, how can I help you?, transkrip perantara adalah Hi how can saat pelanggan berbicara).

Catat ID topik dan nama topik untuk deployment backend nanti.

Mengonfigurasi profil percakapan

Konfigurasi profil percakapan dengan topik Cloud Pub/Sub yang Anda buat di langkah sebelumnya.

Saat membuat profil percakapan baru, pilih Notifikasi Pub/Sub, lalu Aktifkan notifikasi Pub/Sub. Setelah diaktifkan, Anda dapat mencentang kotak di samping jenis notifikasi yang ingin diaktifkan dan memasukkan ID topik untuk topik Cloud Pub/Sub terkait notifikasi.
Pilih JSON sebagai format pesan untuk setiap topik.

Membuat akun layanan untuk identitas langganan Pub/Sub

Buat akun layanan yang mewakili identitas langganan Pub/Sub menggunakan perintah berikut:

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

Berikan izin pada akun layanan untuk memanggil layanan interceptor Anda

Jalankan perintah berikut:

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

Membuat langganan Cloud Pub/Sub untuk topik

Untuk setiap topik yang Anda buat, Anda harus membuat langganan Cloud Pub/Sub yang sesuai.

Peristiwa saran baru

Ganti your-new-suggestion-topic-id dengan topik Cloud Pub/Sub yang Anda konfigurasikan untuk saran baru:

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

Peristiwa pesan baru

Ganti your-new-message-event-topic-id dengan topik Cloud Pub/Sub yang Anda konfigurasikan untuk peristiwa pesan baru:

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

Peristiwa siklus proses percakapan

Ganti your-conversation-lifecycle-event-topic dengan topik Cloud Pub/Sub yang Anda konfigurasi untuk peristiwa siklus proses percakapan baru:

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

Peristiwa notifikasi hasil pengenalan baru

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