跳到主要内容

参数​

有关所有插件均可使用的配置项，请参阅插件通用配置。

  • count

    integer | string

    有效值：

    大于 0

    给定时间间隔内允许累计的最大 GraphQL 查询成本。默认策略下，查询成本即为深度。未配置 rules 时必填。当配置为字符串时，该值可以使用内置变量。

  • time_window

    integer | string

    有效值：

    大于 0

    与限流 count 对应的时间间隔，单位为秒。未配置 rules 时必填。当配置为字符串时，该值可以使用内置变量。

  • rules

    array[object]

    按顺序应用的限流规则数组。rules 与顶层 count 和 time_window 二选一配置，不能同时使用。

    • count

      integer | string

      必填

      有效值：

      大于 0

      规则的 time_window 内允许累计的最大 GraphQL 查询成本。默认策略下，查询成本即为深度。当配置为字符串时，该值可以使用内置变量。

    • time_window

      integer | string

      必填

      有效值：

      大于 0

      与规则 count 对应的时间间隔，单位为秒。当配置为字符串时，该值可以使用内置变量。

    • key

      string

      必填

      用于计数请求的 Key。支持内置变量组合，每个变量必须以美元符号（$）为前缀。如果 Key 无法解析，则不会应用该规则。

    • header_prefix

      string

      插入到该规则限流响应头中的前缀。例如，foo 会生成 X-foo-RateLimit-Limit、X-foo-RateLimit-Remaining 和 X-foo-RateLimit-Reset。

  • cost_strategy

    string

    默认值：depth

    有效值：

    depth、complexity 或 node_quantifier

    计算 GraphQL 文档原始成本的方式。depth 按选择集的嵌套深度计算，也就是该插件一直以来的行为。complexity 对查询解析的节点计分。node_quantifier 只对匹配的成本装饰能解析出 mul_arguments 所列参数的节点计分。如果没有节点同时具备匹配装饰和可用量词，文档的原始分数为 0。对于 complexity 和 node_quantifier，插件先加 0.01、应用 score_factor，再向上取整后计入配额。默认系数会把原始分数 0 变为计费成本 1；大于 100 的系数会进一步提高该成本。该能力在 API7 企业版 3.10.6 中引入。

  • max_cost

    number

    默认值：0

    有效值：

    大于或等于 0

    计费成本超过该值的文档在到达上游之前即以 403 Forbidden 拒绝。请求会先消耗配额，再执行该检查。设为 0 表示关闭该检查，仅由配额决定。该能力在 API7 企业版 3.10.6 中引入。

  • score_factor

    number

    默认值：1

    有效值：

    大于 0

    在成本向上取整、计入配额并与 max_cost 比较之前应用的缩放系数。该能力在 API7 企业版 3.10.6 中引入。

  • resolve_variables

    boolean

    默认值：true

    如果为 true，则在计算成本时解析已提供的 GraphQL 变量、操作声明的变量默认值，以及上游 schema 中的参数默认值。默认开启可确保以变量提供的量词计入其解析值。该能力在 API7 企业版 3.10.6 中引入。

  • introspection_endpoint

    string

    有效值：

    以 http:// 或 https:// 开头

    用于内省上游 GraphQL schema 的端点，complexity 与 node_quantifier 策略需要它来匹配成本装饰。未设置时从上游推导。结果按 Worker 和服务缓存。该能力在 API7 企业版 3.10.6 中引入。

  • introspection_headers

    object

    发起 schema 内省请求时携带的请求头，适用于内省端点需要凭据的上游。这些请求头取自配置而不是请求，因为内省得到的 schema 按 Worker 和服务缓存。启用数据面数据加密时，该字段会加密落盘。该能力在 API7 企业版 3.10.6 中引入。

  • key_type

    string

    默认值：var

    有效值：

    var、var_combination 或 constant

    键的类型。

    如果 key_type 为 var，则 key 被解释为变量。

    如果 key_type 为 var_combination，则 key 被解释为变量组合。

    如果 key_type 为 constant，则 key 被解释为常量。

  • key

    string

    默认值：remote_addr

    用于计数请求的键。

    如果 key_type 为 var，则 key 被解释为变量。变量不需要以美元符号（$）作为前缀。查看内置变量以获取可用变量。

    如果 key_type 为 var_combination，则 key 被解释为变量组合。所有变量都应以美元符号（$）作为前缀。例如，要将 key 配置为使用两个请求头 custom-a 和 custom-b 的组合，key 应配置为 $http_custom_a $http_custom_b。

    如果 key_type 为 constant，则 key 被解释为常量值。

  • rejected_code

    integer

    默认值：503

    有效值：

    介于 200 和 599 之间（含边界值）

    当请求因超过阈值而被拒绝时返回的 HTTP 状态码。

  • rejected_msg

    string

    有效值：

    任意非空字符串

    当请求因超过阈值而被拒绝时返回的响应体。

  • policy

    string

    默认值：local

    有效值：

    local、redis 或 redis-cluster

    速率限制计数器的策略。如果为 local，则计数器存储在本地内存中。如果为 redis，则计数器存储在 Redis 实例中。如果为 redis-cluster，则计数器存储在 Redis 集群中。

  • allow_degradation

    boolean

    默认值：false

    如果为 true，则在插件或其依赖项不可用时，允许网关继续处理请求而不使用该插件。

  • show_limit_quota_header

    boolean

    默认值：true

    如果为 true，则包含以下速率限制响应头：

    • X-RateLimit-Limit 显示总配额。
    • X-RateLimit-Remaining 显示剩余配额。
    • X-RateLimit-Reset 显示计数器重置前的剩余秒数。

  • group

    string

    有效值：

    非空

    插件的 group ID，同一 group 的路由可以共享相同的速率限制计数器。

  • redis_host

    string

    Redis 节点的地址。当 policy 为 redis 时必填。

  • redis_port

    integer

    默认值：6379

    有效值：

    大于或等于 1

    Redis 节点的端口。当 policy 为 redis 时使用。

  • redis_username

    string

    如果使用 Redis ACL，则为 Redis 的用户名。如果你使用传统的认证方法 requirepass，则只需配置 redis_password。当 policy 为 redis 时使用。

  • redis_password

    string

    Redis 节点的密码。当 policy 为 redis 或 redis-cluster 时使用。

  • redis_database

    integer

    默认值：0

    有效值：

    大于或等于 0

    Redis 中的数据库编号。当 policy 为 redis 时使用。

  • redis_ssl

    boolean

    默认值：false

    如果为 true，则在 policy 为 redis 时使用 SSL 连接到 Redis。

  • redis_ssl_verify

    boolean

    默认值：false

    如果为 true，则在 policy 为 redis 时验证服务器 SSL 证书。

  • redis_timeout

    integer

    默认值：1000

    有效值：

    大于或等于 1

    Redis 超时时间（毫秒）。当 policy 为 redis 或 redis-cluster 时使用。

  • redis_keepalive_timeout

    integer

    默认值：10000

    有效值：

    大于或等于 1000

    当 policy 为 redis 或 redis-cluster 时，Redis 的保活超时时间，单位为毫秒。

    此参数在 API7 企业版 3.9.x 系列中自 3.9.16 起可用，在 3.10.x 系列中自 3.10.3 起可用，并且在 APISIX 中自 3.17.0 起可用。

  • redis_keepalive_pool

    integer

    默认值：100

    有效值：

    大于或等于 1

    当 policy 为 redis 或 redis-cluster 时，Redis 的保活连接池大小。

    此参数在 API7 企业版 3.9.x 系列中自 3.9.16 起可用，在 3.10.x 系列中自 3.10.3 起可用，并且在 APISIX 中自 3.17.0 起可用。

  • redis_cluster_nodes

    array[string]

    Redis 集群节点列表，至少包含两个地址。当 policy 为 redis-cluster 时必填。

  • redis_cluster_name

    string

    Redis 集群的名称。当 policy 为 redis-cluster 时必填。

  • redis_cluster_ssl

    boolean

    默认值：false

    如果为 true，则在 policy 为 redis-cluster 时使用 SSL 连接到 Redis 集群。

  • redis_cluster_ssl_verify

    boolean

    默认值：false

    如果为 true，则在 policy 为 redis-cluster 时验证服务器 SSL 证书。

插件元数据​

  • limit_header

    string

    默认值：X-RateLimit-Limit

    表示速率限制总配额的默认响应头名称。在 API7 企业版中自 3.10.6 起可用。

  • remaining_header

    string

    默认值：X-RateLimit-Remaining

    表示速率限制剩余配额的默认响应头名称。在 API7 企业版中自 3.10.6 起可用。

  • reset_header

    string

    默认值：X-RateLimit-Reset

    表示速率限制计数器重置前剩余秒数的默认响应头名称。在 API7 企业版中自 3.10.6 起可用。