自 2025 年 4 月 29 日起，Gemini 1.5 Pro 和 Gemini 1.5 Flash 模型將無法用於先前未使用這些模型的專案，包括新專案。詳情請參閱「模型版本和生命週期」。

本頁面由 Cloud Translation API 翻譯而成。

管理已部署代理程式的存取權

不同存取模式可使用不同的驗證方法：

用途	驗證方式	關於這項驗證方法
直接從代理程式存取資料來源。	服務帳戶	已部署的代理程式可存取服務帳戶有權存取的所有資源。
使用代理程式中的 API 金鑰，將要求傳送至端點。	API 金鑰	請先確認要使用的 API 支援 API 金鑰，再使用這項驗證方法。
處理代理人使用者的使用者帳戶、註冊、登入或授權。	OAuth 用戶端 ID	要求您的服務專員向使用者要求並取得同意聲明。

角色

您在 Vertex AI Agent Engine 上部署的代理會使用與 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 相符的 AI Platform Reasoning Engine 服務代理 服務帳戶執行。

服務帳戶具有 Vertex AI 推理引擎服務代理人 角色 (roles/aiplatform.reasoningEngineServiceAgent)，可授予部署代理程式所需的預設權限。您可以在 IAM 說明文件中查看預設權限的完整清單。

列出已部署的代理人角色

主控台

前往「IAM」頁面，勾選「包含 Google 提供的角色授予項目」核取方塊。

前往身分與存取權管理頁面
選取與 Google Cloud 專案相對應的專案。
找出與 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 相符的主體。
已部署代理的角色會顯示在「角色」欄下方。

gcloud

首先安裝並初始化 gcloud CLI。然後執行下列指令：

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 上部署代理時產生的服務帳戶。

詳情請參閱 IAM 說明文件和指令列參考資料。

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 上部署代理時產生的服務帳戶。

授予已部署的代理人角色

控制台 (建議做法)

前往「IAM」頁面，勾選「包含 Google 提供的角色授予項目」核取方塊。

前往身分與存取權管理頁面
選取與 Google Cloud 專案相對應的專案。
找出與 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 相符的主體。
按一下「編輯」按鈕，然後新增角色，再按一下「儲存」按鈕，即可將必要角色新增至「主體」。

gcloud

首先安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

其中

PRINCIPAL 會根據在 Vertex AI Agent Engine 上部署代理時產生的服務帳戶。
ROLE_NAME 是您要授予的角色名稱。如需預先定義角色清單，請參閱「瞭解角色」一文。

詳情請參閱身分與存取權管理說明文件和 CLI 參考資料。

Python

我們不建議您自行編寫 Python 程式碼，為已部署的代理程式授予或撤銷角色。建議您改為使用 Google Cloud 控制台或 gcloud 執行一次性作業，或是使用 Terraform 以程式設計方式管理 IAM 存取權控管。如果您想或需要在 Python 中執行這項操作，請參閱 IAM 用戶端程式庫的說明文件。

撤銷已部署的代理人角色

控制台 (建議做法)

前往「IAM」頁面，勾選「包含 Google 提供的角色授予項目」核取方塊。

前往身分與存取權管理頁面
選取與 Google Cloud 專案相對應的專案。
找出與 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 相符的主體。
如要撤銷主體的角色，請按一下「編輯」按鈕，移除相應的角色，然後再按一下「儲存」按鈕。

gcloud

首先安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

其中

PRINCIPAL 會根據在 Vertex AI Agent Engine 上部署代理時產生的服務帳戶。
ROLE_NAME 是您要撤銷的角色名稱。如需預先定義角色清單，請參閱「瞭解角色」一文。

詳情請參閱身分與存取權管理說明文件和 CLI 參考資料。

Python

我們不建議您自行編寫 Python 程式碼，為已部署的代理程式授予或撤銷角色。建議您改為使用 Google Cloud 控制台或 gcloud 進行一次性作業，或是使用 Terraform 以程式設計方式管理 IAM 存取權控管。如果您想或需要在 Python 中執行這項操作，請參閱 IAM 用戶端程式庫的說明文件。

密鑰

密鑰包含一或多個密鑰版本，以及標籤和複製資訊等中繼資料。密鑰的實際酬載會儲存在密鑰版本中。密鑰會在專案層級 (透過 Secret Manager) 管理，並可跨部署的代理程式共用。如要在 Secret Manager 中列出與代理程式相對應的密鑰，您可以新增標籤並用於篩選。

建立密鑰

主控台

前往「Secret Manager」頁面。

