根据 YAML 模板创建 API 代理

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

Beta 版

此功能正处于 Beta 版阶段，随时可能会变更。它受 Google Cloud 服务条款的正式发布前产品条款的约束。对正式发布前功能的支持可能有限，并且对正式发布前功能的更改可能不兼容其他正式发布前版本。如需了解详情，请参阅发布阶段说明。

本页面介绍了如何使用 YAML 将 API 代理定义为 Apigee 功能模板，并使用 Google Cloud CLI 部署该模板。您将先构建一个简单的代理，然后构建一个更完整的示例，该示例位于 Gemini 模型的前端。

如需了解相关背景信息，请参阅使用 YAML 配置代理。如需查看完整架构，请参阅 API 代理 YAML 配置参考。

准备工作

• 在 Google Cloud 项目中启用 Vertex AI API，以便代理可以与 Gemini 模型通信。

  gcloud services enable aiplatform.googleapis.com

• 安装并初始化 Google Cloud CLI。
• 如需访问本教程中使用的命令，请安装 gcloud beta 组件：

  gcloud components install beta

• 拥有 Apigee 组织和至少一个环境。记下组织和环境名称；示例使用 ORG 和 ENV 作为占位符。第 2 部分中的 AI 网关还需要中级或综合环境（而非基本环境）；请参阅 Apigee 环境类型。
• 确保您拥有所需的权限：
  • 如需导入（创建）API 代理：API Admin 角色 (roles/apigee.apiAdmin)，或授予 apigee.proxies.create 的同等角色。
  • 如需部署 API 代理，您必须拥有目标环境的 Environment Admin (roles/apigee.environmentAdmin) 角色，以及项目级的 API Reader (roles/apigee.apiReaderV2) 角色。
  • 如需创建在第 2 部分第 6 步中生成 API 密钥的 API 产品、开发者和应用，您需要拥有 API Admin (roles/apigee.apiAdmin) 和 Developer Admin (roles/apigee.developerAdmin) 角色。如需查看完整角色列表，请参阅 Apigee 角色。

注意：如果活跃的 Google Cloud 项目与 Apigee 组织相关联，则可以在每个命令中省略 --organization；CLI 随后会自动使用该组织。 如需查看 CLI 当前使用的项目，请运行 gcloud config get-value project；如需更改项目，请运行 gcloud config set project PROJECT_ID。

第 1 部分：创建简单的 API 代理

在本部分中，您将创建一个代理，用于将请求转发到 Apigee 模拟目标服务并强制执行速率限制。

第 1 步：创建模板

模板是您部署的文件。它定义了代理的基本路径、路由和后端目标，并列出了要包含的功能。

为您的代理创建一个目录，然后创建一个名为 hello-proxy.yaml 的文件：

gateway: apigee
schemaVersion: 1.0.0
name: hello-proxy
type: template
description: A simple proxy to the Apigee mock target, protected by a rate limit.
features:
- spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

此模板定义了以下内容：

• 基本路径为 /hello 的端点。客户端通过此路径调用代理。
• 将请求发送到名为 default 的目标的路由。
• 指向后端网址的目标。
• 接下来，您将创建一个功能 spike-arrest.yaml。

注意：name 字段 (hello-proxy) 是写入代理软件包的名称。导入代理时，Apigee 中的代理名称来自命令行实参。请保持两者一致，以免造成混淆。

第 2 步：创建功能

功能是包含政策的可重复使用的配置单元。模板不能直接包含政策，因此速率限制政策位于功能中。

在与模板相同的目录中，创建一个名为 spike-arrest.yaml 的文件：

gateway: apigee
schemaVersion: 1.0.0
name: spike-arrest
displayName: Spike Arrest
type: feature
description: Protects the backend by smoothing traffic spikes.
categories:
- traffic
parameters:
- name: RATE
  displayName: RATE
  description: Maximum request rate, for example 30ps (per second) or 100pm (per minute).
  default: 30ps
  examples:
  - 30ps
  - 100pm
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: SA-SpikeArrest
policies:
- name: SA-SpikeArrest
  type: SpikeArrest
  content:
    SpikeArrest:
      metadata:
        name: SA-SpikeArrest
        enabled: "true"
        continueOnError: "false"
      DisplayName: SA-SpikeArrest
      Rate: "{RATE}"

此功能：

• 定义用于限制请求速率的 SpikeArrest 政策。
• 使用 defaultEndpoint.flows 将政策添加到请求 PreFlow，以便针对每个请求运行该政策。
• 声明一个形参 RATE，当代理被编译时，其默认值 (30ps) 会替换为 {RATE}。

注意：参数值会解析为功能中定义的 default。如需使用其他费率，请修改 default 值。

重要提示：模板引用的每个功能文件都必须与模板文件位于同一目录中。

第 3 步：导入代理

导入模板以创建 API 代理修订版本。从包含文件的目录中运行此命令：

gcloud beta apigee apis import hello-proxy \
    --from-template=hello-proxy.yaml \
    --organization=ORG

CLI 会将模板及其功能编译为 API 代理软件包，然后上传该软件包并输出新的代理修订版本。导入操作会创建修订版本，但不会部署该版本。

