通过

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

后续步骤

有关使用策略的详细信息，请参阅：