本文列出 Merchant API 適用的配額。
Merchant API 設有配額,確保所有使用者都能享有穩定公平的環境。配額可防止任何單一 API 使用者對系統造成過度負載,確保高效能。瞭解這些配額十分重要,能助你有效管理產品資料,以及在 Google 上擴展業務。
基本概念
Merchant API 配額是透過配額群組管理。
API 方法會對應至配額群組。這項對應的結構可能有所不同:
- 每組單一方法:部分配額群組適用於單一 API 方法。舉例來說,列出資料來源的方法
accounts.dataSources.list有專屬的配額群組。 - 每個群組有多個方法 (組合):相關方法通常會組合成單一配額群組。該群組中的所有方法共用相同的每日和每分鐘限制。常見例子包括:
- 將相關方法和資源的所有讀取作業分組,例如
merchant-accounts-read-methods。 - 將相關方法和資源的所有寫入作業分組,例如
merchant-accounts-write-methods。
- 將相關方法和資源的所有讀取作業分組,例如
無論類型為何,每次方法呼叫都計為一次。包含 250 個項目的 list 要求只會計為一次,而非 250 個 get 要求。
內建的 HTTP 批次處理不會影響配額。批次要求中的每個單一要求都會計入配額。舉例來說,如果批次要求包含 500 個 insert 要求,系統會視為 500 個個別 insert 方法要求來計費。
專用區域批次作業例外狀況:無論酬載包含多少區域作業,專用區域批次方法 (batchCreate、batchUpdate、batchDelete) 都會計為 merchant_regions 配額群組的單一 API 呼叫。
如要有效管理整合,請查看與您要使用的每個 API 方法相關聯的特定配額群組。您可以在配額清單方法中找到這些詳細資料。詳情請參閱「監控和可視度」。
更新政策
Merchant API 會強制執行下列更新政策:
- 根據預設,你每天最多可以更新產品兩次。您應將呼叫平均分配到一整天,以符合每分鐘配額。
- 根據預設,您每天最多只能更新子帳戶兩次。每日子帳戶更新配額是根據允許的子帳戶總數計算而得。
- 根據預設,每個子帳戶每天最多只能呼叫兩次子帳戶的資料來源方法,例如
list或create。
頻率配額
每個配額群組都有兩種限制 (和每日用量):
- 每日上限 (
quotaLimit):每天允許的要求數量上限。每日配額限制會在世界標準時間中午 12:00 重設。 - 每分鐘限制 (
quotaMinuteLimit):每分鐘允許的要求數量上限,用於控制要求速率。每分鐘配額限制採用滾動週期,違規處置期從該方法和資源的第一個 API 呼叫開始。舉例來說,如果您在上午 10:01:30 呼叫,該方法的每分鐘配額時間範圍會持續到上午 10:02:30。 - 每日用量 (
quotaUsage):當天已提出的要求數量,會計入每日上限。如果缺少這個欄位,表示這個群組尚未耗用任何配額。
您可以在 quotas.list 方法的回應中找到先前所述的三個欄位 (quotaLimit、quotaMinuteLimit 和 quotaUsage)。
不同配額群組的每日和每分鐘限制有很大的差異。預期用量較高或系統成本較低的作業 (例如讀取產品資料),通常限制較高。相反地,較密集或敏感的操作 (例如修改帳戶) 可能會有較低的限制。
配額分配和階層
本節說明 Merchant API 會追蹤及套用哪些實體的配額用量:
一般來說,系統會根據提出 API 要求的使用者收取配額。
- 獨立帳戶:如果獨立帳戶驗證 API 呼叫,該要求會計入該帳戶的配額。
- 範例:商家鞋店 A (帳戶 ID:12345) 使用自己的服務帳戶進行驗證,呼叫
products.insert,指定自己的帳戶 (accounts/12345)。配額會從鞋店 A 的配額集區中扣除。
- 範例:商家鞋店 A (帳戶 ID:12345) 使用自己的服務帳戶進行驗證,呼叫
- 進階帳戶:以進階帳戶身分驗證時,即使目標是子帳戶,也會消耗進階帳戶集區的配額。
- 範例:代理商零售管理帳戶 (進階帳戶 ID:12345) 管理子帳戶服飾店 B (帳戶 ID:11111)。代理商使用自己的憑證進行驗證,並呼叫
products.insert,指定服飾店 B (accounts/11111)。配額會從上層代理商的集區 (進階帳戶 ID:12345) 扣除,而非子帳戶的集區。
- 範例:代理商零售管理帳戶 (進階帳戶 ID:12345) 管理子帳戶服飾店 B (帳戶 ID:11111)。代理商使用自己的憑證進行驗證,並呼叫
- 子帳戶:使用子帳戶憑證驗證 API 呼叫時,配額會從該子帳戶的個別集區扣除。雖然由上層進階帳戶管理,但運作方式與獨立帳戶相同。
- 範例:沿用先前的設定,如果服飾店 B (帳戶 ID:11111) 使用專為子帳戶設定的憑證進行驗證,呼叫
products.insert並指定自己的帳戶 (accounts/11111),則配額會從服飾店 B 的個別配額集區中扣除,上層代理商的集區則不受影響。
- 範例:沿用先前的設定,如果服飾店 B (帳戶 ID:11111) 使用專為子帳戶設定的憑證進行驗證,呼叫
一般規則的例外狀況
配額分配一般規則有幾項特定例外狀況:
- Accounts.list:這個方法的配額會向發出呼叫的已驗證使用者或服務帳戶收取,而非 Merchant Center 帳戶 ID。配額用量不會顯示在標準 Merchant Center API 診斷頁面。如果您有進階帳戶,建議使用
accounts.listSubaccounts方法,這會計入進階帳戶配額。 - 問題解決方法:即使是由其他帳戶驗證要求,這些方法一律會計入要求問題的帳戶配額。
分配階層
購物比較服務 (CSS):CSS 網站會匯集產品優惠,並將使用者導向零售商網站進行購買。發出 API 呼叫時,配額會套用至您驗證的特定 CSS 群組、CSS 網域、帳戶或子帳戶。
範例:
- 名為 Europe Shopping Group 的 CSS 群組 (帳戶 ID:10001) 想要列出相關聯的 CSS 網域。透過使用自己的憑證進行驗證來發出這個 API 呼叫,配額會直接從歐洲購物群組配額集區中扣除。
- CSS 網域 TopDeals CSS (帳戶 ID:20002) 進行驗證,呼叫指定其相關聯商家帳戶 (
accounts/30003) 的方法,指派標籤。配額會從 TopDeals CSS 的配額集區中扣除,而非商家帳戶的集區。
市集:市集是代管多個個別商家的線上平台。這類帳戶是特殊的進階帳戶,可讓你為每位賣家建立個別子帳戶。
下圖顯示 CSS 群組、CSS、市集、進階帳戶、獨立帳戶和子帳戶的階層。

