Skip to main content

請求的計算方式

每個執行的根操作欄位算作一次 API 呼叫。 要求四個根欄位的 GraphQL 請求會以四次 API 呼叫計費,就如同你發出了四個 REST 請求。根層級的別名會分開計算,因為每個別名都會分派一個操作。從型別化回應中選取的巢狀欄位不會增加 API 呼叫次數。
一個 HTTP 請求,會在你方案的配額與速率限制中計入四次 API 呼叫。 這是刻意的設計,也是誠實的計費模式:每個根欄位在我們這端所做的工作都與對應的 REST 呼叫相同,因此成本也相同。GraphQL 能幫你減少往返次數,讓你在同一處精確取得所需的資料;但它並不是取得超出方案所含 API 呼叫次數的方法。 實際影響如下:
  • 你現有的方案限制維持不變。你方案的額度請參閱 API 限制。
  • 要求一個你不需要的根操作,成本與透過 REST 呼叫它相同。選取你需要的巢狀回應欄位則不會增加呼叫次數。
  • 請求可能會在執行途中受到速率限制。已完成的根欄位會保留其資料,只有被節流的根欄位會傳回錯誤,請參閱部分成功。

查詢限制

此端點會對查詢的結構與大小施加一些限制。這些限制的目的是避免單一請求耗用我們不合理的容量,而且設定得遠高於一般使用所需。如果你碰到其中一項限制,通常代表查詢是意外產生的,而非真正的需求。 被拒絕的查詢,若你傳送 Accept: application/graphql-response+json 會傳回 HTTP 400,否則傳回 HTTP 200;兩種情況下都會包含 errors 陣列,且沒有 data。請參閱錯誤。

每次請求的 API 呼叫次數

這是最重要的一項。單一請求最多只能觸發 5 次 API 呼叫,因此上面四個根欄位的範例沒問題,但二十個根欄位的查詢就不行。一旦已開始五次分派,其他根欄位會傳回說明此限制的 429;已分派的欄位仍可傳回其資料。 如果你需要更多,請將查詢拆分到多個請求中。如果你發現正當的工作負載經常需要這麼做,請與我們聯絡。此限制在推出時刻意設得保守,要提高它很簡單,但日後若要調降則會破壞既有整合,因此一開始先設得較小。

深度、欄位與別名

這些限制會在任何東西執行之前檢查,因此超出其中一項完全不會消耗 API 呼叫。 這些限制也寬裕地容納完整的 introspection 查詢(約 180 個欄位、12 層深度,且沒有別名),因此在啟動時擷取整個 schema 的用戶端也能正常運作。

請求 body 大小

64 KB,對查詢來說相當充裕,但對檔案來說則遠遠不足。這就是無法透過 GraphQL 上傳媒體的原因,支援的做法請參閱上傳媒體。

逾時

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

不受限制的項目

  • 讀取 schema。 Introspection 不需驗證,也不計量。瀏覽有哪些功能是免費的;執行操作則不是。
  • 格式錯誤的查詢。 被 GraphQL 拒絕的查詢(未知的欄位、錯誤的型別、無效的列舉值)永遠不會抵達我們的 API,也永遠不會計費。
這些限制會依據實際使用情況進行檢討。如果其中某項限制不適合正當的整合,請告訴我們,這樣的回饋比變通做法更有幫助。