通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

验证 GraphQL 请求

  • 项目

适用于：所有 API 管理层级

validate-graphql-request 策略在 GraphQL API 中验证 GraphQL 请求并授权访问特定查询路径。 无效查询为“请求错误”。 仅对有效的请求进行授权。

注意

按照策略声明中提供的顺序设置策略的元素和子元素。 详细了解如何设置或编辑 API 管理策略。

策略语句

<validate-graphql-request error-variable-name="variable name" max-size="size in bytes" max-depth="query depth">
    <authorize>
        <rule path="query path, for example: '/listUsers' or '/__*'" action="string or policy expression that evaluates to 'allow | remove | reject | ignore'" />
    </authorize>
</validate-graphql-request>

属性

属性 说明 需要 默认
error-variable-name context.Variables 中的要将验证错误记录到的变量的名称。 允许使用策略表达式。 否 空值
max_size 请求有效负载的最大大小（以字节为单位）。 最大允许值：102,400 字节 (100 KB)。 （如果需要提高此限制，请联系客户支持。）允许使用策略表达式。 是 空值
max-depth 一个整数。 最大查询深度。 允许使用策略表达式。 否 6

元素

名称 说明 必需
授权 添加此元素以为一个或多个路径设置适当的授权规则。 否
规则 (rule) 添加其中一个或多个元素以授权特定的查询路径。 每个规则可以选择指定不同的操作。 可以使用策略表达式有条件地指定。 否

规则属性

属性 说明 需要 默认
path 要对其执行授权验证的路径。 它必须遵循以下模式：/type/field。 是 空值
action 规则应用时要执行的操作。 可以使用策略表达式有条件地指定。 否 allow

自检系统

path=/__* 的策略是自检系统。 可用于拒绝自检请求（__schema、__type 等）。

请求操作

下表描述了可用的操作。

操作 说明
reject 发生请求错误，请求不会发送到后端。 如果未配置，则不应用其他规则。
删除 发生字段错误，并从请求中删除该字段。
allow 该字段将传递到后端。
ignore 该规则对于这种情况无效，因此将应用下一个规则。

使用情况

使用注意事项

  • 为已导入到 API 管理的直通或综合 GraphQL API 配置策略。

  • 此策略只能在策略部分中使用一次。

  • 因为 GraphQL 查询使用平展架构，所以权限可以应用于某个输出类型的任何叶节点：

    • 变更、查询或订阅
    • 类型声明中的单个字段

    权限不能应用于：

    • 输入类型
    • Fragments
    • Unions
    • 接口
    • 架构元素

  • 该策略可以验证在所有级别上最多包含 250 个查询字段的 GraphQL 请求。

错误处理

针对 GraphQL 架构的验证失败，或者请求的大小或深度失败，都是请求错误，导致请求失败，并出现错误块（但没有数据块）。

与 Context.LastError 属性类似，所有 GraphQL 验证错误都会在 GraphQLErrors 变量中自动传播。 如果需要单独传播错误，则可以指定错误变量名称。 将错误推送到 error 变量和 GraphQLErrors 变量。

示例

查询验证

此示例将以下验证和授权规则应用于 GraphQL 查询：

  • 大于 100 kb 或查询深度大于 4 的请求将被拒绝。
  • 对内省系统的请求被拒绝。
  • /Missions/name 字段将从包含两个以上标头的请求中删除。
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/__*" action="reject" /> 
        <rule path="/Missions/name" action="@(context.Request.Headers.Count > 2 ? "remove" : "allow")" />
    </authorize>
</validate-graphql-request>

变异验证

此示例将以下验证和授权规则应用于 GraphQL 变异：

  • 大于 100 kb 或查询深度大于 4 的请求将被拒绝。
  • 除非请求来自 IP 地址 deleteUser，否则拒绝更改字段的请求 198.51.100.1。
<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/Mutation/deleteUser" action="@(context.Request.IpAddress <> "198.51.100.1" ? "deny" : "allow")" />
    </authorize>
</validate-graphql-request>

相关内容

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