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，為機密服務定義服務邊界。您可以藉此控管 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 函式和 Cloud Run 服務與代理程式位於同一個專案，您不需要額外的 IAM 權限即可呼叫這些函式和服務。如果位於不同專案，將 roles/cloudfunctions.invoker 和 roles/run.invoker 角色授予服務代理地址後，即可使用 ID 權杖存取 Cloud Run 函式和 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 Manager 密鑰存取者」(roles/secretmanager.secretAccessor) 角色授予新密鑰的「Customer Engagement Suite 服務代理」。
  3. 將憑證複製到剪貼簿。
  4. 為密鑰新增版本。將憑證貼到 Secret 值。
    • 結尾請省略任何換行字元。
  5. 複製您剛新增的密鑰版本名稱。名稱格式為 projects/{project_id}/secrets/{secret_id}/versions/{version_id}。 請使用這個密鑰版本設定工具。