注意：每次导入时，Apigee 都会创建一个新修订版本，而不是覆盖现有版本。

第 4 步：部署代理

将修订版本部署到环境：

gcloud apigee apis deploy \
    --api=hello-proxy \
    --environment=ENV \
    --organization=ORG

默认情况下，此命令会部署最新修订版本。如需部署特定修订版本，请将其编号作为第一个实参传递，例如 gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV。 如果已在同一基本路径中部署了其他代理，请添加 --override 以零停机时间替换该代理。

第 5 步：调用代理

如需通过网络调用已部署的代理，您的环境必须连接到具有可路由主机名的环境组。如果您刚刚创建组织，请在调用代理之前确认已设置此项；请参阅关于环境和环境组。

查找包含您的环境的环境组的主机名：

1. 在 Google Cloud 控制台中，依次前往 Apigee > 管理 > 环境。
2. 选择环境组标签页。
3. 找到包含您的环境的环境组，然后从其主机名列中复制一个值。

使用模板中的基本路径，在该主机名处调用代理：

curl https://HOSTNAME/hello

将 HOSTNAME 替换为您复制的主机名。成功的响应来自模拟目标服务。

注意：部署命令返回后，部署可能需要短时间才能开始提供流量，因此您可能需要等待片刻，然后重试。如果该调用返回 HTTP 503 并带有 no healthy upstream，则表示环境的运行时路由（环境组主机名和负载均衡器）未为该环境提供服务；请验证您的环境组和主机名配置。

第 2 部分：为 Gemini 构建 AI 网关

本部分将构建一个更完整的代理：一个 AI 网关，可将请求转发到 Vertex AI 上的 Gemini 模型，强制执行速率限制，并要求提供 API 密钥。它使用一个模板、三个功能和一个服务账号。

与第 1 部分中的简单代理不同，此代理会调用 Google Cloud 服务 (Vertex AI)。gemini-target 功能使用 auth: GoogleAccessToken，因此 Apigee 会将 Google OAuth 令牌附加到对 Vertex AI 的每个请求。该令牌是为您创建并随后在部署代理时提供的服务账号签发的，因此这部分内容增加了一个创建该服务账号的步骤（第 3 步）。

注意：此处需要服务账号，只是因为此代理会向 Google Cloud 后端进行身份验证；第 1 部分中的代理不需要服务账号。如需了解完整说明，请参阅使用 Google 身份验证。

第 1 步：创建模板

创建一个名为 ai-gateway.yaml 的文件：

gateway: apigee
schemaVersion: 1.0.0
name: ai-gateway
type: template
description: AI gateway that fronts a Gemini model with throttling and API key enforcement.
features:
- spike-arrest.yaml
- verify-api-key.yaml
- gemini-target.yaml
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

第 2 步：创建特征

在同一目录中，创建这三个功能文件。

重复使用第 1 部分中的 spike-arrest.yaml 功能。

创建 verify-api-key.yaml 以要求在 x-api-key 标头中提供 API 密钥：

gateway: apigee
schemaVersion: 1.0.0
name: verify-api-key
displayName: Verify API Key
type: feature
description: Requires a valid API key in the x-api-key request header.
categories:
- security
defaultEndpoint:
  name: default
  flows:
  - name: PreFlow
    mode: Request
    steps:
    - name: VA-VerifyAPIKey
policies:
- name: VA-VerifyAPIKey
  type: VerifyAPIKey
  content:
    VerifyAPIKey:
      metadata:
        name: VA-VerifyAPIKey
        enabled: "true"
        continueOnError: "false"
      DisplayName: VA-VerifyAPIKey
      APIKey:
        metadata:
          ref: request.header.x-api-key

创建 gemini-target.yaml 以路由到经过 Google 访问令牌身份验证的 Gemini 模型：

gateway: apigee
schemaVersion: 1.0.0
name: gemini-target
displayName: Gemini Target
type: feature
description: Routes requests to a Gemini model on Vertex AI, authenticated with a Google access token.
categories:
- llm
targets:
- name: gemini
  url: https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent
  auth: GoogleAccessToken
  scopes:
  - https://www.googleapis.com/auth/cloud-platform

将 PROJECT_ID 替换为您的 Google Cloud 项目 ID，并将 REGION 替换为您使用的 Vertex AI 区域（例如 us-central1）。此功能使用 auth: GoogleAccessToken，以便 Apigee 将 Google 访问令牌附加到对 Vertex AI 的每个请求。

模型并非在所有地区都可用，并且网址取决于您使用的地区。上述网址是区域性网址，适用于从特定区域（例如 us-central1 中的 gemini-2.5-flash）提供的模型。其他模型仅通过全球端点提供，该端点使用不同的主机和 locations/global：

  url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent

如需查找模型支持的位置，请参阅 Vertex AI 上的生成式 AI 位置。

注意：如果您在调用代理时 Vertex AI 返回 404 Not Found，则表示您指定的位置没有可用的模型（请切换到受支持的区域或使用全局网址），或者 Vertex AI API 未启用。

第 3 步：为代理创建服务账号

