使用 YAML 配置代理

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

您可以采用 YAML 定义 Apigee API 代理，并使用 Google Cloud CLI 部署该代理，而无需编写传统的 XML 代理软件包。您可以在名为 Apigee 功能模板的 YAML 文件中描述代理的端点、路由、政策和后端目标，然后 Apigee 会将这些文件编译为标准的 API 代理软件包。

由于结果是普通的 Apigee API 代理软件包，因此以这种方式构建的代理与在 Apigee 界面中或从 XML 软件包构建的代理一样，在相同的 Apigee 运行时上运行，并具有相同的政策和行为。

为何要使用 YAML 定义代理

传统的 Apigee API 代理格式是 XML 文件的 ZIP 归档。YAML 提供了一种替代方案，许多开发者认为这种方案更易于阅读、编写和审核，并且非常适合 AI 辅助工具和代理工具。Apigee 功能模板旨在实现以下目标：

  • 偏好简洁的声明性格式并希望将代理配置保留在源代码控制中的 API 开发者和架构师。
  • 希望以标准化方式在模型后端前面放置 Apigee 网关的 AI 从业者。
  • 希望打包可重复使用的代理配置并将其一致地应用于多个代理的平台和 DevOps 团队。

主要概念

Apigee 功能模板使用三种文档类型。每个文件都是一个 YAML 文件，通过其 type 字段进行标识。

文档类型 type 值 用途
模板 template 您部署的入口点。模板包含一个或多个功能，并定义代理的端点和路由。
功能 feature 一种可重复使用的配置单元（例如身份验证检查、速率限制或后端目标），可包含在模板中。功能包含政策和资源。
代理 proxy CLI 在编译包含其功能的模板时生成的完全解析的代理。虽然代理文件通常是 CLI 生成的中间输出，但您也可以直接导入代理文件，将其转换为 API 代理软件包。

您负责创作模板和功能。在编译期间，Apigee 会为您生成 代理。

工作原理

导入模板时，Google Cloud CLI 会在本地执行以下步骤，然后将结果上传到 Apigee：

  1. 编译。CLI 会读取您的模板及其引用的功能文件，将它们合并，然后生成单个代理定义。
  2. 转换。该 CLI 会将代理定义转换为标准的 Apigee API 代理软件包（Apigee 所需的 XML 文件 ZIP）。
  3. 导入。CLI 会将该软件包上传到 Apigee，后者会创建一个新的 API 代理修订版本。

导入代理并不会使其生效。作为单独的步骤，您可以将修订版本部署到环境中，就像部署任何其他 API 代理一样：

YAML template + feature files
  |  gcloud beta apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)

如需查看分步说明，请参阅通过 YAML 模板创建 API 代理。

最小示例

以下模板定义了一个代理，该代理包含两个功能：一个用于添加后端目标，另一个用于添加响应消息：

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

每个被引用的功能文件都必须与模板位于同一目录中。 如需查看完整的可运行示例及其使用的功能文件，请参阅从 YAML 模板创建 API 代理。

您可以采取的措施

  • 在 YAML 中定义代理的端点、基本路径、路由、流和后端目标。
  • 将可重用的政策和资源打包为功能，并在模板中进行组合。
  • 为 Google Cloud 目标添加后端身份验证（例如，Vertex AI 后端的 Google 访问令牌）。
  • 使用 Google Cloud CLI 将模板作为新的 API 代理修订版本导入，然后使用标准部署命令进行部署。

限制

在创作模板和功能时，请注意以下几点：

  • 功能是本地文件。模板只能引用同一目录中的功能文件。不支持通过网址或从共享目录引用功能。
  • 参数值使用其默认值。功能可以定义参数，但参数值会解析为功能中定义的默认值。没有可在导入时替换参数值的命令行标志。
  • 不支持 JSONPath 参数。使用 paths (JSONPath) 表达式的形参会导致编译失败。
  • 不支持测试。架构接受 tests 部分，但会忽略该部分，并且不会将其包含在生成的软件包中。
  • 架构严格。未知字段会导致错误。仅支持 gateway: apigee 和 schemaVersion: 1.0.0。
  • 问题排查使用生成的 XML。Apigee 界面和运行时与生成的软件包协同工作。在界面中，无法返回到 YAML 来源。

后续步骤