> ## 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 | 查詢在執行前即被拒絕 |
| 請求 body 大小 | 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 呼叫。

這些限制也寬裕地容納完整的 introspection 查詢（約 180 個欄位、12 層深度，且沒有別名），因此在啟動時擷取整個 schema 的用戶端也能正常運作。

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

64 KB，對查詢來說相當充裕，但對檔案來說則遠遠不足。這就是無法透過 GraphQL 上傳媒體的原因，支援的做法請參閱[上傳媒體](/docs/apis/graphql/using-the-api#uploading-media)。

<h2 id="timeouts">
  逾時
</h2>

每個請求整體最多有 120 秒。**query 中的根欄位可能會並行執行**，因此其耗時通常取決於最慢的相依項目。**mutation 中的根欄位會依序執行**，因此多個緩慢的 mutation 可能會累積而接近逾時。無論哪種形式，仍可能對後端造成最多五次並行或依序分派的負載；必要時請將已知較慢的工作拆開。

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

<ul class="custom-bullets">
  <li><strong>讀取 schema。</strong> Introspection 不需驗證，也不計量。瀏覽有哪些功能是免費的；執行操作則不是。</li>
  <li><strong>格式錯誤的查詢。</strong> 被 GraphQL 拒絕的查詢（未知的欄位、錯誤的型別、無效的列舉值）永遠不會抵達我們的 API，也永遠不會計費。</li>
</ul>

這些限制會依據實際使用情況進行檢討。如果其中某項限制不適合正當的整合，請告訴我們，這樣的回饋比變通做法更有幫助。