API 限制和配額

Google Ads API 會強制執行 API 作業的限制，例如單一變更要求中可傳送的作業數量。下表摘要說明一些重要的限制和配額。

要求類型、限制和錯誤代碼
使用測試存取層級進行作業 每天可對測試帳戶執行 15,000 項 API 作業 RESOURCE_EXHAUSTED
Explorer 存取層級可執行的作業 每天可對正式環境帳戶執行 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 錯誤代碼和訊息清單。

變更要求

除了計入使用者的每日作業配額外，每個 mutate 要求最多只能包含 10,000 個 mutate 作業。如果要求違反這項限制，系統會拒絕要求並傳回錯誤：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 中的下列方法有配額限制。

轉換上傳服務

轉換調整項上傳服務

轉換價值規則

如果帳戶已存在ConversionValueRuleSet，且該attachment_type包含CUSTOMER，則必須將所有新的轉換價值規則加入該規則組合，才能啟用。如果沒有這類轉換價值規則集，您必須建立一個，並按照「建立規則集」一文的說明，將轉換價值規則新增至該規則集。

帳單和帳戶預算服務

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

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

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

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

  • 您應等待至少 12 小時，再對同一帳戶的帳戶預算 (AccountBudget 或 AccountBudgetProposal) 進行變更。如果變更時間未滿 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 錯誤。

處理超過 20 個 ID 的使用者

如果單一使用者擁有的 ID 超過 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 錯誤。

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