不同存取模式可用的驗證方法如下：
| 用途 | 驗證方式 | 關於這項驗證方式 |
|---|---|---|
| 直接從代理程式存取資料來源。 | 服務帳戶 | 已部署的代理程式可存取服務帳戶有權存取的所有資源。 |
| 在代理程式內使用 API 金鑰，將要求傳送至端點。 | API 金鑰 | 使用這種驗證方法前，請先確認要使用的 API 是否支援 API 金鑰。 |
| 處理代理程式使用者帳戶、註冊、登入或授權事宜。 | OAuth 用戶端 ID | 代理程式必須要求並取得使用者同意。 |
角色
在 Vertex AI Agent Engine 上部署的代理程式會使用 AI Platform Reasoning Engine 服務代理程式或自訂服務帳戶執行。詳情請參閱「為代理程式設定身分和權限」。
AI Platform Reasoning Engine 服務代理
AI Platform Reasoning Engine Service Agent 服務帳戶使用的格式為 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com。
服務帳戶具有「Vertex AI Reasoning Engine 服務代理人」角色 (roles/aiplatform.reasoningEngineServiceAgent)，可授予已部署代理程式所需的預設權限。如要查看預設權限的完整清單，請參閱 IAM 說明文件。
列出已部署代理程式的角色
主控台
前往身分與存取權管理頁面。
選取與您 Google Cloud 專案對應的專案。
找出與做為代理程式身分使用的服務帳戶相符的主體。
已部署代理程式的角色會顯示在「角色」欄下方。
gcloud
gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
--flatten="bindings[].members" \
--filter="bindings.members:serviceAccount:PRINCIPAL" \
--format="value(bindings.role)"其中
PROJECT_ID_OR_NUMBER是專案 ID 或編號，且PRINCIPAL是根據在 Vertex AI Agent Engine 上部署代理程式時使用的服務帳戶。
Python
首先，請執行下列指令來安裝用戶端程式庫：
pip install google-api-python-client然後驗證身分，並執行下列指令，列出已部署代理程式的角色：
from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2
project_id = "PROJECT_ID"
principal = "PRINCIPAL"
crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
resource=f"projects/{project_id}"
))
for binding in policy.bindings:
for member in binding.members:
if principal in member:
print(binding.role)
其中 PRINCIPAL 是以在 Vertex AI Agent Engine 上部署代理時使用的服務帳戶為準。
授予已部署代理程式的角色
控制台 (建議)
前往身分與存取權管理頁面。
選取與您 Google Cloud 專案對應的專案。
找出與做為代理程式身分使用的服務帳戶相符的主體。
按一下編輯按鈕，將必要角色新增至「主體」，然後按一下儲存按鈕。
gcloud
gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME其中
Python
我們不建議您自行編寫 Python 程式碼，授予或撤銷已部署代理程式的角色。建議您改用 Google Cloud 控制台或 gcloud 執行一次性作業，或是使用 Terraform 以程式輔助方式管理 IAM 存取權控管。如要在 Python 中執行這項操作，請參閱 IAM 用戶端程式庫的說明文件。
撤銷已部署代理程式的角色
控制台 (建議)
前往身分與存取權管理頁面。
選取與您 Google Cloud 專案對應的專案。
找出與做為代理程式身分使用的服務帳戶相符的主體。
按一下編輯按鈕，從「主體」撤銷角色，移除相應角色，然後按一下儲存按鈕。
gcloud
gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME其中
Python
我們不建議您自行編寫 Python 程式碼，授予或撤銷已部署代理程式的角色。建議您改用 Google Cloud 控制台或 gcloud 執行一次性作業，或是使用 Terraform 以程式輔助方式管理 IAM 存取權控管。如要在 Python 中執行這項操作，請參閱 IAM 用戶端程式庫的說明文件。
密鑰
一個 Secret 包含一或多個 Secret 版本，以及標籤和複製資訊等中繼資料。密鑰的實際酬載會儲存在密鑰版本中。密鑰是在專案層級透過 Secret Manager 管理，並可供已部署的代理程式共用。如要列出 Secret Manager 中與代理程式對應的密鑰，可以新增標籤並用於篩選。
建立密鑰
主控台
前往「Secret Manager」頁面。
在「Secret Manager」(密鑰管理員) 頁面中，按一下「Create Secret」(建立密鑰)。
在「Name」(名稱) 欄位中，輸入密鑰的名稱 (例如
my-secret)。選用步驟：如要在建立初始密鑰時一併新增密鑰版本，請在「Secret value」(密鑰值) 欄位中輸入密鑰值 (例如
abcd1234)。前往「標籤」，然後按一下「新增標籤」。
輸入鍵和對應的值，即可建立標籤。
按一下「建立密鑰」。
gcloud
gcloud secrets create SECRET_ID --replication-policy="automatic"gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"
其中
SECRET_ID是密鑰的 ID 或完整識別碼。FILE_PATH是包含版本詳細資料的檔案完整路徑 (包括檔案名稱)。
詳情請參閱 Secret Manager 說明文件，瞭解如何建立密鑰和密鑰版本，或參閱 CLI 參考資料，瞭解如何建立密鑰和密鑰版本。
Python
首先，請執行下列指令來安裝用戶端程式庫：
pip install google-cloud-secret-manager然後驗證身分，並執行下列
from google.cloud import secretmanager
import google_crc32c
client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
"parent": "projects/PROJECT_ID",
"secret_id": "SECRET_ID",
"secret": { # google.cloud.secretmanager_v1.types.Secret
# Required. The replication policy cannot be changed after the Secret has been created.
"replication": {"automatic": {}},
# Optional. Labels to associate with the secret.
"labels": {"type": "api_key", "provider": "anthropic"},
# Optional. The secret's time-to-live in seconds with format (e.g.,
# "900s" for 15 minutes). If specified, the secret versions will be
# automatically deleted upon reaching the end of the TTL period.
"ttl": "TTL",
},
})
anthropic_api_key = "API_KEY" # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)
version = client.add_secret_version(request={
"parent": secret.name,
"payload": {
"data": payload_bytes,
"data_crc32c": int(crc32c.hexdigest(), 16), # Optional.
},
})
print(f"Added secret version: {version.name}")
取得密鑰
主控台
前往「Secret Manager」頁面。
在「Secret Manager」頁面中，按一下要說明的密鑰名稱。
「Secret detail」(密鑰詳細資料) 頁面會列出密鑰相關資訊。
gcloud
gcloud secrets versions describe VERSION_ID --secret=SECRET_ID其中
VERSION_ID是密鑰版本的 ID，且SECRET_ID是密鑰的 ID，或是密鑰的完整識別碼。
詳情請參閱 Secret Manager 說明文件或 CLI 參考資料。
Python
首先，請執行下列指令來安裝用戶端程式庫：
pip install google-cloud-secret-manager然後驗證身分，並執行下列
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})
列出密鑰
主控台
前往「Secret Manager」頁面。
在「密鑰」表格中，按一下「篩選器」欄位。
選擇篩選器屬性和相應值，例如
Location:asia-east1。系統會根據輸入的值自動篩選表格。
(選用) 如要篩選密鑰版本，請選取密鑰來存取其版本，然後使用「版本」表格中的「篩選器」選項。
gcloud
如要列出專案的所有密鑰，請執行下列指令：
gcloud secrets list --filter="FILTER"其中 FILTER 是字串 (例如 name:asecret OR name:bsecret) 或規則運算式 (例如 name ~ "secret_ab.*")。
如要列出密碼的所有版本，請執行下列指令：
gcloud secrets versions list SECRET_ID其中 SECRET_ID 是密鑰的 ID 或完整識別碼。
詳情請參閱 Secret Manager 說明文件，瞭解如何篩選密鑰和列出密鑰版本，或參閱 CLI 參考資料，瞭解如何分別列出密鑰和密鑰版本。
Python
首先，請執行下列指令來安裝用戶端程式庫：
pip install google-cloud-secret-manager然後驗證身分，並執行下列
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
"parent": "projects/PROJECT_ID",
"filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
print(f"Found secret: {secret.name}")
更新密鑰
主控台
前往「Secret Manager」頁面。
在「Secret Manager」(密鑰管理工具) 頁面中，勾選密鑰名稱旁的核取方塊。
如果「資訊面板」已關閉，請按一下「顯示資訊面板」。
在「資訊面板」中，選取「標籤」分頁標籤。
按一下「新增標籤」，然後輸入標籤的鍵和值。
按一下 [儲存]。
gcloud
gcloud secrets update SECRET_ID --update-labels=KEY=VALUE其中
SECRET_ID是密鑰的 ID 或密鑰的完整識別碼，KEY是標籤鍵，VALUE是標籤的對應值。
詳情請參閱 Secret Manager 說明文件或 CLI 參考資料。
Python
首先，請執行下列指令來安裝用戶端程式庫：
pip install google-cloud-secret-manager然後驗證身分，並執行下列
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
"secret": {
"name": name,
"labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
},
"update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")
刪除密鑰
主控台
前往「Secret Manager」頁面。
在「Secret Manager」頁面的「動作」欄中，按一下密鑰的「查看更多」。
在選單中選取「刪除」。
在「Delete secret」(刪除密鑰) 對話方塊中，輸入密鑰名稱。
按一下「刪除密鑰」按鈕。
gcloud
如要刪除密鑰版本，請執行下列指令：
gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID其中
VERSION_ID是密鑰版本的資源名稱，且SECRET_ID是密鑰的 ID，或是密鑰的完整識別碼。
如要刪除密鑰及其所有版本，請執行下列指令：
gcloud secrets delete SECRET_ID其中 SECRET_ID 是密鑰的 ID 或密鑰的完整識別碼
詳情請參閱 Secret Manager 說明文件，瞭解如何刪除密鑰和刪除密鑰版本，或參閱 CLI 參考資料，瞭解如何刪除密鑰和刪除密鑰版本。
Python
首先，請執行下列指令來安裝用戶端程式庫：
pip install google-cloud-secret-manager然後驗證身分，並執行下列
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})
OAuth 用戶端和憑證
Google 的 OAuth 伺服器會使用用戶端 ID 來識別個別代理程式。如果代理程式在多個平台上執行，則每個平台都需要專屬的用戶端 ID。如要整合以 OAuth 為基礎的代理程式，大致上需要執行下列操作：
建立 OAuth 用戶端憑證
在 Google Cloud 控制台中，前往「Google Auth Platform」>「Clients」(用戶端) 頁面。
(如有需要) 如果畫面顯示「尚未設定 Google 驗證平台」，請按一下「開始使用」，然後填寫「專案設定」。(稍後可再更新)。如要瞭解正式版準備狀態的詳細資訊，請參閱「OAuth 2.0 政策規範」。
按一下「建立用戶端」。
將「Application type」(應用程式類型) 設為
Web application。將 OAuth 用戶端名稱設為
OAUTH_CLIENT_DISPLAY_NAME。在「Authorized redirect URIs」(已授權的重新導向 URI) 下方，新增
REDIRECT_URI的 URI。在「用戶端密鑰」下方，按一下「下載 JSON」按鈕。系統會下載
client_secret.json檔案，其中包含下列內容：
{'web': {
'client_id': "CLIENT_ID",
'client_secret': "CLIENT_SECRET",
'project_id': "PROJECT_ID",
'redirect_uris': [REDIRECT_URIs],
'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
'javascript_origins': "JAVASCRIPT_ORIGINS", # Optional.
}}
- 將用戶端 ID 和密鑰儲存在 Secret Manager 中，例如：
from google.cloud import secretmanager
import google_crc32c
import json
client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
"parent": "projects/PROJECT_ID",
"secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
"secret": {
"labels": {"type": "oauth_client"},
"replication": {"automatic": {}},
},
})
payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)
client.add_secret_version(request={
"parent": secret.name,
"payload": {
"data": payload_bytes,
"data_crc32c": int(crc32c.hexdigest(), 16),
},
})
列出 OAuth 用戶端
在 Google Cloud 控制台中，前往「Google Auth Platform」>「Clients」(用戶端) 頁面。
系統會列出您擁有的 OAuth 用戶端憑證。
刪除 OAuth 用戶端
在 Google Cloud 控制台中，前往「Google Auth Platform」>「Clients」(用戶端) 頁面。
選取要刪除的 OAuth 用戶端憑證，然後按一下「刪除」。
由客戶管理的加密金鑰 (CMEK)
根據預設， Google Cloud 會使用 Google 代管的加密金鑰，自動加密靜態資料。如果您有與資料保護金鑰相關的特定法規遵循或監管要求，可以為已部署的代理程式使用客戶自行管理的加密金鑰 (CMEK)。
如需一般規定和搭配 Vertex AI 使用 CMEK 的指南，請參閱 Vertex AI 適用的 CMEK 說明文件，包括：
- 專案設定 (計費和已啟用的 API)
- 建立金鑰環和金鑰
- 必須授予的權限
如要為代理程式啟用 CMEK，您必須在建立 Agent Engine 執行個體時，使用 Cloud KMS 金鑰指定 encryption_spec。如需程式碼範例，請參閱「設定客戶管理的加密金鑰」。
限制
將 CMEK 與 Vertex AI Agent Engine 搭配使用時，請注意下列限制：
不允許使用多區域金鑰：系統僅支援單一區域金鑰。金鑰環和金鑰的區域必須與 Agent Engine 執行個體相同。
已部署的 CMEK 執行個體無法更新：使用 CMEK 金鑰部署代理程式後，該部署作業的執行個體就無法更新或變更。如要使用其他 Agent Engine 規格 (適用於新金鑰或其他設定)，請部署新的 Agent Engine 執行個體。
部分中繼資料和作業資料不會加密：CMEK 會加密代理程式的核心靜態資料。不過，特定中繼資料和執行階段作業資料不會加密。包括：
- 代理程式中繼資料：
- 顯示名稱
- 說明
- 執行階段營運資料：
- 服務帳戶電子郵件地址
- 代理物件類別方法名稱
- 環境變數
- 代理程式中繼資料：