API 代理 YAML 配置参考文档

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

本页面介绍了 Apigee 功能模板的 YAML 格式:template、feature 和 proxy 文档类型及其所有字段。如需了解概念性介绍,请参阅使用 YAML 配置代理。如需查看演示,请参阅通过 YAML 模板创建 API 代理。

惯例

  • 字段名称使用 camelCase。例如,schemaVersion、basePath、displayName、faultRules、defaultFaultRule、httpTargetConnection。
  • 架构是严格的。导入文件时,未知字段会导致错误。
  • 必填字段。解析文件时,系统只会验证 gateway 和 schemaVersion。在实际操作中,下表中标记为是的其他字段也是必需的,这样才能生成有效的 API 代理。

常见顶级字段

每个 template、feature 和 proxy 文档都以以下字段开头。

名称 说明 默认值 是否必需?
gateway 目标网关。必须为 apigee。 不适用 是
schemaVersion 文档的架构版本。必须为 1.0.0。 不适用 是
name 文档的名称。对于模板或代理,这是写入软件包中的 API 代理名称。 不适用 是
type 文档类型:template、feature 或 proxy。 不适用 是
description 人类可读的说明。 不适用 否
priority 一个整数,用于控制在编译期间应用特征的顺序。数字越小,应用顺序越靠前。 100 否

文档类型:模板

模板是您导入的入口点。它会组合功能并定义代理的端点和路由。模板不包含政策或资源,这些内容来自其引用的功能。

名称 说明 默认值 是否必需?
features 要组合到代理中的功能文件列表。每个条目都是一个特征文件的路径,相对于包含模板的目录(例如 ./features/spike-arrest.yaml)。 [] 否
parameters 用于为特征参数设置值的参数列表。条目的 default 会替换具有相同 name 的特征参数的 default。请参阅参数。 [] 否
endpoints 定义基本路径和路由的端点列表。 [] 否
targets 定义后端连接的目标列表。 [] 否

文档类型:功能

功能是您在模板中包含的可重复使用的配置单元。 功能包含政策和资源,并且可以向已编译的代理提供流、端点和目标。除了常见顶级字段之外,特征还具有以下字段。

名称 说明 默认值 是否必需?
displayName 人类可读的显示名称。 不适用 否
uid 一个唯一标识符,用于在模板多次包含该功能时,将该功能的政策和资源区分开来。如果该功能设置了 uid,则 CLI 会在其每个政策和资源名称前加上 UID- 前缀,并更新对它们的引用。如果该功能未设置 uid,则 CLI 会按原样使用名称。 不适用 否
documentation 有关该功能的扩展文档。 不适用 否
categories 自由形式类别标签列表。 [] 否
parameters 该功能定义的参数列表。 [] 否
defaultEndpoint 代理端点,其流和默认故障规则会合并到已编译代理的每个端点中。使用此选项可将功能的政策附加到请求或响应流。 不适用 否
defaultTarget 用作默认后端连接的代理目标。 不适用 否
endpoints 要添加到代理的代理端点列表。与现有端点同名的端点会替换现有端点。 [] 否
targets 要添加到代理的代理目标列表。与现有目标同名的目标会替换现有目标。 [] 否
policies 该功能提供的政策列表。如果该特征集设置了 uid,则 CLI 会在编译期间为每个政策名称添加 UID- 前缀,例如 sa1-SA-SpikeArrest。否则,CLI 会按原样使用政策名称。 [] 否
resources 该功能提供的资源列表,例如 JavaScript 或属性文件。 [] 否

文件类型:代理

代理是 CLI 在编译模板及其功能时生成的完全解析的文档。您通常不会直接编写此类型;此处对其进行描述是因为它是成为 API 代理软件包的形状。

代理具有与特征相同的字段,但它使用 endpoints 和 targets(而不是 defaultEndpoint 或 defaultTarget),并且始终表示完整的可部署代理。其 type 为 proxy。

嵌套对象

参数

参数为特征提供值。功能会声明其参数,而模板可以在其自己的 parameters 列表中设置这些参数的值。当 CLI 编译模板时,它会按如下方式解析每个功能参数:

  1. 如果模板的 parameters 列表包含 name 匹配且 default 不为空的条目,则 CLI 会使用该值。如果该功能设置了 uid,则模板条目的名称必须为 FEATURE_NAME.UID.PARAMETER_NAME。
  2. 否则,CLI 会使用功能参数的 default。
  3. 如果两者均未设置值,则参数会解析为空字符串。CLI 不会报告错误。

没有用于在导入时设置参数值的命令行标志。如需更改值,请修改模板。

名称 说明 默认值 是否必需?
name 参数名称。在精选内容中引用为 {name}。 不适用 是
displayName 人类可读名称。 不适用 否
description 参数的说明。 不适用 否
default 在功能中,当模板未设置值时使用的值。在模板中,同名特征参数的值。CLI 会忽略空值。CLI 会将该功能的字符串中的 {name} 替换为解析后的值。 不适用 否
examples 示例值列表。 [] 否
maps 值替换映射。如果解析后的值是映射中的键,则会替换为映射的值。 不适用 否
paths JSONPath 表达式列表。此版本不支持 - 使用它会导致错误。 不适用 否

endpoint

在模板的 endpoints 列表中使用。

