DOCS
Rate•
首頁為物流供應商提供的解決方案 GraphQL API 速率限制

GraphQL API 速率限制

瞭解 Zonos 如何根據複雜性計算查詢成本。

Zonos 根據查詢複雜性而不是請求數量來限制 GraphQL API 請求。這確保了公平的使用，同時允許您請求所需的確切資料。

為什麼採用基於複雜性的速率限制？ 

傳統 REST API 使用基於請求的速率限制，其中每個請求消耗相同的積分，無論您是獲取一個欄位還是數百個欄位，以及您是讀取還是修改資料 —— 儘管伺服器負載存在很大差異。

GraphQL 的查詢複雜性方法通過根據實際請求的資料和執行的操作計算成本來解決此問題。這為您提供了更大的靈活性來請求您需要的內容，同時提供可預測的伺服器負載。

速率限制 

Zonos 使用基於點數的系統，其中每個查詢根據其複雜性扣除點數。您有一個可用點數池，其中包括：

  • 以 3,000 點/秒的速率補充（30,000 點/10 秒）
  • 最大容量為 300,000 點

這使您可以偶爾進行複雜查詢的突發，同時保持可持續的請求速度。

如何計算查詢成本 

每個 GraphQL 請求都有在執行前計算的成本：

基本成本

  • Query: 5 點
  • Mutation: 10 點
  • Object: 每個返回的物件 1 點
  • Scalar fields: 0 點（免費）

字串、整數、ID 和布林值等純量欄位不增加成本。您只需為基本操作和返回的物件付費。

示例：簡單查詢

1query {
2 landedCost(id: "123") {
3 id
4 createdBy
5 shipToCountry
6 }
7}

成本明細： 5（基本查詢）+ 1（Landed cost 物件）= 6 點

純量欄位（id、name、currency）是免費的。

示例：有多個物件的查詢

1{
2 orders(first: 10, filter: { status: COMPLETED }) {
3 edges {
4 cursor
5 node {
6 id
7 }
8 }
9 }
10}

成本明細： 5（基本查詢）+ 10（10 個訂單 × 每個 1 點）= 15 點

示例：Mutation

1mutation {
2 landedCostCalculate(input: { ... }) {
3 id
4 }
5}

成本明細： 10（基本 mutation）+ 約 50（返回的物件）= 60 點

典型的 Landed cost 計算的複雜性成本約為 60 點。

檢視查詢複雜性 

每個 API 回應都包含一個 zonos-query-complexity 標題，顯示您的查詢成本：

1zonos-query-complexity: 58

此標題告訴您查詢消耗了多少點數。使用它來監控您的 API 使用情況並最佳化昂貴的查詢。

處理速率限制 

如果您超出速率限制，您將收到錯誤訊息。為了有效處理速率限制：

監控您的複雜性

檢查回應中的 zonos-query-complexity 標題，以瞭解查詢成本並識別昂貴的模式。

實施重試邏輯

如果達到速率限制，請實施指數退避和重試邏輯。由於水桶以 3,000 點/秒的速率補充，請根據您的查詢複雜性計算適當的等待時間。

有效批處理

GraphQL 允許您在單個請求中請求多個查詢：

1{
2 landedCost(id: "landed_cost_123") {
3 id
4 createdAt
5 }
6 order(orderId: "order_123") {
7 id
8 status
9 createdAt
10 }
11}

最佳實踐 

只請求您需要的內容

查詢複雜性與您請求的資料成正比。構造查詢以僅獲取您實際使用的欄位和物件。

1query {
2 order(orderId: "order_123") {
3 id
4 status
5 createdAt
6 updatedAt
7 items {
8 id
9 name
10 quantity
11 amount
12 }
13 shipments {
14 id
15 }
16 }
17}

對大型資料集進行分頁

當請求多個物件時，請使用合理的頁面大小：

1{
2 orders(first: 100, filter: { status: COMPLETED }) {
3 edges {
4 cursor
5 node {
6 id
7 }
8 }
9 }
10}

一次請求 10-50 個項目並根據需要遍歷結果，而不是在單個查詢中請求數百個物件。

避免不必要的嵌套

每個嵌套物件都會增加您的複雜性。只有在您真正需要時才請求嵌套資料。

這個頁面有幫助嗎？

獲取支持·法律文件·© 2026 Zonos
在此頁面：
  • GraphQL API 速率限制