本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
您可以在 YAML 中定义 Apigee API 代理,并使用 Google Cloud CLI 进行部署,作为编写传统 XML 代理包的替代方案。您可以在名为 Apigee 功能模板的 YAML 文件中描述代理的端点、路由、政策和后端目标,Apigee 会为您将这些内容编译为标准 API 代理包。
由于结果是普通的 Apigee API 代理软件包,因此您通过这种方式构建的代理在同一 Apigee 运行时上运行,其政策和行为与您在 Apigee 界面中或通过 XML 软件包构建的代理相同。
为何使用 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:
- 编译。CLI 会读取您的模板及其引用的功能文件,将它们合并,并生成单个代理定义。
- 转化。CLI 会将代理定义转换为标准 Apigee API 代理软件包(Apigee 预期的 XML 文件的 ZIP 文件)。
- 导入。CLI 会将软件包上传到 Apigee,后者会创建一个新的 API 代理修订版本。
导入代理并不会使其生效。作为单独的步骤,您需要将修订版本部署到环境中,就像对任何其他 API 代理一样:
YAML template + feature files | gcloud 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 代理。
最小示例
以下模板定义了一个具有一个端点和一个后端目标的代理,并通过组合一个功能 spike-arrest.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: - ./features/spike-arrest.yaml endpoints: - name: default basePath: /hello routes: - name: default target: default targets: - name: default url: https://mocktarget.apigee.net
features 中的每个条目都是本地特征文件的路径,相对于包含模板的目录。在此示例中,特征文件位于模板旁边的 features 子目录中。如需查看完整演示(包括 spike-arrest.yaml 功能文件),请参阅通过 YAML 模板创建 API 代理。
您可以采取的措施
- 在 YAML 中定义代理的端点、基本路径、路由、流和后端目标。
- 将可重复使用的政策和资源打包为功能,并在模板中进行组合。
- 为 Google Cloud 目标添加后端身份验证(例如,为 Gemini Enterprise Agent Platform 后端添加 Google 访问令牌)。
- 使用 Google Cloud CLI 将模板导入为新的 API 代理修订版本,然后使用标准部署命令进行部署。
限制
在编写模板和功能时,请注意以下几点:
- 特征是本地文件。模板通过相对于包含该模板的目录的路径来引用每个特征。不支持通过网址或从共享目录引用特征。
- 参数值在模板中设置。功能参数从模板的
parameters列表中获取其值,如果模板未设置值,则从功能的default中获取其值。CLI 会将没有值的参数替换为空字符串,并且不会报告错误。没有命令行标志可在导入时设置参数值;如需更改值,请修改模板并重新导入。 - 不支持 JSONPath 参数。使用
paths(JSONPath) 表达式的参数会导致编译失败。 - 不支持测试。架构接受
tests部分,但会将其忽略,并且不会将其包含在生成的软件包中。 - 架构是严格的。未知字段会导致错误。仅支持
gateway: apigee和schemaVersion: 1.0.0。 - 问题排查会使用生成的 XML。Apigee 界面和运行时可与生成的软件包搭配使用。界面中没有返回到 YAML 来源的往返。