配額

本文列出 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 的配額集區中扣除。
  • 進階帳戶:以進階帳戶身分驗證時,即使目標是子帳戶,也會消耗進階帳戶集區的配額。
    • 範例:代理商零售管理帳戶 (進階帳戶 ID:12345) 管理子帳戶服飾店 B (帳戶 ID:11111)。代理商使用自己的憑證進行驗證,並呼叫 products.insert,指定服飾店 B (accounts/11111)。配額會從上層代理商的集區 (進階帳戶 ID:12345) 扣除,而非子帳戶的集區。
  • 子帳戶:使用子帳戶憑證驗證 API 呼叫時,配額會從該子帳戶的個別集區扣除。雖然由上層進階帳戶管理,但運作方式與獨立帳戶相同。
    • 範例:沿用先前的設定,如果服飾店 B (帳戶 ID:11111) 使用專為子帳戶設定的憑證進行驗證,呼叫 products.insert 並指定自己的帳戶 (accounts/11111),則配額會從服飾店 B 的個別配額集區中扣除,上層代理商的集區則不受影響。

一般規則的例外狀況

配額分配一般規則有幾項特定例外狀況:

分配階層

  • 購物比較服務 (CSS):CSS 網站會匯集產品優惠,並將使用者導向零售商網站進行購買。發出 API 呼叫時,配額會套用至您驗證的特定 CSS 群組、CSS 網域、帳戶或子帳戶。

    範例:

    • 名為 Europe Shopping Group 的 CSS 群組 (帳戶 ID:10001) 想要列出相關聯的 CSS 網域。透過使用自己的憑證進行驗證來發出這個 API 呼叫,配額會直接從歐洲購物群組配額集區中扣除。
    • CSS 網域 TopDeals CSS (帳戶 ID:20002) 進行驗證,呼叫指定其相關聯商家帳戶 (accounts/30003) 的方法,指派標籤。配額會從 TopDeals CSS 的配額集區中扣除,而非商家帳戶的集區。
  • 市集:市集是代管多個個別商家的線上平台。這類帳戶是特殊的進階帳戶,可讓你為每位賣家建立個別子帳戶。

下圖顯示 CSS 群組、CSS、市集、進階帳戶、獨立帳戶和子帳戶的階層。

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 ID
  • ACCESS_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 配額。