本页面适用于 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 |
要组合到代理中的功能文件名称列表。每个名称都必须解析为与模板位于同一目录中的文件。 | [] |
否 |
parameters |
提供特征默认值的形参值列表。 | [] |
否 |
endpoints |
定义基本路径和路由的端点列表。 | [] |
否 |
targets |
定义后端连接的目标列表。 | [] |
否 |
文档类型：功能
功能是可重复使用的配置单元，您可以将其纳入模板中。 功能包含政策和资源，并且可以向已编译的代理贡献流、端点和目标。除了常见的顶级字段之外，功能还包含以下字段。
| 名称 | 说明 | 默认值 | 是否必需？ |
|---|---|---|---|
displayName |
人类可读的显示名称。 | 不适用 | 否 |
uid |
用于为功能政策和资源设置命名空间的唯一标识符。如果未设置，则使用 name。 |
不适用 | 否 |
documentation |
扩展了该功能的文档。 | 不适用 | 否 |
categories |
自由格式的类别标签列表。 | [] |
否 |
parameters |
功能定义的形参列表。 | [] |
否 |
defaultEndpoint |
一个代理端点，其流和默认故障规则会合并到已编译代理的每个端点中。使用此元素将功能的政策附加到请求或响应流。 | 不适用 | 否 |
defaultTarget |
用作默认后端连接的代理目标。 | 不适用 | 否 |
endpoints |
要添加到代理的代理端点列表。如果端点与现有端点同名，则会替换现有端点。 | [] |
否 |
targets |
要添加到代理的代理目标列表。如果新目标与现有目标同名，则会替换现有目标。 | [] |
否 |
policies |
相应功能提供的政策列表。在编译期间，政策名称会自动添加功能的 uid（或 name）作为前缀。 |
[] |
否 |
resources |
功能提供的资源列表，例如 JavaScript 或属性文件。 | [] |
否 |
证件类型：委托书
代理是 CLI 在编译具有相应功能的模板时生成的完全解析的文档。您通常不会直接创作此类内容；此处之所以介绍它，是因为它会成为 API 代理软件包的形状。
代理与功能具有相同的字段，但它使用 endpoints 和 targets（而非 defaultEndpoint 或 defaultTarget），并且始终表示完整的可部署代理。其 type 为 proxy。
嵌套对象
参数
形参用于向功能提供值。参数的值解析为其 default。
| 名称 | 说明 | 默认值 | 是否必需？ |
|---|---|---|---|
name |
参数名称。在功能内容中引用为 {name}。 |
不适用 | 是 |
displayName |
简单易懂的名称。 | 不适用 | 否 |
description |
参数说明。 | 不适用 | 否 |
default |
默认值。替换了功能字符串中的 {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
使用一个额外的字段扩展了 flow。
从 flow 继承的 mode 字段不适用于故障规则。由于故障规则在请求失败后运行，因此它没有请求或响应阶段；其步骤始终直接运行。如果您在故障规则中设置了 mode，该工具会记录一条警告并忽略该字段。
| 名称 | 说明 | 默认值 | 是否必需？ |
|---|---|---|---|
alwaysEnforce |
如果值为 true，则始终强制执行默认故障规则。 |
false |
否 |
目标
用于模板的 targets 列表中。
| 名称 | 说明 | 默认值 | 是否必需？ |
|---|---|---|---|
name |
目标名称。由路由的 target 引用。 |
不适用 | 是 |
url |
后端网址。 | 不适用 | 否 |
auth |
Google Cloud 后端的身份验证方案，例如 GoogleAccessToken 或 GoogleIDToken。 |
不适用 | 否 |
scopes |
要请求的 OAuth 范围列表。当设置了 auth 时适用。 |
[] |
否 |
aud |
令牌的受众群体。当设置了 auth 时适用。 |
不适用 | 否 |
proxyTarget
用于功能的 defaultTarget 和 targets 中，以及编译后的代理中。通过流程处理和原始连接替换来扩展目标。
| 名称 | 说明 | 默认值 | 是否必需？ |
|---|---|---|---|
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（或 name）为前缀。 |
不适用 | 是 |
type |
资源类型，用于确定 bundle 中的子目录，例如 jsc (JavaScript) 或 properties。 |
不适用 | 是 |
content |
原始文件内容。 | 不适用 | 否 |
此版本不支持的字段
paths针对参数 (JSONPath)。使用它会导致编译失败。tests。系统会接受该字段，但会忽略它，并且不会将其包含在生成的软件包中。
限制
生成的 API 代理软件包在未压缩时不得超过 10 MiB，或者不得超过 256 个文件。