API 限制和配額

Google Ads API 會限制 API 作業，例如單一變更要求中可傳送的作業數量。下表摘要說明幾項須留意的限制和配額。

要求類型、限制和錯誤代碼
測試存取層級作業 每天可對測試帳戶執行 15,000 項 API 作業 RESOURCE_EXHAUSTED
具備探索者存取層級的作業 每天可對正式環境帳戶執行 2,880 項 API 作業
每天可對測試帳戶執行 15,000 項 API 作業 		RESOURCE_EXHAUSTED
基本存取層級作業 每天可對測試和正式環境帳戶執行 15,000 項 API 作業 RESOURCE_EXHAUSTED
標準存取層級作業 每天可對測試和正式環境帳戶執行的 API 作業數量不受限制 不適用
變更要求 每項要求 10,000 次變更作業 TOO_MANY_MUTATE_OPERATIONS
規劃服務要求 1 QPS RESOURCE_EXHAUSTED
轉換上傳服務要求 每項要求 2,000 次轉換 TOO_MANY_CONVERSIONS_IN_REQUEST
帳單和帳戶預算服務要求 每項變更要求 1 項作業 TOO_MANY_MUTATE_OPERATIONS

每日 API 作業限制

每日 API 用量限制取決於 Google Cloud 專案執行的 API 作業數量。API 作業是 Search 和 SearchStream 要求、個別異動作業和其他服務要求的總和。每日 API 作業數量上限取決於 Google Cloud 雲端專案的 API 存取層級。存取層級和允許使用指南概述了各存取層級的特定 API 作業限制。

違反這些限制的要求會遭到拒絕，並傳回錯誤：RESOURCE_EXHAUSTED。

gRPC 限制

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

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

違反這項限制的要求不會產生 GoogleAdsError，而是會產生 RESOURCE_EXHAUSTED (gRPC 代碼 8/HTTP 429) 錯誤。請參閱 gRPC 錯誤代碼和訊息清單。

變更要求

除了計入使用者的每日作業配額外，每個變更要求最多只能包含 10,000 項變更作業。如果要求違反這項限制，系統會拒絕並傳回錯誤：TOO_MANY_MUTATE_OPERATIONS。

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

搜尋要求

Search 或 SearchStream 要求會計為使用者每日作業配額中的一項作業。無論批次數量為何，一項 SearchStream 要求都計為一項 API 作業。

分頁要求

分頁要求 (例如包含有效 next_page_token 的要求) 不會計入使用者的每日作業配額。不過，如果分頁要求包含過期或無效的分頁權杖，就會產生例外狀況，並計入每日作業配額。

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

其他類型的要求

如果要求不是 Mutate、Search 或 SearchStream 要求，則會計為一項作業，計入使用者的每日作業配額。

這類要求包括：

傳回 API 例外狀況的要求

即使要求因 GoogleAdsFailure 而遭拒，仍會計入使用者的每日作業配額。

如果要求失敗，但未傳回 GoogleAdsFailure (例如網路層級發生錯誤)，則不會計入使用者的每日作業配額，因為要求不會傳送至服務。例如網路連線失敗。

關鍵字規劃工具服務

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

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

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

目標對象洞察服務

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

轉換上傳服務

轉換調整項上傳服務

轉換價值規則

如果帳戶已有 attachment_type 為 CUSTOMER 的 ConversionValueRuleSet，您必須將新的轉換價值規則加入該組合，規則才會生效。如果沒有這類轉換價值規則集，請務必建立一個，並按照「建立規則集」一節所述，將轉換價值規則加入其中。

帳單和帳戶預算服務

  • 只能對已設定月結的帳戶進行異動。

    如果要求違反這項限制，系統會拒絕並傳回錯誤：MUTATE_NOT_ALLOWED。

  • 變更要求只能包含 1 項作業。

    如果要求違反這項限制，系統會拒絕並傳回錯誤：TOO_MANY_MUTATE_OPERATIONS。

  • 對同一個帳戶進行帳戶預算 (AccountBudget 或 AccountBudgetProposal) 變更時，兩次變更之間應至少間隔 12 小時。如果在 12 小時內進行變更，可能會導致無法復原的錯誤，只能由 Google Ads 帳戶代表解決。

客戶帳戶邀請

您可以使用 CustomerUserAccessInvitationService 邀請新使用者加入現有客戶帳戶。由於這項功能會傳送邀請電子郵件給其他使用者，因此可能遭到濫用，行為也受到限制：

使用者資料

使用者資料是透過 UserDataService 和 OfflineUserDataJobService 管理。

create 或 remove 作業中的每個 UserData 物件都屬於單一使用者。單一 UserData 物件中的 user_identifiers 欄位最多只能有 20 個 ID。如果單一 UserData 物件超過這項限制，會導致 OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS 或 UserDataError.TOO_MANY_USER_IDENTIFIERS 錯誤。

處理 ID 超過 20 個的使用者

如果單一使用者有超過 20 個 ID 需要上傳，請將這些 ID 分配到多個 UserData 物件。為確保 Google 能將所有 ID 與同一位使用者建立關聯，該使用者的每個 UserData 物件都必須包含至少一個共同的 user_identifier，例如相同的 hashed_email、hashed_phone_number 或 third_party_user_id。Google 會使用這些共用 ID，將不同 UserData 作業的資訊連結並合併至正確的使用者設定檔。

如果您仰賴雜湊電子郵件或電話號碼等 PII，請務必按照 Google Ads API 規定 (SHA-256、小寫、不含空格) 進行正規化和雜湊處理，以免連結失敗。

舉例來說，如果使用者有 30 個電子郵件地址，您可以傳送兩個共用 third_party_user_id 的 UserData 物件 (將 thirdPartyUserId 和電子郵件 1 到 19 放入第一個物件，以符合 20 個 ID 的限制，並將 thirdPartyUserId 和電子郵件 20 到 30 放入第二個物件)：

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

在單一 AddOfflineUserDataJobOperationsRequest 中，所有作業的 user_identifiers 總上限為 100,000 (OfflineUserDataJob 可接受多個 AddOfflineUserDataJobOperationsRequest 呼叫，每項工作最多建議 1,000,000 項作業)。使用 UploadUserDataRequest (UserDataService.UploadUserData) 進行同步上傳時，每項要求最多只能包含 10 項作業，且整個要求最多只能包含 100 個user_identifiers。

其他類型的限制

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

如果遇到這項限制，且要求使用重複欄位，請將作業清單拆分至多個變更要求，減少重複欄位中的項目數量。

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

上一頁
總覽
下一頁
系統限制