OpenAPI 工具

代理可提供 OpenAPI 結構定義,使用 OpenAPI 工具來連接外部 API。代理會代您呼叫 API。

限制:

  • 每個 OpenAPI 工具只能包含一個作業或函式。

結構定義範例:

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

插入工作階段情境變數

您可以將工作階段 ID 等工作階段內容中的變數,插入 OpenAPI 要求。在參數定義中使用 x-ces-session-context 擴充功能欄位。這個值應為 context 物件中變數的路徑。詳情請參閱「工作階段情境變數」。

例如:

      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

安全性考量

設定 OpenAPI 工具時,請務必瞭解權限的處理方式:

  • 工具執行身分:OpenAPI 工具執行的動作,會使用授予 CX Agent Studio 服務帳戶的權限,而非與代理互動的使用者直接權限。
  • 傳遞存取風險: 這表示如果 CX Agent Studio 服務帳戶有權叫用 Cloud Run 函式,該工具就有可能呼叫該服務帳戶可存取的「任何」函式,即使使用者無法直接存取也一樣。

如要降低這類行為的潛在風險,請採取下列做法:

  1. 使用專屬專案:強烈建議您將代理應用程式部署在專屬專案中,與其他重要資源或機密函式分開。這項隔離措施可限制 CX Agent Studio 服務帳戶的權限範圍。
  2. 實作 VPC Service Controls: 使用 VPC Service Controls 定義機密服務的 service perimeter。這樣一來,您就能控管 Cloud Run functions 等服務的存取權,並防止 CX Agent Studio 服務帳戶發出不必要的呼叫。
  3. 遵循最小權限原則:確保 CX Agent Studio 服務帳戶僅具備執行預期功能所需的最低必要 Identity and Access Management 角色和權限。

API 驗證

呼叫外部 API 時,支援下列驗證選項:

服務代理 ID 權杖

CX Agent Studio 可使用 Customer Engagement Suite 服務代理 (格式為 service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com) 產生 ID 權杖。當 CX Agent Studio 呼叫外部 API 時,系統會將權杖新增至授權 HTTP 標頭。

如果 Cloud Run functions 和 Cloud Run 服務與代理位於相同專案,則不需額外的 IAM 權限即可呼叫。如果兩者位於不同專案,只要將 roles/cloudfunctions.invoker 和 roles/run.invoker 角色授予服務代理位址,即可使用 ID 權杖存取 Cloud Run functions 和 Cloud Run 服務。

服務帳戶驗證

服務帳戶可用於驗證工具對任何支援的 Google API 發出的要求。提供服務帳戶電子郵件地址。

如果您尚未建立服務帳戶,請立即建立。

服務帳戶是主體,因此您可以授予角色,讓服務帳戶存取專案中的資源,就像為其他主體授予角色一樣。系統會使用服務帳戶電子郵件產生存取權杖,並在工具要求的 Authorization 標頭中傳送。

設定工具以使用服務帳戶的使用者,必須具備下列權限:

  • roles/iam.serviceAccountUser

為使 Dialogflow CX 產生權杖,Customer Engagement Suite 服務代理必須具備下列權限:

  • roles/iam.serviceAccountTokenCreator

服務帳戶也必須具備託管工具的服務存取權限。

OAuth

提供所用服務的 OAuth 資訊。

如果您使用 OAuth 存取 Google 服務,則需要為該服務設定 OAuth。

API 金鑰

如要設定 API 金鑰驗證,請提供金鑰名稱、要求位置 (標頭或查詢字串) 和 API 金鑰,讓 CX Agent Studio 在要求中傳遞 API 金鑰。使用 Secret Manager 密鑰版本提供 API 金鑰。

Secret Manager 驗證

您可以使用 Secret Manager,將憑證儲存為密鑰。以下是使用密鑰驗證工具的必要步驟:

  1. 如果還沒有密鑰,請建立密鑰。
  2. 將新 Secret 的 Secret Manager Secret 存取者 (roles/secretmanager.secretAccessor) 角色授予 Customer Engagement Suite 服務代理。
  3. 將憑證複製到剪貼簿。
  4. 在 Secret 中新增 Secret 版本。將憑證貼上做為 Secret 值。
    • 請省略結尾的任何換行字元。
  5. 複製剛才新增的密鑰版本名稱。名稱格式為 projects/{project_id}/secrets/{secret_id}/versions/{version_id}。使用這個密鑰版本設定工具。

不記名權杖

您可以設定不記名權杖驗證,在 OpenAPI 工具要求的 Authorization 標頭中,傳遞儲存在工作階段內容變數中的不記名權杖。如果代理需要將從使用者收集的權杖傳遞至其他 API,這個選項就非常實用。

請以下列格式指定工作階段內容變數:$context.variables.VARIABLE_NAME,其中 VARIABLE_NAME 是儲存不記名權杖的變數名稱。