用于验证 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 变量。

后续步骤

有关使用策略的详细信息,请参阅: