GitHub 文档 - GraphQL API 的速率限制和节点限制

节点限制

为了通过模式验证，所有 GraphQL API 调用必须符合以下标准

客户端必须在任何连接上提供 first 或 last 参数。
first 和 last 的值必须在 1-100 之间。
单个调用不能请求超过 500,000 个总节点。

计算调用中的节点

以下两个示例展示了如何计算调用中的总节点数。

简单查询

query {
  viewer {
    repositories(first: 50) {
      edges {
        repository:node {
          name

          issues(first: 10) {
            totalCount
            edges {
              node {
                title
                bodyHTML
              }
            }
          }
        }
      }
    }
  }
}

计算

50         = 50 repositories
 +
50 x 10  = 500 repository issues

            = 550 total nodes

复杂查询

query {
  viewer {
    repositories(first: 50) {
      edges {
        repository:node {
          name

          pullRequests(first: 20) {
            edges {
              pullRequest:node {
                title

                comments(first: 10) {
                  edges {
                    comment:node {
                      bodyHTML
                    }
                  }
                }
              }
            }
          }

          issues(first: 20) {
            totalCount
            edges {
              issue:node {
                title
                bodyHTML

                comments(first: 10) {
                  edges {
                    comment:node {
                      bodyHTML
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

    followers(first: 10) {
      edges {
        follower:node {
          login
        }
      }
    }
  }
}

计算

50              = 50 repositories
 +
50 x 20       = 1,000 pullRequests
 +
50 x 20 x 10 = 10,000 pullRequest comments
 +
50 x 20       = 1,000 issues
 +
50 x 20 x 10 = 10,000 issue comments
 +
10              = 10 followers

                 = 22,060 total nodes

主要速率限制

GraphQL API 为每个查询分配点数，并限制您在特定时间内可以使用点数。此限制有助于防止滥用和拒绝服务攻击，并确保 API 对所有用户可用。

REST API 也有单独的主要速率限制。有关更多信息，请参阅“REST API 的速率限制”。

通常，您可以根据您的身份验证方法计算 GraphQL API 的主要速率限制

对于用户：每小时每用户 5,000 点。这包括使用个人访问令牌发出的请求，以及 GitHub App 或 OAuth App 代表授权该 App 的用户发出的请求。GitHub Enterprise Cloud 组织拥有的 GitHub App 代表用户发出的请求具有更高的速率限制，为每小时 10,000 点。类似地，如果您是 GitHub Enterprise Cloud 组织的成员，则由 GitHub Enterprise Cloud 组织拥有或批准的 OAuth App 代表您发出的请求具有更高的速率限制，为每小时 10,000 点。
对于未安装在 GitHub Enterprise Cloud 组织上的 GitHub App 安装：每个安装每小时 5,000 点。拥有超过 20 个仓库的安装，每个仓库每小时额外获得 50 点。安装在拥有超过 20 个用户的组织上的安装，每个用户每小时额外获得 50 点。速率限制不能超过每小时 12,500 点。用户访问令牌（与安装访问令牌相对）的速率限制由用户的首要速率限制决定。
对于安装在 GitHub Enterprise Cloud 组织上的 GitHub App 安装：每个安装每小时 10,000 点。用户访问令牌（与安装访问令牌相对）的速率限制由用户的首要速率限制决定。
对于 OAuth 应用：每小时 5,000 点，如果应用由 GitHub Enterprise Cloud 组织拥有，则为每小时 10,000 点。这仅适用于应用使用其客户端 ID 和客户端密钥请求公共数据时。由 OAuth 应用生成的 OAuth 访问令牌的速率限制由用户的首要速率限制决定。
对于 GitHub Actions 工作流中的 GITHUB_TOKEN：每个仓库每小时 1,000 点。对于对属于 GitHub.com 上企业帐户的资源的请求，限制为每个仓库每小时 15,000 点。

您可以按照以下部分的说明检查查询的点数或计算预期的点数。计算点数的公式和速率限制可能会发生变化。

检查您的首要速率限制状态

您可以使用每个响应中发送的标头来确定您的首要速率限制的当前状态。

标头名称	描述
`x-ratelimit-limit`	您每小时可以使用点数的最大值
`x-ratelimit-remaining`	当前速率限制窗口中剩余的点数
`x-ratelimit-used`	您在当前速率限制窗口中使用的点数
`x-ratelimit-reset`	当前速率限制窗口重置的时间，以 UTC 纪元秒为单位
`x-ratelimit-resource`	请求计入的速率限制资源。对于 GraphQL 请求，这将始终为 `graphql`。

您还可以查询 rateLimit 对象以检查您的速率限制。在可能的情况下，您应该使用速率限制响应标头而不是查询 API 来检查您的速率限制。

query {
  viewer {
    login
  }
  rateLimit {
    limit
    remaining
    used
    resetAt
  }
}

字段	描述
`限制`	您每小时可以使用点数的最大值
`剩余`	当前速率限制窗口中剩余的点数
`已使用`	您在当前速率限制窗口中使用的点数
`重置时间`	当前速率限制窗口重置的时间，以 UTC 纪元秒为单位

返回查询的点数

可以通过查询 rateLimit 对象上的 cost 字段来返回查询的点数

query {
  viewer {
    login
  }
  rateLimit {
    cost
  }
}

预测查询的点数

您也可以在进行查询之前粗略地计算查询的点数。

将满足每个唯一连接所需的请求数量加起来。假设每个请求都将达到 first 或 last 参数限制。
将该数字除以 100 并将结果四舍五入到最接近的整数，以获得最终的聚合点数。此步骤将对大数字进行标准化。

注意：对 GraphQL API 的调用的最小点数为 1。

以下是一个示例查询和分数计算

query {
  viewer {
    login
    repositories(first: 100) {
      edges {
        node {
          id

          issues(first: 50) {
            edges {
              node {
                id

                labels(first: 60) {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

此查询需要 5,101 个请求才能完成

虽然我们返回了 100 个仓库，但 API 必须连接到查看者的帐户一次以获取仓库列表。因此，仓库请求 = 1
虽然我们返回了 50 个问题，但 API 必须连接到每个 100 个仓库以获取问题列表。因此，问题请求 = 100
虽然我们返回了 60 个标签，但 API 必须连接到每个 5,000 个潜在的总问题以获取标签列表。因此，标签请求 = 5,000
总计 = 5,101

除以 100 并四舍五入得到查询的最终分数：51

请求	点数
没有突变的 GraphQL 请求	1
带有突变的 GraphQL 请求	5
大多数 REST API 的 `GET`、`HEAD` 和 `OPTIONS` 请求	1
大多数 REST API 的 `POST`、`PATCH`、`PUT` 或 `DELETE` 请求	5

超过速率限制

如果您超过了主速率限制，响应状态仍然是 200，但您会收到错误消息，并且 x-ratelimit-remaining 标头的值为 0。您应该在 x-ratelimit-reset 标头指定的时间之后重试您的请求。

如果您超过了次级速率限制，响应状态将是 200 或 403，并且您会收到一条错误消息，表明您遇到了次级速率限制。如果 retry-after 响应标头存在，您应该在经过那么多秒后重试您的请求。如果 x-ratelimit-remaining 标头为 0，您应该在 x-ratelimit-reset 标头指定的 UTC 时间戳（以秒为单位）之后重试您的请求。否则，请等待至少一分钟后再重试。如果您的请求继续因次级速率限制而失败，请在重试之间等待指数增长的时长，并在特定次数的重试后抛出错误。

在您受到速率限制时继续发出请求可能会导致您的集成被禁止。

保持在速率限制内

为了避免超过速率限制，您应该在每次修改请求之间至少暂停 1 秒，并避免并发请求。

您还应该订阅 webhook 事件，而不是轮询 API 获取数据。有关更多信息，请参阅“Webhook 文档”。

GraphQL API 的速率限制和节点限制

本文档