自動調整配額
Merchant API 設有特定服務的自動配額管理系統,會根據你的用量、商品和帳戶規模,調整成長中商家的配額限制。Merchant API 每天會重新計算這些配額。
自動調整配額的配額群組包括:
產品服務
- 與
products和productInputs資源相關的方法,其所有配額群組。 - 每日呼叫配額通常設為商家商品數量配額的 2 倍。假設商家每天最多需要更新每項產品兩次。
- 個別產品的更新次數可以超過兩次,但每日 API 呼叫總數不得超過每日呼叫配額總量。
帳戶服務
- Merchant API 中與各種精細帳戶相關資源相關的方法,其所有配額群組。
- 每日呼叫配額會設為該帳戶允許的子帳戶數量上限。每個子帳戶每天最多可執行兩次讀取呼叫。
資料來源服務
- 進階帳戶對子帳戶執行的 Merchant API 中,與資料來源相關資源相關的方法的所有配額群組,例如
list或create。 - 每日呼叫配額通常設為進階帳戶子帳戶數量的 2 倍。假設商家每天最多可更新每個子帳戶的資料來源兩次。
只有上述服務會自動調整配額。其他服務則有預設配額,如需提高配額,必須手動提出要求。詳情請參閱「配額提高程序」一節。
超出配額時的影響
超過配額後,API 回應和 Merchant Center 帳戶的診斷頁面會顯示錯誤訊息:
- 每分鐘:
quota/request_rate_too_high
{
"error": {
"code": 429,
"message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "quotaExceeded",
"domain": "merchantapi.googleapis.com",
"metadata": {
"HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
"REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
}
}
]
}
}
- 每天:
quota/daily_limit_exceeded
{
"error": {
"code": 429,
"message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "quotaExceeded",
"domain": "merchantapi.googleapis.com",
"metadata": {
"HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
"REASON": "QUOTA_TOO_MANY_REQUESTS"
}
}
]
}
}
下列錯誤是 Merchant Center 限制,與 Merchant API 配額無關。你可以嘗試申請增加商品、動態饋給或子帳戶的配額:
too_many_items:超出商家配額too_many_subaccounts:已達子帳戶數量上限
監控與觀測
如要查看帳戶目前的呼叫配額和用量,請使用帳戶名稱呼叫 quotas.list。
POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}
更改下列內容:
ACCOUNT_ID:Merchant Center IDACCESS_TOKEN:發出 API 呼叫的授權權杖
要求成功後,API 會傳回 quotaGroups 資源清單,其中包含配額群組的資源 name、不同配額,以及群組配額適用的方法。
{
"quotaGroups": [
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
"quotaUsage": "2",
"quotaLimit": "1000",
"methodDetails": [
{
"method": "quotaservice.listquotagroups",
"version": "v1",
"subapi": "quota",
"path": "quota/v1/quotaservice.listquotagroups"
}
],
"quotaMinuteLimit": "10"
},
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
"quotaLimit": "10000",
"methodDetails": [
{
"method": "commissiongroupservice.listcommissiongroups",
"version": "v1",
"subapi": "youtube",
"path": "youtube/v1/commissiongroupservice.listcommissiongroups"
}
],
"quotaMinuteLimit": "60"
},
{
"name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
"quotaLimit": "20000000",
"methodDetails": [
{
"method": "merchantreviewsservice.listmerchantreviews",
"version": "v1",
"subapi": "reviews",
"path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
}
],
"quotaMinuteLimit": "60000"
}
]
}
配額提高程序
如要申請增加配額,請開啟聯絡支援團隊表單,在必填的「問題/疑問」欄位選取「申請提高配額」,並填寫所有必填欄位,包括 Merchant Center ID、目標方法和業務理由。
- 對於具有自動配額的資源 (
products、accounts和進階帳戶的datasources):您只能在特殊情況下要求暫時提高配額,例如在新的市場推出產品或高流量購物季。我們不接受永久提高這類資源的配額。 - 對於所有其他沒有自動配額的資源:視需要要求提高配額。
建議您定期檢查配額,確保配額足以因應導入作業,並查看配額如何自動調整。使用 quotas.list 方法,查看各 API 方法群組目前的每日配額限制、每分鐘限制和每日用量。
最佳做法
實施這些最佳做法,有助於確保整合順利進行、避免發生非預期的配額錯誤,並有效率地運用 Merchant Center 資源。
最佳化要求分配
- 平均分配要求:避免在短時間內傳送大量要求。請將每日 API 呼叫平均分配到一整天,以免超過每分鐘配額限制 (
quotaMinuteLimit)。 - 主動調節:在應用程式中實作用戶端頻率限制 (調節)。請勿只依賴 Google 伺服器拒絕過多流量。從來源控管要求比率。
妥善處理錯誤
- 處理 HTTP 429:應用程式必須準備好處理 429 要求過多錯誤 (
quota/request_rate_too_high)。 - 使用指數輪詢和隨機延遲:重試失敗的要求時 (尤其是 429 錯誤後),請使用指數輪詢 (增加等待時間),並加入「隨機延遲」。抖動可防止「重試風暴」,即多個用戶端執行個體在完全相同的時間重試,再次導致伺服器超載。
- 遵循重試提示:如果 API 回應包含重試詳細資料或標頭,請根據這些資訊判斷何時恢復呼叫。
盡量減少重複呼叫
- 避免過時呼叫 (404 NOT_FOUND):避免要求或刪除已不存在的資源。即使呼叫失敗,也會耗用 API 配額。在 Merchant Center API 診斷中監控
NOT_FOUND錯誤,偵測過時的狀態追蹤或不必要的輪詢。 - 更新前先驗證:傳送更新要求前,請先確認資料是否確實有變更。避免傳送寫入相同值的更新。
- 使用快取:視情況在本機快取讀取回應 (例如產品詳細資料、設定),避免重複呼叫
get或list擷取未變更的資料。
瀏覽配額階層和例外狀況
- 進階帳戶和子帳戶:如果您是進階帳戶,請在進階帳戶層級進行驗證,這樣呼叫次數就會計入進階帳戶共用集區。
- 使用
listSubaccounts:如果是進階帳戶,請使用accounts.listSubaccounts,而非accounts.list。accounts.list配額會向呼叫使用者 (而非商家中心 ID) 收取,且不會顯示在標準診斷中。listSubaccounts會計入 MCA 配額。