Agen dapat terhubung ke API eksternal menggunakan alat OpenAPI dengan menyediakan skema OpenAPI. Agen akan memanggil API atas nama Anda.
Batasan:
- Setiap alat OpenAPI hanya dapat memiliki satu operasi atau fungsi.
Contoh skema:
openapi: 3.0.0
info:
title: Simple Pets API
version: 1.0.0
servers:
- url: 'https://api.pet-service-example.com/v1'
paths:
/pets/{petId}:
get:
summary: Return a pet by ID.
operationId: getPet
parameters:
- in: path
name: petId
required: true
description: Pet id
schema:
type: integer
responses:
200:
description: OK
/pets:
get:
summary: List all pets
operationId: listPets
parameters:
- name: petName
in: query
required: false
description: Pet name
schema:
type: string
- name: label
in: query
description: Pet label
style: form
explode: true
required: false
schema:
type: array
items:
type: string
- name: X-OWNER
in: header
description: Optional pet owner provided in the HTTP header
required: false
schema:
type: string
- name: X-SESSION
in: header
description: session id
required: true
schema:
type: string
x-ces-session-context: $context.session_id
responses:
'200':
description: An array of pets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
post:
summary: Create a new pet
operationId: createPet
requestBody:
description: Pet to add to the store
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
responses:
'201':
description: Pet created
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
components:
schemas:
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
owner:
type: string
label:
type: array
items:
type: string
Memasukkan variabel konteks sesi
Anda dapat memasukkan variabel dari konteks sesi,
seperti ID sesi, ke dalam permintaan OpenAPI.
Gunakan kolom ekstensi x-ces-session-context dalam definisi parameter.
Nilainya harus berupa jalur ke variabel dalam objek context.
Untuk mengetahui informasi selengkapnya, lihat
Variabel konteks sesi.
Contoh:
parameters:
- name: X-SESSION
in: header
description: session id
required: true
schema:
type: string
# This extension injects the session ID
x-ces-session-context: $context.session_id
Pertimbangan Keamanan
Saat mengonfigurasi alat OpenAPI, penting untuk memahami cara penanganan izin:
- Identitas Eksekusi Alat: Tindakan yang dilakukan oleh alat OpenAPI dijalankan menggunakan izin yang diberikan ke akun layanan CX Agent Studio, bukan izin langsung dari pengguna akhir yang berinteraksi dengan agen.
- Risiko Akses Transitif: Artinya, jika akun layanan CX Agent Studio memiliki izin untuk memanggil Cloud Run Functions, alat ini berpotensi memanggil fungsi apa pun yang dapat diakses oleh akun layanan tersebut, meskipun pengguna akhir tidak memiliki akses langsung.
Untuk mengurangi potensi risiko yang terkait dengan perilaku ini:
- Gunakan Project Khusus: Sebaiknya deploy aplikasi agen dalam project khusus, terpisah dari resource penting atau fungsi sensitif lainnya. Isolasi ini membatasi cakupan izin yang tersedia untuk akun layanan CX Agent Studio.
- Terapkan Kontrol Layanan VPC: Gunakan Kontrol Layanan VPC untuk menentukan perimeter layanan di sekitar layanan sensitif Anda. Dengan begitu, Anda dapat mengontrol akses ke layanan seperti Cloud Run Functions dan mencegah panggilan yang tidak diinginkan dari akun layanan CX Agent Studio.
- Ikuti Hak Istimewa Terendah: Pastikan akun layanan CX Agent Studio hanya diberi peran dan izin Identity and Access Management minimum yang diperlukan untuk fungsi yang diinginkan.
Autentikasi API
Opsi autentikasi berikut didukung saat memanggil API eksternal:
Token ID agen layanan
CX Agent Studio dapat membuat
token ID
menggunakan Agen layanan Customer Engagement Suite (dengan format: service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com).
Token ditambahkan di header HTTP otorisasi saat CX Agent Studio
memanggil API eksternal.
Jika Cloud Run Functions dan layanan Cloud Run berada dalam project yang sama dengan agen, Anda tidak memerlukan izin IAM tambahan untuk memanggilnya. Jika berada di project yang berbeda, token ID dapat digunakan untuk mengakses Cloud Run Functions dan layanan Cloud Run setelah Anda memberikan peran roles/cloudfunctions.invoker dan roles/run.invoker ke alamat agen layanan.
Autentikasi Akun Layanan
Akun layanan dapat digunakan untuk mengautentikasi permintaan alat ke Google API mana pun yang mendukungnya. Berikan alamat email akun layanan Anda.
Jika Anda belum melakukannya, buat akun layanan.
Karena akun layanan adalah akun utama,
akun layanan dapat mengakses resource dalam project Anda dengan
memberinya peran,
seperti yang Anda lakukan untuk akun utama lainnya.
Email akun layanan akan digunakan untuk
membuat token akses
yang akan dikirim di header Authorization permintaan alat.
Pengguna yang mengonfigurasi alat untuk menggunakan akun layanan harus memiliki izin berikut:
roles/iam.serviceAccountUser
Agar Dialogflow CX dapat membuat token, Agen layanan Customer Engagement Suite harus memiliki izin berikut:
roles/iam.serviceAccountTokenCreator
Akun layanan juga harus memiliki izin untuk mengakses layanan yang menghosting alat.
OAuth
Berikan informasi OAuth untuk layanan yang Anda gunakan.
Jika menggunakan OAuth untuk layanan Google, Anda harus mengonfigurasi OAuth untuk layanan tersebut.
Kunci API
Anda dapat mengonfigurasi autentikasi kunci API dengan memberikan nama kunci, lokasi permintaan (header atau string kueri), dan kunci API agar CX Agent Studio meneruskan kunci API dalam permintaan. Berikan kunci API Anda menggunakan versi rahasia Secret Manager.
Autentikasi Secret Manager
Anda dapat menyimpan kredensial sebagai secret menggunakan Secret Manager. Berikut adalah langkah-langkah yang diperlukan untuk mengautentikasi alat Anda menggunakan secret:
- Buat secret Anda jika Anda belum memilikinya.
- Berikan peran Secret Manager Secret Accessor
(
roles/secretmanager.secretAccessor) kepada Customer Engagement Suite Service Agent pada secret baru. - Salin kredensial Anda ke papan klip.
- Tambahkan versi secret baru ke secret Anda. Tempelkan kredensial Anda sebagai nilai secret.
- Hilangkan karakter baris baru di akhir.
- Salin nama versi secret yang baru saja Anda tambahkan. Format namanya adalah
projects/{project_id}/secrets/{secret_id}/versions/{version_id}. Gunakan versi rahasia ini untuk konfigurasi alat.
Token pemilik
Anda dapat mengonfigurasi autentikasi token pemilik untuk meneruskan token pemilik yang disimpan dalam
variabel konteks sesi
di header Authorization permintaan alat OpenAPI. Opsi ini berguna
saat agen perlu meneruskan token yang dikumpulkan dari pengguna akhir ke API lain.
Tentukan variabel konteks sesi dalam format berikut:
$context.variables.VARIABLE_NAME, dengan
VARIABLE_NAME adalah nama variabel yang
menyimpan token pemilik.