根据 YAML 模板创建 API 代理

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

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 网关还需要 Intermediate 或 Comprehensive 环境（而不是 Base 环境）；请参阅 Apigee 环境类型。
• 确保您拥有所需的权限：
  • 如需导入（创建）API 代理：API 管理员 角色 （roles/apigee.apiAdmin），或授予 apigee.proxies.create 的等效角色。
  • 如需部署 API 代理：Environment Admin (roles/apigee.environmentAdmin) 目标环境中的，以及项目级层的 API Reader (roles/apigee.apiReaderV2)。
  • 如需创建在第 2 部分第 6 步中生成 API 密钥的 API 产品、开发者和应用：API 管理员 (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 以路由到 Gemini 模型，并使用 Google 访问令牌进行身份验证：

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 权限（例如，通过 Service Account User 角色）。如需查看所需权限的完整列表，请参阅 服务帐号简介。

第 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 错误。
• 您必须部署到 Intermediate 或 Comprehensive 环境。 此代理使用可扩展政策，Base 环境不支持该政策；部署到该环境会失败并显示错误 Extensible proxy can not be deployed to a base environment。请参阅 Apigee 环境类型。

注意 ：gcloud apigee apis deploy 命令不接受服务帐号，因此请使用 Apigee 界面或 Deployment 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."

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

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 代理
• 发布 概览