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.

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

Menyisipkan variabel konteks sesi

Anda dapat menyuntikkan variabel dari konteks sesi, seperti ID sesi, ke dalam permintaan OpenAPI Anda. Gunakan kolom ekstensi x-ces-session-context dalam definisi parameter. Nilai harus berupa jalur ke variabel dalam objek context.

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 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 memitigasi potensi risiko yang terkait dengan perilaku ini:

  1. Gunakan Project Khusus: Sebaiknya deploy aplikasi agen dalam project khusus, yang 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 demikian, Anda dapat mengontrol akses ke layanan seperti Cloud Run Functions 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 dimaksud.

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. 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 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 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 adalah langkah-langkah yang diperlukan untuk mengautentikasi alat Anda menggunakan rahasia:

  1. Buat rahasia Anda jika Anda belum memilikinya.
  2. Beri peran Customer Engagement Suite Service Agent Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) pada secret baru.
  3. Salin kredensial Anda ke papan klip.
  4. Tambahkan versi secret baru ke secret Anda. Tempelkan kredensial Anda sebagai nilai secret.
    • Jangan sertakan karakter baris baru di akhir.
  5. Salin nama versi rahasia yang baru saja Anda tambahkan. Format namanya adalah projects/{project_id}/secrets/{secret_id}/versions/{version_id}. Gunakan versi rahasia ini untuk konfigurasi alat.