由于 gemini-target 功能使用 auth: GoogleAccessToken，因此部署的代理会以服务账号的身份调用 Vertex AI。创建该服务账号，授予其对 Vertex AI 的访问权限，并允许 Apigee 服务代理使用该服务账号。您可以在第 5 步中部署代理时提供此服务账号。如需了解详情，请参阅使用 Google 身份验证。

1. 在与 Apigee 组织相同的 Google Cloud 项目中创建用户代管式服务账号。（系统不接受 Compute Engine 默认服务账号。）如需了解其他创建方式，请参阅创建和管理服务账号。

   gcloud iam service-accounts create SA_NAME \
       --project=PROJECT_ID \
       --display-name="Apigee AI gateway"

   这会创建服务账号 SA_NAME@PROJECT_ID.。

2. 向服务账号授予对所调用后端的访问权限。对于 Vertex AI 目标，授予 Vertex AI User 角色 (roles/aiplatform.user)：

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:SA_NAME@PROJECT_ID." \
       --role="roles/aiplatform.user"

   如果项目的 IAM 政策已包含条件角色绑定，请向此命令添加 --condition=None。

3. 通过向服务账号授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)，允许 Apigee 服务代理为该服务账号生成令牌：

   gcloud iam service-accounts add-iam-policy-binding \
       SA_NAME@PROJECT_ID. \
       --project=PROJECT_ID \
       --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee." \
       --role="roles/iam.serviceAccountTokenCreator"

   如需查找 PROJECT_NUMBER，请运行 gcloud projects describe PROJECT_ID --format='value(projectNumber)'。

注意：如需使用服务账号部署代理，您用于部署的身份需要拥有该服务账号的 iam.serviceAccounts.actAs 权限（例如，通过服务账号用户角色）。如需查看所需权限的完整列表，请参阅服务账号简介。

第 4 步：导入代理

导入模板以创建 API 代理修订版本：

gcloud beta apigee apis import ai-gateway \
    --from-template=ai-gateway.yaml \
    --organization=ORG

记下命令输出中的修订版本号；您需要在第 5 步中使用该版本号。如需仅输出修订版本号，请在导入命令中添加 --format="value(revision)"。

第 5 步：使用服务账号部署代理

部署 AI 网关与第 1 部分中的简单代理在以下两个方面有所不同：

• 您必须提供在第 3 步中创建的服务账号。如果您在部署时未提供此文件，则部署会失败并显示 MISSING_SERVICE_ACCOUNT 错误。
• 您必须部署到中级环境或综合环境中。 此代理使用可扩展政策，而基础环境不支持该政策；如果部署到基础环境，则会失败并显示错误可扩展代理无法部署到基础环境。请参阅 Apigee 环境类型。

注意：gcloud apigee apis deploy 命令不接受服务账号，因此请使用 Apigee 界面或部署 API 部署此代理，如下所示。如需了解常规部署说明，请参阅部署 API 代理。

Apigee 界面：部署代理，并在系统提示输入服务账号时，输入 SA_NAME@PROJECT_ID.。 如需了解相关步骤，请参阅部署 API 代理。

Deployment API：调用 deployments API，并将服务账号作为 serviceAccount 查询参数传递。将 REVISION 替换为第 4 步中的修订版本号：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments?serviceAccount=SA_NAME@PROJECT_ID."

部署请求会立即返回；部署是异步的。轮询修订版本的部署状态，该状态在变为 READY 之前会报告 PROGRESSING：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"

编译代理时，spike-arrest 和 verify-api-key 功能会将各自的政策添加到请求 PreFlow（先进行速率限制，然后检查 API 密钥），而 gemini-target 功能会添加 Vertex AI 后端。部署完成后，代理会以您的服务账号身份向 Vertex AI 进行身份验证。

第 6 步：获取 API 密钥

verify-api-key 功能会拒绝任何未携带有效 API 密钥的请求，因此您需要先获取密钥，然后才能调用代理。API 密钥是与包含此代理的 API 产品相关联的开发者应用的凭据。完成以下任务（如发布概览中所述）：

1. 创建 API 产品，其中包含 ai-gateway 代理以及您将该代理部署到的环境。
2. 注册应用开发者。
3. 注册与该 API 产品相关联的开发者应用。

注册应用会生成密钥。如需检索，请参阅查看 API 密钥和 Secret。

第 7 步：调用代理

按照第 1 部分第 5 步中所述查找环境组的主机名，然后调用基本路径为 /v1/gemini 的代理。在 x-api-key 标头中传递 API 密钥，并发送 Gemini generateContent 请求正文：

curl -X POST https://HOSTNAME/v1/gemini \
    -H "x-api-key: API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'

将 HOSTNAME 替换为您的环境组主机名，并将 API_KEY 替换为第 6 步 中的密钥。成功响应是模型的 JSON 输出。省略密钥会导致 VerifyAPIKey 政策返回授权失败，这确认了 verify-api-key 功能已生效。如需了解传递密钥的其他方式，请参阅使用有效的 API 密钥提交请求。

后续步骤

• API 代理 YAML 配置参考文档
• 使用 YAML 配置代理
• 部署 API 代理
• 发布概览