用于验证 GraphQL 请求并授权的 API 管理策略(预览版)
本文提供了新 API 管理策略的参考,用于验证对导入到 API 管理的 GraphQL API 的请求并授权。
有关添加和配置策略的详细信息,请参阅 API 管理中的策略。
验证策略
策略 | 描述 |
---|---|
验证 GraphQL 请求 | 验证对 GraphQL API 的请求并授权。 |
验证 GraphQL 请求
validate-graphql-request
策略验证 GraphQL 请求并授权访问特定查询路径。 无效查询为“请求错误”。 仅对有效的请求进行授权。
权限
因为 GraphQL 查询使用平展架构:
- 权限可以应用在输出类型的任何叶节点上:
- 变更、查询或订阅
- 类型声明中的单个字段。
- 权限可能不适用于:
- 输入类型
- Fragments
- Unions
- 接口
- 架构元素
授权元素
可以使用多个授权元素。 最具体的路径用于为查询中的每个叶节点选择适当的授权规则。
- 每个授权都可以选择提供不同的操作。
if
子句允许管理员指定条件操作。
自检系统
path=/__*
的策略是自检系统。 可用于拒绝自检请求(__schema
、__type
等)。
策略语句
<validate-graphql-request error-variable-name="variable name" max-size="size in bytes" max-depth="query depth">
<authorize-path="query path, for example: /Query/list Users or /__*" action="allow|remove|reject" />
<if condition="policy expression" action="allow|remove|reject" />
</validate-graphql-request>
示例
在下面的示例中,我们验证 GraphQL 查询并拒绝:
- 大于 100 kb 或查询深度大于 4 的请求。
- 访问自检系统和
list Users
查询。
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4">
<authorize path="/" action="allow" />
<authorize path="/__*" action="reject" />
<authorize path="/Query/list Users" action="reject" />
</validate-graphql-request>
元素
名称 | 说明 | 必须 |
---|---|---|
validate-graphql-request |
根元素。 | 是 |
authorize |
添加一个或多个此类元素,以提供具有请求级和字段级错误的字段级授权。 | 是 |
if |
添加一个或多个此类元素,以对字段级授权的操作进行条件更改。 | 否 |
属性
姓名 | 说明 | 需要 | 默认 |
---|---|---|---|
error-variable-name |
context.Variables 中的要将验证错误记录到的变量的名称。 |
否 | 空值 |
max-size |
请求有效负载的最大大小(以字节为单位)。 最大允许值:102,400 字节 (100 KB)。 (如果需要增加此限制,请联系支持。) | 是 | 空值 |
max-depth |
一个整数。 最大查询深度。 | 否 | 6 |
path |
要对其执行授权验证的查询路径。 | 是 | 空值 |
action |
要为匹配字段执行的操作。 如果指定了匹配条件,则可能会更改。 | 是 | 空值 |
condition |
确定策略表达式是否匹配的布尔值。 使用第一个匹配条件。 | 否 | 空值 |
请求操作
下表描述了可用的操作。
操作 | 说明 |
---|---|
reject |
发生请求错误,请求不会发送到后端。 |
remove |
发生字段错误,并从请求中删除该字段。 |
allow |
该字段将传递到后端。 |
使用情况
策略节: 入站
策略范围: 所有范围
错误处理。
针对 GraphQL 架构的验证失败,或者请求的大小或深度失败,都是请求错误,导致请求失败,并出现错误块(但没有数据块)。
与 Context.LastError
属性类似,所有 GraphQL 验证错误都会在 GraphQLErrors
变量中自动传播。 如果需要单独传播错误,则可以指定错误变量名称。 将错误推送到 error
变量和 GraphQLErrors
变量。
后续步骤
有关使用策略的详细信息,请参阅:
- API 管理中的策略
- 转换 API
- 策略参考,其中提供了策略语句及其设置的完整列表
- 策略示例
- 错误处理