管理已部署代理的访问权限

不同访问模式有不同的身份验证方法：

使用场景 身份验证方法 此身份验证方法简介
直接从代理内访问数据源。 服务账号 已部署的代理可以访问其服务账号有权访问的所有资源。
使用代理中的 API 密钥向端点发送请求。 API 密钥 在使用此身份验证方法之前，请确定您要使用的 API 支持 API 密钥。
为代理的最终用户处理用户账号、注册、登录或授权。 OAuth 客户端 ID 要求您的代理向用户请求并征得用户同意。

角色

您在 Agent Engine 上部署的代理使用与 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 匹配的 AI Platform Reasoning Engine Service Agent 服务账号运行。

该服务账号具有 Vertex AI Reasoning Engine Service Agent 角色 (roles/aiplatform.reasoningEngineServiceAgent)，该角色可授予部署的代理所需的默认权限。您可以在 IAM 文档中查看默认权限的完整列表。

列出已部署代理的角色

控制台

  1. 前往 IAM 页面，然后勾选“包括 Google 提供的角色授权”复选框。

    转到 IAM

  2. 选择与您的 Google Cloud 项目对应的项目。

  3. 找到与 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 匹配的主账号。

  4. 您可以在“角色”列下找到已部署代理的角色。

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 基于在 Agent Engine 上部署代理时生成的服务账号。

如需了解详情，请参阅 IAM 文档和 CLI 参考文档。

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 基于在 Agent Engine 上部署代理时生成的服务账号。

为已部署的代理授予角色

  1. 前往 IAM 页面，然后勾选“包括 Google 提供的角色授权”复选框。

    转到 IAM

  2. 选择与您的 Google Cloud 项目对应的项目。

  3. 找到与 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 匹配的主账号。

  4. 依次点击“编辑”按钮、添加角色，然后点击“保存”按钮，向主账号添加所需的角色。

gcloud

首先，安装并初始化 gcloud CLI。然后运行以下命令：

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

其中

  • PRINCIPAL 基于在 Agent Engine 上部署代理时生成的服务账号。
  • ROLE_NAME 是您要授予的角色的名称。如需了解完整的预定义角色的列表，请参阅了解角色。

如需了解详情，请参阅 IAM 文档和 CLI 参考文档。

Python

我们不建议您编写自己的 Python 代码来为已部署的代理授予或撤消角色。我们建议您使用 Google Cloud 控制台或 gcloud 执行一次性操作，或者使用 Terraform 以编程方式管理 IAM 访问控制。如果您想或需要在 Python 中执行此操作，请参阅 IAM 客户端库文档。

撤消已部署代理的角色

  1. 前往 IAM 页面，然后勾选“包括 Google 提供的角色授权”复选框。

    转到 IAM

  2. 选择与您的 Google Cloud 项目对应的项目。

  3. 找到与 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 匹配的主账号。

  4. 如需从主账号撤消角色，请点击“修改”按钮，移除相应角色，然后点击“保存”按钮。

gcloud

首先，安装并初始化 gcloud CLI。然后运行以下命令：

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

其中

  • PRINCIPAL 基于在 Agent Engine 上部署代理时生成的服务账号。
  • ROLE_NAME 是您要撤消的角色的名称。如需了解完整的预定义角色的列表，请参阅了解角色。

如需了解详情，请参阅 IAM 文档和 CLI 参考文档。

Python

我们不建议您编写自己的 Python 代码来为已部署的代理授予或撤消角色。我们建议您使用 Google Cloud 控制台或 gcloud 执行一次性操作，或者使用 Terraform 以编程方式管理 IAM 访问控制。如果您想或需要在 Python 中执行此操作，请参阅 IAM 客户端库文档。

Secret

密文包含一个或多个密文版本，以及标签和复制信息等元数据。Secret 的实际载荷存储在Secret 版本中。Secret 在项目级进行管理（通过 Secret Manager），并且可以跨部署的代理共享。如需在 Secret Manager 中列出与代理对应的 Secret，您可以添加标签并将其用于过滤。

创建 Secret

控制台

  1. 前往 Secret Manager 页面。

    转到 Secret Manager

  2. 在 Secret Manager 页面上，点击创建密钥。

  3. 在 Name 字段中，输入 secret 的名称（例如 my-secret）。

  4. 可选：如需在创建初始 Secret 时也添加 Secret 版本，请在 Secret 值字段中输入 Secret 值（例如 abcd1234）。

  5. 前往标签，然后点击添加标签。

  6. 输入键及其对应的值以创建标签。

  7. 点击创建密钥。

gcloud

首先，安装并初始化 gcloud CLI。然后运行以下命令：

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 文档，了解如何创建 Secret 和 Secret 版本；或者参阅 CLI 参考文档，了解如何分别创建 Secret 和 Secret 版本。

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

