API 限制和配額

Google Ads API 會對 API 作業設下限制,例如單一變動要求中可傳送的作業數量。下表摘要列出一些重要限制和配額,請務必留意。

要求類型、限制和錯誤代碼
基本存取層級的作業 每日 15,000 次 API 作業 RESOURCE_EXHAUSTED
修改要求 每項要求 10,000 次作業 TOO_MANY_MUTATE_OPERATIONS
規劃服務要求 1 QPS RESOURCE_EXHAUSTED
轉換上傳服務要求 每個要求 2,000 次轉換 TOO_MANY_CONVERSIONS_IN_REQUEST
帳單和帳戶預算服務要求 每個修改要求 1 項作業 TOO_MANY_MUTATE_OPERATIONS

每日 API 作業限制

每日 API 用量限制是根據每個開發人員權杖執行的 API 作業次數而定。API 作業是取得要求和變動作業的總和。每日 API 作業的限制取決於開發人員權杖的存取層級。「存取層級和允許用途指南」列出各存取層級的具體 API 作業限制。

如果要求違反這些限制,系統會拒絕要求並傳回以下錯誤: RESOURCE_EXHAUSTED

gRPC 限制

所有 Google Ads API 用戶端程式庫都使用 gRPC 生成要求和回應。根據預設,gRPC 的訊息大小為 4 MB,但我們的用戶端程式庫會將訊息大小上限設為 64 MB,以提高效率。

回覆內容不得超過此限制。舉例來說,如果搜尋要求包含大量欄位,產生的回應大小可能會超過 64 MB。如要避免超過這個上限,可以減少選取的欄位數量,或是使用串流。如果是變動,請減少每個要求中的作業數量。

違反這項限制的要求「不會」產生 GoogleAdsError,但會產生 429 Resource Exhausted gRPC 錯誤。請參閱 gRPC 錯誤代碼和訊息清單

修改要求

除了會計入使用者的每日作業配額外,每個變動要求最多只能包含 10,000 個作業。

如果要求違反這項限制,系統會拒絕要求並傳回以下錯誤: TOO_MANY_MUTATE_OPERATIONS

下文將說明特定服務和要求類型的其他限制和注意事項。

搜尋要求

SearchSearchStream 要求會計為一項作業,並計入使用者的每日作業配額。無論批次數量為何,一項 SearchStream 要求都會計為一項 API 作業。

分頁要求

分頁要求 (例如包含有效 next_page_token 的要求) 不會計入使用者的每日作業配額。不過,如果分頁要求包含過期或無效的頁面符記,系統會產生例外狀況,並計入每日作業配額。

如要進一步瞭解分頁,請參閱「瀏覽結果」。

其他類型的要求

如果要求不是 GetMutateSearchSearchStream 要求,則會計為一項作業,並計入使用者的每日作業配額。

這類要求包括:

傳回 API 例外的要求

遭拒的要求 (GoogleAdsFailure) 仍會計入使用者的每日作業配額。

如果要求失敗但未傳回 GoogleAdsFailure,例如網路層級發生錯誤,由於要求永遠不會送達服務,因此不會計入使用者的每日作業配額。例如網路連線失敗。

關鍵字規劃服務

由於成本和複雜度考量,下列關鍵字規劃服務方法會受到與其他類型要求不同的限制。

建立關鍵字企劃書時,請留意這些限制。

關鍵字企劃書物件 最大數量
每個帳戶 KeywordPlan 10,000
KeywordPlan KeywordPlanAdGroup 200
KeywordPlan KeywordPlanAdGroupKeyword 10,000
KeywordPlanCampaignKeyword (排除關鍵字) 1,000
KeywordPlan KeywordPlanCampaign 1

目標對象洞察服務

AudienceInsightsService 方法中的下列方法有特定配額限制。

轉換上傳服務

轉換調整項上傳服務

帳單和帳戶預算服務

  • 只有設定為月結的帳戶才能進行變動。

    如果要求違反這項限制,系統會拒絕要求並傳回以下錯誤: MUTATE_NOT_ALLOWED

  • 變動要求只能執行 1 項作業。

    如果要求違反這項限制,系統會拒絕要求並傳回以下錯誤: TOO_MANY_MUTATE_OPERATIONS

  • 變更同一帳戶的預算訂單時,請至少間隔 12 小時。如果變更時間未滿 12 小時,可能會導致無法復原的錯誤,只能由 Google Ads 帳戶代表解決。

客戶帳戶邀請

您可以透過CustomerUserAccessService邀請新使用者加入現有客戶帳戶。由於這項功能會傳送邀請電子郵件給其他使用者,因此可能遭到濫用,因此有以下行為限制:

使用者資料

使用者資料是透過 UserDataServiceOfflineUserDataJobService 管理。在指定的建立或移除 UserData 作業中,每組 user_identifiers 應專屬於單一使用者。

如要強制執行這項規定,如果 UserData 集中的 user_identifiers 超過 20 個,系統就會傳回 OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERSUserDataError.TOO_MANY_USER_IDENTIFIERS 錯誤。

無論作業數量為何,您最多可上傳 100,000 個使用者 ID。

其他限制類型

如果要求中的重複欄位 (例如作業清單) 項目過多,可能會導致錯誤: REQUEST_SIZE_LIMIT_EXCEEDED。 其他問題也可能導致顯示相同的錯誤訊息。

如果遇到這項限制,且您發出的要求使用重複欄位,請嘗試在變動要求中部署作業清單,減少重複欄位中的項目數量。

進行 GAQL 查詢時,IN 子句中的項目數量上限為 20,000 個。如果超過這項限制,系統會傳回 FILTER_HAS_TOO_MANY_VALUES 錯誤。