Alat OpenAPI

Agen dapat terhubung ke API eksternal menggunakan alat OpenAPI dengan memberikan skema OpenAPI. Agen akan memanggil API atas nama Anda.

Batasan:

  • Setiap alat OpenAPI hanya dapat memiliki satu operasi atau fungsi.

Skema contoh:

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

Menyuntikkan variabel konteks sesi

Anda dapat menyuntikkan 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 dieksekusi 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 fungsi Cloud Run, alat tersebut 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:

  1. 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.
  2. Terapkan Kontrol Layanan VPC: Gunakan Kontrol Layanan VPC untuk menentukan perimeter layanan di sekitar layanan sensitif Anda. Hal ini memungkinkan Anda mengontrol akses ke layanan seperti fungsi Cloud Run dan mencegah panggilan yang tidak diinginkan dari akun layanan CX Agent Studio.
  3. Ikuti Prinsip 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 fungsi Cloud Run dan layanan Cloud Run berada dalam project yang sama dengan agen, Anda tidak memerlukan izin IAM tambahan untuk memanggilnya. Jika berada dalam project yang berbeda, token ID dapat digunakan untuk mengakses fungsi Cloud Run dan layanan Cloud Run setelah Anda memberikan roles/cloudfunctions.invoker dan roles/run.invoker peran ke alamat agen layanan.

Autentikasi Akun Layanan

Akun layanan dapat digunakan untuk mengautentikasi permintaan alat ke Google API yang mendukungnya. Berikan alamat email akun layanan Anda.

Jika belum, buat akun layanan.

Karena akun layanan adalah akun utama, akun tersebut 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 Anda 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 sehingga CX Agent Studio meneruskan kunci API dalam permintaan. Berikan kunci API Anda menggunakan versi secret Secret Manager.

Autentikasi Secret Manager

Anda dapat menyimpan kredensial sebagai secret menggunakan Secret Manager. Berikut langkah-langkah yang diperlukan untuk mengautentikasi alat Anda menggunakan secret:

  1. Buat secret jika Anda belum memilikinya.
  2. Berikan peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) kepada Agen Layanan Customer Engagement Suite di secret baru.
  3. Salin kredensial Anda ke papan klip.
  4. Tambahkan versi secret baru ke secret Anda. Tempel kredensial Anda sebagai nilai secret.
    • Hapus karakter baris baru di akhir.
  5. Salin nama versi secret yang baru Anda tambahkan. Format nama adalah projects/{project_id}/secrets/{secret_id}/versions/{version_id}. Gunakan versi secret ini untuk konfigurasi alat.