控制台

  1. 前往 Secret Manager 页面。

    转到 Secret Manager

  2. 在 Secret Manager 页面上，点击要描述的 Secret 的名称。

  3. Secret 详细信息页面列出了有关 Secret 的信息。

gcloud

首先，安装并初始化 gcloud CLI。然后运行以下命令：

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

其中

  • VERSION_ID 是 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")
response = client.get_secret(request={"name": name})

列出 Secret

控制台

  1. 前往 Secret Manager 页面。

    转到 Secret Manager

  2. 在“密钥”表中，点击过滤条件字段。

  3. 选择过滤条件属性及其对应的值，例如 Location:asia-east1。

  4. 系统会根据输入的值自动过滤表格。

  5. （可选）如需过滤 Secret 版本：选择要访问其版本的 Secret，然后使用版本表中的过滤选项。

gcloud

首先，安装并初始化 gcloud CLI。

如需列出项目的所有密钥，请运行以下命令：

gcloud secrets list --filter="FILTER"

其中，FILTER 是字符串（例如 name:asecret OR name:bsecret）或正则表达式（例如 name ~ "secret_ab.*"）。

如需列出 Secret 的所有版本，请运行以下命令：

gcloud secrets versions list SECRET_ID

其中，SECRET_ID 是密钥的 ID 或密钥的完全限定标识符。

如需了解详情，请参阅 Secret Manager 文档，了解如何过滤 Secret 和列出 Secret 版本；或者参阅 CLI 参考文档，分别了解如何列出 Secret 和 Secret 版本。

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

控制台

  1. 前往 Secret Manager 页面。

    转到 Secret Manager

  2. 在 Secret Manager 页面上，点击 Secret 名称旁边的复选框。

  3. 如果信息面板已关闭，请点击显示信息面板以显示信息。

  4. 在信息面板中，选择标签标签页。

  5. 点击添加标签，然后输入标签的键和值。

  6. 点击保存。

gcloud

首先，安装并初始化 gcloud CLI。然后运行以下命令：

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}")

删除密钥

控制台

  1. 前往 Secret Manager 页面。

    转到 Secret Manager

  2. 在 Secret Manager 页面上的相应 Secret 的操作列中，点击查看更多。

  3. 在菜单中选择删除。

  4. 在删除密文对话框中，输入密文的名称。

  5. 点击删除密文按钮。

gcloud

首先，安装并初始化 gcloud CLI。

如需删除 Secret 版本，请运行以下命令：

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

其中

  • VERSION_ID 是 Secret 版本的资源名称，
  • SECRET_ID 是密钥的 ID 或密钥的完全限定标识符。

如需删除密文及其所有版本，请运行以下命令：

gcloud secrets delete SECRET_ID

其中，SECRET_ID 是密钥的 ID 或密钥的完全限定标识符

如需了解详情，请参阅 Secret Manager 文档，了解如何删除 Secret 和销毁 Secret 版本；或者参阅 CLI 参考文档，了解如何删除 Secret 和销毁 Secret 版本。

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 的代理，您需要执行以下操作：

  1. 创建 OAuth 客户端和凭据。

  2. 将客户端 ID 和 Secret 存储在 Secret Manager 中。（请参阅创建密钥）。

  3. 在开发期间访问代理中的 Secret。

创建 OAuth 客户端凭据

  1. 在 Google Cloud 控制台中，依次前往 Google Auth Platform > 客户端页面。

    依次前往“Google Auth Platform”>“客户端”

  2. （如有必要）如果屏幕上显示“尚未配置 Google Auth Platform”，请点击开始，然后填写项目配置。（您可以稍后更新这些信息。）如需详细了解正式版准备情况，请参阅 OAuth 2.0 政策合规性。

  3. 点击创建客户端。

  4. 将应用类型设置为 Web application。

  5. 将 OAuth 客户端的名称设置为 OAUTH_CLIENT_DISPLAY_NAME。

  6. 在已获授权的重定向 URI 下，添加 REDIRECT_URI 的 URI。

  7. 在“客户端密钥”下，点击“下载 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.
}}
  1. 将客户端 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 客户端

  1. 在 Google Cloud 控制台中，依次前往 Google Auth Platform > 客户端页面。

    依次前往“Google Auth Platform”>“客户端”

  2. 其中会列出您拥有的 OAuth 客户端凭据。

删除 OAuth 客户端

  1. 在 Google Cloud 控制台中，依次前往 Google Auth Platform > 客户端页面。

    依次前往“Google Auth Platform”>“客户端”

  2. 选择要删除的 OAuth 客户端凭据，然后点击“删除”。