配額

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

一般規則的例外狀況

配額分配一般規則有幾項例外狀況：

  • Accounts.list： 這個方法的配額會向發出呼叫的已驗證使用者或服務帳戶收費，而非 Merchant Center 帳戶 ID。 標準Merchant Center API 診斷頁面不會顯示配額用量。如果您有進階帳戶，建議使用 accounts.listSubaccounts 方法，這會計入進階帳戶配額。
  • 問題解決方法： 即使是由其他帳戶驗證要求，這些方法一律會計入要求解決問題的帳戶配額。

分配階層

  • 購物比較服務 (CSS)：CSS 網站會彙整產品，並將使用者導向零售商網站進行購買。進行 API 呼叫時，系統會根據您驗證的特定 CSS 群組、CSS 網域、帳戶或子帳戶套用配額。

    範例：

    • 名為「歐洲購物群組」 (帳戶 ID：10001) 的 CSS 群組想要列出相關聯的 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配額會向呼叫使用者收費 (而非 MC ID)，且不會顯示在標準診斷中。listSubaccounts會計入 MCA 配額。
上一頁
Overview
下一頁
Merchant Center limits