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
。
下文將說明特定服務和要求類型的其他限制和注意事項。
搜尋要求
Search
或 SearchStream
要求會計為一項作業,並計入使用者的每日作業配額。無論批次數量為何,一項 SearchStream
要求都會計為一項 API 作業。
分頁要求
分頁要求 (例如包含有效 next_page_token
的要求) 不會計入使用者的每日作業配額。不過,如果分頁要求包含過期或無效的頁面符記,系統會產生例外狀況,並計入每日作業配額。
如要進一步瞭解分頁,請參閱「瀏覽結果」。
其他類型的要求
如果要求不是 Get
、Mutate
、Search
或 SearchStream
要求,則會計為一項作業,並計入使用者的每日作業配額。
這類要求包括:
BatchJobService.ListMutateJobResults
ConversionUploadService.UploadCallConversions
ConversionUploadService.UploadClickConversions
OfflineUserDataJobService.AddOfflineUserDataJobOperations
OfflineUserDataJobService.CreateOfflineUserDataJob
UserDataService.UploadUserData
傳回 API 例外的要求
遭拒的要求 (GoogleAdsFailure
) 仍會計入使用者的每日作業配額。
如果要求失敗但未傳回 GoogleAdsFailure
,例如網路層級發生錯誤,由於要求永遠不會送達服務,因此不會計入使用者的每日作業配額。例如網路連線失敗。
關鍵字規劃服務
由於成本和複雜度考量,下列關鍵字規劃服務方法會受到與其他類型要求不同的限制。
每個客戶 ID 每秒最多只能提出 1 個要求:
KeywordPlanIdeaService.GenerateKeywordIdeas
KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
KeywordPlanIdeaService.GenerateKeywordForecastMetrics
如果要求違反這些限制,系統會拒絕要求並傳回錯誤:
RESOURCE_EXHAUSTED
。1 QPS 的計算方式為每 60 秒 60 個要求。
每個客戶 ID 每秒最多只能提出 2 個要求:
建立關鍵字企劃書時,請留意這些限制。
關鍵字企劃書物件 | 最大數量 |
---|---|
每個帳戶 KeywordPlan |
10,000 |
每KeywordPlan KeywordPlanAdGroup |
200 |
每KeywordPlan KeywordPlanAdGroupKeyword |
10,000 |
KeywordPlanCampaignKeyword (排除關鍵字) |
1,000 |
每KeywordPlan KeywordPlanCampaign |
1 |
目標對象洞察服務
AudienceInsightsService
方法中的下列方法有特定配額限制。
每個 CID 每天最多約 200 個要求:
每個開發人員權杖每秒最多只能提出 2 個要求:
轉換上傳服務
每項要求最多只能有 2,000 次來電或點擊轉換:
如果要求違反這些限制,系統會拒絕要求並傳回以下錯誤:
TOO_MANY_CONVERSIONS_IN_REQUEST
。
轉換調整項上傳服務
每項要求最多只能有 2,000 項轉換調整:
如果要求違反這些限制,系統會拒絕要求並傳回以下錯誤:
TOO_MANY_ADJUSTMENTS_IN_REQUEST
。
帳單和帳戶預算服務
只有設定為月結的帳戶才能進行變動。
如果要求違反這項限制,系統會拒絕要求並傳回以下錯誤:
MUTATE_NOT_ALLOWED
。變動要求只能執行 1 項作業。
如果要求違反這項限制,系統會拒絕要求並傳回以下錯誤:
TOO_MANY_MUTATE_OPERATIONS
。變更同一帳戶的預算訂單時,請至少間隔 12 小時。如果變更時間未滿 12 小時,可能會導致無法復原的錯誤,只能由 Google Ads 帳戶代表解決。
客戶帳戶邀請
您可以透過CustomerUserAccessService
邀請新使用者加入現有客戶帳戶。由於這項功能會傳送邀請電子郵件給其他使用者,因此可能遭到濫用,因此有以下行為限制:
使用者無法收到同一位客戶帳戶的多個待處理邀請。如果後續要求傳送邀請給已有待處理邀請的使用者,系統會傳回以下錯誤:
ACCESS_INVITATION_ERROR_EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION
。客戶帳戶一次最多只能有 70 個待處理的邀請。 如果傳送的要求導致超過這個值,系統會傳回以下錯誤:
ACCESS_INVITATION_ERROR_PENDING_INVITATIONS_LIMIT_EXCEEDED
。
使用者資料
使用者資料是透過 UserDataService
和 OfflineUserDataJobService
管理。在指定的建立或移除 UserData
作業中,每組 user_identifiers
應專屬於單一使用者。
如要強制執行這項規定,如果 UserData
集中的 user_identifiers
超過 20 個,系統就會傳回 OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS
或 UserDataError.TOO_MANY_USER_IDENTIFIERS
錯誤。
無論作業數量為何,您最多可上傳 100,000 個使用者 ID。
其他限制類型
如果要求中的重複欄位 (例如作業清單) 項目過多,可能會導致錯誤:
REQUEST_SIZE_LIMIT_EXCEEDED
。
其他問題也可能導致顯示相同的錯誤訊息。
如果遇到這項限制,且您發出的要求使用重複欄位,請嘗試在變動要求中部署作業清單,減少重複欄位中的項目數量。
進行 GAQL 查詢時,IN
子句中的項目數量上限為 20,000 個。如果超過這項限制,系統會傳回 FILTER_HAS_TOO_MANY_VALUES
錯誤。