> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL 限制与计费

> Ayrshare 如何将 GraphQL 请求计入你的 API 配额，以及查询深度、字段、别名和请求大小的限制。

<h2 id="how-requests-are-counted">
  请求的计数方式
</h2>

**每个执行的根操作字段计为一次 API 调用。** 请求四个根字段的 GraphQL 请求按四次 API 调用计费，与你发出四个 REST 请求完全相同。根级别的别名会分别计数，因为每个别名都会分派一个操作。从类型化响应中选择的嵌套字段不会增加 API 调用次数。

```graphql theme={"system"}
{
  history: postHistory(lastDays: 7)
  accounts: user
  comments: comments(id: "abc123")
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}
```

一个 HTTP 请求，计入你计划配额和速率限制的是**四次 API 调用**。

这是有意为之，也是公平的模式：每个根字段在我们这边所做的工作与等效的 REST 调用相同，因此成本也相同。GraphQL 可以为你节省往返次数，让你在一个地方准确获取所需内容；但它并不是获得超出计划所含 API 调用次数的途径。

实际影响如下：

<ul class="custom-bullets">
  <li>你现有的计划限制保持不变。请参见 <a href="/docs/apis/overview">API 限制</a>了解你计划的额度。</li>
  <li>请求一个你并不需要的根操作，其成本与通过 REST 调用它相同。选择你需要的嵌套响应字段不会增加调用次数。</li>
  <li>请求可能会在<em>执行过程中</em>受到速率限制。已完成的根字段会保留其数据，只有被限流的根字段会返回错误，请参见<a href="/docs/apis/graphql/errors#partial-success">部分成功</a>。</li>
</ul>

<h2 id="query-limits">
  查询限制
</h2>

该端点对查询的结构和大小实施了一些限制。这些限制的存在是为了防止单个请求消耗过多的系统容量，其设定值远高于日常使用所需：如果你触及了某个限制，通常说明是意外生成了某个查询，而非真实需求。

| 限制 | 值 | 如何得知 |
| - | - | - |
| 每个请求的 API 调用次数 | 5 | 每个超出的根字段返回 `extensions.status` 429 |
| 查询嵌套深度 | 15 | 查询在运行前被拒绝 |
| 每个请求的字段数 | 300 | 查询在运行前被拒绝 |
| 每个请求的别名数 | 25 | 查询在运行前被拒绝 |
| 请求体大小 | 64 KB | HTTP 413 |

如果你发送了 `Accept: application/graphql-response+json`，被拒绝的查询会返回 HTTP 400，否则返回 HTTP 200；两种情况下都会带有 `errors` 数组且没有 `data`。请参见[错误](/docs/apis/graphql/errors)。

<h3 id="api-calls-per-request">
  每个请求的 API 调用次数
</h3>

这是最重要的一项限制。单个请求最多可触发 **5** 次 API 调用，因此上面包含四个根字段的示例没有问题，但包含二十个根字段的请求则不行。一旦已启动五次分派，额外的根字段会返回说明该限制的 429；已分派的字段仍可返回其数据。

如果你需要更多调用，请将查询拆分到多个请求中。如果你在合理的工作负载下经常需要这样做，请[联系我们](/docs/help-center/overview)：该限制在发布初期有意设置得较为保守，提高它很容易，而日后降低它则会破坏现有集成，因此先从较小的值开始。

<h3 id="depth-fields-and-aliases">
  深度、字段和别名
</h3>

这些限制会在任何操作运行之前进行检查，因此超出其中任何一项都不会消耗任何 API 调用。

它们也远高于完整内省查询的需求（完整内省查询约有 180 个字段、12 层深度，且不含别名），因此在启动时获取整个 schema 的客户端可以正常工作。

<h3 id="request-body-size">
  请求体大小
</h3>

64 KB，这对于查询来说绰绰有余，但对于文件来说则太小了。这就是媒体无法通过 GraphQL 上传的原因，受支持的方式请参见[上传媒体](/docs/apis/graphql/using-the-api#uploading-media)。

<h2 id="timeouts">
  超时
</h2>

每个请求总共最多有 120 秒的处理时间。**查询中的根字段可能并发运行**，因此其耗时通常取决于最慢的依赖项。**变更中的根字段按顺序运行**，因此多个耗时较长的变更可能会累积并接近超时。无论哪种形式，都仍可能对后端施加最多五次并发或顺序分派的负载；在适当的情况下，请拆分已知耗时较长的工作。

<h2 id="what-is-not-limited">
  不受限制的内容
</h2>

<ul class="custom-bullets">
  <li><strong>读取 schema。</strong>内省无需身份验证，也不计量。浏览有哪些功能是免费的，但运行操作不是。</li>
  <li><strong>格式错误的查询。</strong>被 GraphQL 拒绝的查询（未知字段、类型错误、无效的枚举值）永远不会到达我们的 API，也永远不会计费。</li>
</ul>

我们会根据实际使用情况审查这些限制。如果其中某项限制不适合某个合理的集成，请告诉我们：这样的反馈比变通方法更有价值。