Alat OpenAPI

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:

  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. Dengan begitu, Anda dapat mengontrol akses ke layanan seperti Cloud Run Functions dan mencegah panggilan yang tidak diinginkan dari akun layanan CX Agent Studio.
  3. 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:

  1. Buat secret Anda jika Anda belum memilikinya.
  2. Berikan peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) kepada Customer Engagement Suite Service Agent pada secret baru.
  3. Salin kredensial Anda ke papan klip.
  4. Tambahkan versi secret baru ke secret Anda. Tempelkan kredensial Anda sebagai nilai secret.
    • Hilangkan karakter baris baru di akhir.
  5. 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.