名称 说明 默认值 是否必需?
name 端点名称。 不适用 是
basePath 客户端用于调用代理的基本路径,例如 /v1/gemini。 不适用 否
routes 将请求映射到目标的路由列表。 [] 否

proxyEndpoint

在功能的 defaultEndpoint 和 endpoints 以及已编译的代理中使用。通过流处理扩展端点。

名称 说明 默认值 是否必需?
flows 流列表。名为 PreFlow 或 PostFlow 的流会映射到相应的 Apigee 流;任何其他名称都会放置在通用流容器中。 [] 否
postClientFlow 在响应发送到客户端后运行的单个流。 不适用 否
faultRules 用作故障规则的流列表。 [] 否
defaultFaultRule 在没有其他故障规则匹配时运行的故障规则。 不适用 否

路线

名称 说明 默认值 是否必需?
name 路由名称。 不适用 是
target 要路由到的目标端点的名称。 不适用 否
condition 此路由要应用,必须满足的条件。 不适用 否

工作沉浸度

名称 说明 默认值 是否必需?
name 流程名称。对标准请求/响应流使用 PreFlow 或 PostFlow。 不适用 是
mode Request 或 Response。确定步骤是在请求还是响应中运行。 Request 否
condition 工作流运行必须满足的条件。 不适用 否
steps 步骤(政策调用)的有序列表。 [] 否

步骤

步骤在流中运行政策。

名称 说明 默认值 是否必需?
name 要运行的政策的名称。在功能中,使用政策的本地名称;编译器会将其重写为命名空间名称。 不适用 是
condition 必须满足此条件,步骤才能运行。 不适用 否

faultRule

使用一个额外字段扩展流。

从流继承的 mode 字段不适用于故障规则。由于故障规则在请求失败后运行,因此它没有请求或响应阶段;其步骤始终直接运行。如果您在故障规则上设置了 mode,该工具会记录警告并忽略该字段。

名称 说明 默认值 是否必需?
alwaysEnforce 如果为 true,则始终强制执行默认故障规则。 false 否

目标

在模板的 targets 列表中使用。

名称 说明 默认值 是否必需?
name 目标名称。由路由的 target 引用。 不适用 是
url 后端网址。 不适用 否
auth Google Cloud 后端的身份验证方案,例如 GoogleAccessToken 或 GoogleIDToken。 不适用 否
scopes 要请求的 OAuth 范围列表。在设置了 auth 时适用。 [] 否
aud 令牌的受众群体。在设置了 auth 时适用。 不适用 否

proxyTarget

在功能的 defaultTarget 和 targets 以及已编译的代理中使用。通过流处理和原始连接替换来扩展 target。

名称 说明 默认值 是否必需?
flows 在目标请求或响应上运行的流列表。 [] 否
faultRules 用作故障规则的流列表。 [] 否
defaultFaultRule 故障规则。 不适用 否
httpTargetConnection HTTPTargetConnection 元素的原始表示法,用于高级配置。如果设置,则其优先级高于 url、auth、scopes 和 aud。 不适用 否
localTargetConnection LocalTargetConnection 元素的原始表示。 如果设置了此项,则其优先级高于 HTTP 连接。 不适用 否

政策

政策在功能中定义。其配置是使用政策内容惯例中所述的特性/文本惯例在 content 下编写的。

名称 说明 默认值 是否必需?
name 政策名称。 不适用 是
type Apigee 政策类型,例如 VerifyAPIKey、SpikeArrest 或 Javascript。必须与 content 中的单个顶级键匹配。 不适用 是
content 一个单键字典,其键等于 type。嵌套值使用以下惯例描述政策的 XML。 {} 是

政策内容惯例

Apigee 政策采用 XML 格式。在 YAML 中,您可以使用以下规则在 content 中表示该 XML:

  • content 字典只有一个键,该键必须与政策的 type 匹配。
  • 元素属性位于 metadata 键下。
  • 元素文本位于 _text 键下。例如,<Foo bar="baz">qux</Foo> 会变为 Foo: {metadata: {bar: "baz"}, _text: "qux"}。如果元素只有文本而没有属性,您可以直接将文本作为值写入。
  • 子元素嵌套在其标记名称下。重复的标记会变成列表。

例如,以下功能政策:

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

会编译为此政策 XML:

<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey">
  <APIKey ref="request.header.x-api-key"></APIKey>
  <DisplayName>VA-VerifyAPIKey</DisplayName>
</VerifyAPIKey>

资源

资源是指功能向软件包贡献的文件,例如 JavaScript 文件或属性文件。

名称 说明 默认值 是否必需?
name 文件名,例如 hello-world.js。如果该功能设置了 uid,则 CLI 会在编译期间为资源名称添加 UID- 前缀。否则,CLI 会使用所写的名称。 不适用 是
type 资源类型,用于确定软件包中的子目录,例如 jsc (JavaScript) 或 properties。 不适用 是
content 原始文件内容。 不适用 否

此版本不支持的字段

  • 参数上的 paths (JSONPath)。使用它会导致编译失败。
  • 对任何文档tests。该字段会被接受但会被忽略,并且不会包含在生成的 bundle 中。

限制

生成的 API 代理包不得超过 10 MiB(未压缩)或 256 个文件。

后续步骤