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。

接下來將概述特定服務和要求類型的其他限制和注意事項。

搜尋要求

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 個要求：

  • KeywordPlanIdeaService.GenerateAdGroupTheme

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

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

轉換上傳服務

• 每次請求僅限 2,000 次來電或點擊轉換：

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  系統會拒絕違反這些限制的要求，並傳回錯誤：TOO_MANY_CONVERSIONS_IN_REQUEST。

轉換調整項上傳服務

• 每項要求最多只能包含 2,000 個轉換調整項：

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  違反這些限制的要求會遭到拒絕，並顯示以下錯誤：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 錯誤。

其他類型的限制

如果重複欄位 (例如作業清單) 在要求中含有太多項目，可能會導致發生 REQUEST_SIZE_LIMIT_EXCEEDED 錯誤。出現這則錯誤訊息也可能是其他問題造成。

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

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