代理可提供 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 函式,該工具就有可能呼叫該服務帳戶可存取的「任何」函式,即使使用者無法直接存取也一樣。
如要降低這類行為的潛在風險,請採取下列做法:
- 使用專屬專案:強烈建議您將代理應用程式部署在專屬專案中,與其他重要資源或機密函式分開。這項隔離措施可限制 CX Agent Studio 服務帳戶的權限範圍。
- 實作 VPC Service Controls: 使用 VPC Service Controls 定義機密服務的 service perimeter。這樣一來,您就能控管 Cloud Run functions 等服務的存取權,並防止 CX Agent Studio 服務帳戶發出不必要的呼叫。
- 遵循最小權限原則:確保 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,將憑證儲存為密鑰。以下是使用密鑰驗證工具的必要步驟:
- 如果還沒有密鑰,請建立密鑰。
- 將新 Secret 的 Secret Manager Secret 存取者 (
roles/secretmanager.secretAccessor) 角色授予 Customer Engagement Suite 服務代理。 - 將憑證複製到剪貼簿。
- 在 Secret 中新增 Secret 版本。將憑證貼上做為 Secret 值。
- 請省略結尾的任何換行字元。
- 複製剛才新增的密鑰版本名稱。名稱格式為
projects/{project_id}/secrets/{secret_id}/versions/{version_id}。使用這個密鑰版本設定工具。
不記名權杖
您可以設定不記名權杖驗證,在 OpenAPI 工具要求的 Authorization 標頭中,傳遞儲存在工作階段內容變數中的不記名權杖。如果代理需要將從使用者收集的權杖傳遞至其他 API,這個選項就非常實用。
請以下列格式指定工作階段內容變數:$context.variables.VARIABLE_NAME,其中 VARIABLE_NAME 是儲存不記名權杖的變數名稱。