前往 Secret Manager
在「Secret Manager」頁面中，按一下「Create Secret」。
在「Name」欄位中輸入密鑰的名稱 (例如 my-secret)。
選用步驟：如要在建立初始密鑰時新增密鑰版本，請在「密鑰值」欄位中輸入密鑰值 (例如 abcd1234)。
前往「標籤」，然後點選「新增標籤」。
輸入鍵和相應值，即可建立標籤。
按一下「Create secret」。

gcloud

首先安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

其中

SECRET_ID 是密鑰的 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 Manager」頁面中，按一下要說明的密鑰名稱。
「Secret details」(密鑰詳細資料) 頁面會列出密鑰相關資訊。

gcloud

首先安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

其中

VERSION_ID 是密鑰版本的 ID，
SECRET_ID 是密鑰的 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」頁面。

前往 Secret Manager
在「Secrets」表格中，按一下「Filter」欄位。
選擇篩選器屬性及其對應值，例如 Location:asia-east1。
系統會根據輸入的值自動篩選表格。
(選用) 如要篩選機密金鑰版本：選取要存取其版本的機密金鑰，然後使用「版本」表格中的「篩選」選項。

gcloud

首先安裝並初始化 gcloud CLI。

如要列出專案的所有 Secret，請執行下列指令：

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
在「Secret Manager」頁面中，勾選密鑰名稱旁的核取方塊。
如果「資訊面板」已關閉，請按一下「顯示資訊面板」來顯示。
在「資訊面板」中，選取「標籤」分頁標籤。
按一下「新增標籤」，然後輸入標籤的鍵和值。
按一下 [儲存]。

gcloud

首先安裝並初始化 gcloud CLI。然後執行下列指令：

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

其中

SECRET_ID 是密鑰的 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
在「Secret Manager」頁面的「Actions」欄中，按一下「View more」。
在選單中選取「刪除」。
在「Delete secret」對話方塊中，輸入密鑰名稱。
按一下「刪除密鑰」按鈕。

gcloud

首先安裝並初始化 gcloud CLI。

如要刪除密鑰版本，請執行下列指令：

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

其中

VERSION_ID 是密鑰版本的資源名稱，
SECRET_ID 是密鑰的 ID，或密鑰的完整修飾 ID。

如要刪除 Secret 及其所有版本，請執行下列指令：

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 用戶端和憑證

用戶端 ID 可讓 Google 的 OAuth 伺服器識別單一服務項目。如果您的服務項目是在多個平台上執行，則每個平台都需要專屬的用戶端 ID。整體來說，如要整合 OAuth 代理程式，請執行下列操作：

建立 OAuth 用戶端和憑證。
將用戶端 ID 和密鑰儲存在 Secret Manager 中。(請參閱「建立密鑰」)。
開發期間存取代理中的密鑰。

建立 OAuth 用戶端憑證

在 Google Cloud 控制台中，依序前往「Google Auth Platform」>「Clients」頁面。

依序前往「Google Auth Platform」>「Clients」
(視需要) 如果畫面顯示「尚未設定 Google 驗證平台」，請按一下「開始使用」，然後填寫專案設定。(之後可再更新)。如要進一步瞭解正式版完備性，請參閱「OAuth 2.0 政策遵循性」。
按一下「Create Client」。
將「Application type」設為 Web application。
將 OAuth 用戶端的名稱設為 OAUTH_CLIENT_DISPLAY_NAME。
在「已授權的重新導向 URI」下方，新增 REDIRECT_URI 的 URI。
按一下「Client Secrets」(用戶端密鑰) 下方的「download JSON」(下載 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」頁面。

依序前往「Google Auth Platform」>「Clients」
這裡會列出您擁有的 OAuth 用戶端憑證。

刪除 OAuth 用戶端

在 Google Cloud 控制台中，依序前往「Google Auth Platform」>「Clients」頁面。

依序前往「Google Auth Platform」>「Clients」
選取要刪除的 OAuth 用戶端憑證，然後按一下刪除。

管理已部署代理程式的存取權 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

角色

列出已部署的代理人角色

主控台

gcloud

Python

授予已部署的代理人角色

控制台 (建議做法)

gcloud

Python

撤銷已部署的代理人角色

控制台 (建議做法)

gcloud

Python

密鑰

建立密鑰

主控台

gcloud

Python

取得密鑰

主控台

gcloud

Python

列出密鑰

主控台

gcloud

Python

更新密鑰

主控台

gcloud

Python

刪除密鑰

主控台

gcloud

Python

OAuth 用戶端和憑證

建立 OAuth 用戶端憑證

列出 OAuth 用戶端

刪除 OAuth 用戶端

管理已部署代理程式的存取權