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 錯誤。

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