Hạn mức và giới hạn API

Google Ads API áp dụng các giới hạn đối với các thao tác API, chẳng hạn như số lượng thao tác có thể được gửi trong một yêu cầu thay đổi tài nguyên duy nhất. Bảng sau đây tóm tắt một số giới hạn và hạn mức quan trọng mà bạn cần lưu ý.

Loại yêu cầu, giới hạn và mã lỗi
Thao tác với cấp truy cập Thử nghiệm 15.000 thao tác API mỗi ngày đối với tài khoản thử nghiệm RESOURCE_EXHAUSTED
Các thao tác có cấp truy cập Explorer 2.880 thao tác API mỗi ngày đối với tài khoản sản xuất
15.000 thao tác API mỗi ngày đối với tài khoản kiểm thử 		RESOURCE_EXHAUSTED
Thao tác với cấp truy cập Cơ bản 15.000 thao tác API mỗi ngày cho cả tài khoản thử nghiệm và tài khoản chính thức RESOURCE_EXHAUSTED
Thao tác với cấp truy cập Tiêu chuẩn Không giới hạn số lượng thao tác API mỗi ngày đối với cả tài khoản thử nghiệm và tài khoản chính thức Không áp dụng
Yêu cầu thay đổi 10.000 thao tác biến đổi cho mỗi yêu cầu TOO_MANY_MUTATE_OPERATIONS
Yêu cầu dịch vụ lập kế hoạch 1 QPS (số lần truy vấn mỗi giây) RESOURCE_EXHAUSTED
Yêu cầu về Dịch vụ tải lượt chuyển đổi lên 2.000 lượt chuyển đổi mỗi yêu cầu TOO_MANY_CONVERSIONS_IN_REQUEST
Yêu cầu dịch vụ về thanh toán và ngân sách tài khoản 1 thao tác cho mỗi yêu cầu thay đổi tài nguyên TOO_MANY_MUTATE_OPERATIONS

Hạn mức thao tác API hằng ngày

Hạn mức sử dụng API hằng ngày dựa trên số lượng thao tác API mà dự án của bạn trên Google Cloud thực hiện. Thao tác API là tổng số yêu cầu Search và SearchStream, các thao tác biến đổi riêng lẻ và các yêu cầu dịch vụ khác. Giới hạn cho các thao tác API hằng ngày phụ thuộc vào cấp truy cập API của dự án trên đám mây Google. Hướng dẫn về cấp truy cập và việc sử dụng được phép nêu rõ các giới hạn cụ thể về thao tác API cho từng cấp truy cập.

Những yêu cầu vi phạm các giới hạn này sẽ bị từ chối kèm theo lỗi: RESOURCE_EXHAUSTED.

Giới hạn của gRPC

Tất cả thư viện ứng dụng Google Ads API đều sử dụng gRPC để tạo yêu cầu và phản hồi. Theo mặc định, gRPC có kích thước thông báo là 4 MB, nhưng các thư viện ứng dụng của chúng tôi đặt kích thước thông báo tối đa là 64 MB để tăng hiệu quả.

Câu trả lời không được vượt quá giới hạn này. Ví dụ: một yêu cầu tìm kiếm có nhiều trường có thể tạo ra một phản hồi có kích thước vượt quá 64 MB. Để tránh giới hạn này, bạn có thể giảm số lượng trường đã chọn hoặc sử dụng tính năng truyền trực tuyến. Đối với các thao tác biến đổi, hãy gửi ít thao tác hơn cho mỗi yêu cầu.

Những yêu cầu vi phạm giới hạn này sẽ không tạo ra GoogleAdsError mà sẽ tạo ra lỗi RESOURCE_EXHAUSTED (mã gRPC 8 / HTTP 429). Tham khảo danh sách mã và thông báo lỗi gRPC.

Yêu cầu thay đổi tài nguyên

Ngoài việc được tính vào hạn mức thao tác hằng ngày của người dùng, một yêu cầu thay đổi tài nguyên không được chứa quá 10.000 thao tác thay đổi tài nguyên cho mỗi yêu cầu. Những yêu cầu vi phạm giới hạn này sẽ bị từ chối kèm theo lỗi: TOO_MANY_MUTATE_OPERATIONS.

Các giới hạn và điểm cần lưu ý khác đối với một số dịch vụ và loại yêu cầu cụ thể được nêu trong phần tiếp theo.

Yêu cầu tìm kiếm

Yêu cầu Search hoặc SearchStream được tính là một thao tác đối với hạn mức thao tác hằng ngày của người dùng. Một yêu cầu SearchStream được tính là một thao tác API, bất kể số lượng lô.

Yêu cầu phân trang

Các yêu cầu được phân trang (ví dụ: các yêu cầu chứa một next_page_token hợp lệ) không được tính vào hạn mức thao tác hằng ngày của người dùng. Tuy nhiên, các yêu cầu phân trang chứa mã thông báo trang đã hết hạn hoặc không hợp lệ sẽ tạo ra một ngoại lệ và được tính vào hạn mức hoạt động hằng ngày.

Để biết thêm thông tin về việc phân trang, hãy tham khảo phần Phân trang qua kết quả.

Các loại yêu cầu khác

Một yêu cầu không phải là yêu cầu Mutate, Search hoặc SearchStream sẽ được tính là một thao tác trong hạn mức thao tác hằng ngày của người dùng.

Sau đây là một số ví dụ về các yêu cầu như vậy:

Yêu cầu trả về ngoại lệ API

Các yêu cầu bị từ chối kèm theo mã GoogleAdsFailure vẫn được tính vào hạn mức hoạt động hằng ngày của người dùng.

Những yêu cầu không thành công nhưng không trả về GoogleAdsFailure, chẳng hạn như do lỗi ở cấp mạng, sẽ không được tính vào hạn mức hoạt động hằng ngày của người dùng vì các yêu cầu đó sẽ không bao giờ đến được dịch vụ. Ví dụ: lỗi kết nối mạng.

Dịch vụ lập kế hoạch từ khoá

Do chi phí và độ phức tạp, các phương thức dịch vụ Lập kế hoạch từ khoá sau đây phải tuân theo các giới hạn riêng biệt so với các loại yêu cầu khác.

Hãy lưu ý những giới hạn này khi tạo kế hoạch từ khoá.

Đối tượng kế hoạch từ khoá Số lượng tối đa
KeywordPlan cho mỗi tài khoản 10.000
KeywordPlanAdGroup mỗi KeywordPlan 200
KeywordPlanAdGroupKeyword mỗi KeywordPlan 10.000
KeywordPlanCampaignKeyword (từ khoá phủ định) cho mỗi KeywordPlan 1.000
KeywordPlanCampaign mỗi KeywordPlan 1

Dịch vụ thông tin chi tiết về đối tượng

Các phương thức sau đây trong AudienceInsightsService phải tuân theo các hạn mức cụ thể.

Dịch vụ tải lượt chuyển đổi lên

Dịch vụ tải mức điều chỉnh cho lượt chuyển đổi lên

Quy tắc giá trị lượt chuyển đổi

  • Giới hạn 100.000 quy tắc về giá trị lượt chuyển đổi cho mỗi tài khoản.

    Những yêu cầu vi phạm giới hạn này sẽ bị từ chối kèm theo lỗi ResourceCountLimitExceededError.ACCOUNT_LIMIT.

Nếu một ConversionValueRuleSet có attachment_type là CUSTOMER đã tồn tại cho tài khoản, thì bạn phải thêm mọi quy tắc mới về giá trị lượt chuyển đổi vào nhóm đó để các quy tắc này có hiệu lực. Nếu không có quy tắc về giá trị lượt chuyển đổi nào như vậy, bạn phải tạo một quy tắc và thêm các quy tắc về giá trị lượt chuyển đổi vào đó như mô tả trong phần Tạo quy tắc.

Dịch vụ thanh toán và ngân sách tài khoản

  • Bạn chỉ có thể thực hiện các thao tác thay đổi đối với những tài khoản được thiết lập phương thức lập hoá đơn hằng tháng.

    Những yêu cầu vi phạm giới hạn này sẽ bị từ chối và báo lỗi: MUTATE_NOT_ALLOWED.

  • Bạn chỉ được phép thực hiện 1 thao tác cho các yêu cầu biến đổi.

    Những yêu cầu vi phạm giới hạn này sẽ bị từ chối và báo lỗi: TOO_MANY_MUTATE_OPERATIONS.

  • Bạn nên đợi ít nhất 12 giờ giữa các lần thay đổi ngân sách tài khoản (AccountBudget hoặc AccountBudgetProposal) đối với cùng một tài khoản. Nếu bạn thực hiện thay đổi trước khi hết 12 giờ, có thể xảy ra lỗi không thể khắc phục. Bạn chỉ có thể giải quyết lỗi này bằng cách liên hệ với người đại diện tài khoản Google Ads của bạn.

Lời mời tham gia tài khoản khách hàng

Bạn có thể mời người dùng mới vào tài khoản khách hàng hiện có bằng CustomerUserAccessInvitationService. Vì tính năng này gửi email gửi lời mời đến những người dùng khác, nên có khả năng bị sử dụng sai mục đích và do đó, có một số hạn chế đối với hành vi của tính năng này:

  • Người dùng không thể nhận nhiều lời mời đang chờ xử lý cho cùng một tài khoản khách hàng. Nếu một yêu cầu tiếp theo được thực hiện để gửi lời mời đến một người dùng đã có lời mời đang chờ xử lý, thì lỗi này sẽ được trả về: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

  • Tài khoản khách hàng không được có quá 70 lời mời đang chờ xử lý cùng một lúc. Nếu bạn gửi một yêu cầu khiến giá trị này bị vượt quá, thì lỗi này sẽ được trả về: PENDING_INVITATIONS_LIMIT_EXCEEDED.

Dữ liệu người dùng

Dữ liệu người dùng được quản lý bằng UserDataService và OfflineUserDataJobService.

Mỗi đối tượng UserData trong một thao tác create hoặc remove đều liên quan đến một người dùng cuối. Trường user_identifiers trong một đối tượng UserData chỉ được chứa tối đa 20 giá trị nhận dạng. Nếu vượt quá giới hạn này trong một đối tượng UserData, bạn sẽ gặp lỗi OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS hoặc UserDataError.TOO_MANY_USER_IDENTIFIERS.

Xử lý người dùng có hơn 20 giá trị nhận dạng

Nếu một người dùng cuối có hơn 20 giá trị nhận dạng mà bạn cần tải lên, bạn nên phân phối các giá trị nhận dạng này trên nhiều đối tượng UserData. Để đảm bảo Google có thể liên kết tất cả các giá trị nhận dạng này với cùng một người dùng cuối, mỗi đối tượng UserData cho người dùng đó phải bao gồm ít nhất một user_identifier chung, chẳng hạn như cùng một hashed_email, hashed_phone_number hoặc third_party_user_id. Google sử dụng các giá trị nhận dạng được chia sẻ này để liên kết và hợp nhất thông tin từ các hoạt động UserData riêng biệt với hồ sơ người dùng cuối chính xác.

Nếu bạn dựa vào thông tin nhận dạng cá nhân (PII) như email hoặc số điện thoại đã băm, hãy đảm bảo rằng thông tin đó được chuẩn hoá và băm theo các yêu cầu của Google Ads API (SHA-256, chữ thường, không có khoảng trắng) để tránh lỗi liên kết.

Ví dụ: nếu người dùng có 30 địa chỉ email, bạn có thể gửi hai đối tượng UserData có chung một third_party_user_id (đặt thirdPartyUserId và email từ 1 đến 19 trong đối tượng đầu tiên để không vượt quá giới hạn 20 giá trị nhận dạng, và đặt thirdPartyUserId và email từ 20 đến 30 trong đối tượng thứ hai):

{
  "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" }
  ]
}

Tổng hạn mức cho user_identifiers trên tất cả các thao tác trong một AddOfflineUserDataJobOperationsRequest là 100.000 (OfflineUserDataJob có thể chấp nhận nhiều lệnh gọi AddOfflineUserDataJobOperationsRequest, tối đa là 1.000.000 thao tác cho mỗi công việc). Đối với các lượt tải lên đồng bộ bằng cách sử dụng UploadUserDataRequest (UserDataService.UploadUserData), mỗi yêu cầu được giới hạn tối đa 10 thao tác và 100 user_identifiers trên toàn bộ yêu cầu.

Các loại hạn mức khác

Một trường lặp lại (chẳng hạn như danh sách thao tác) có quá nhiều mục trong một yêu cầu có thể gây ra lỗi: REQUEST_SIZE_LIMIT_EXCEEDED. Thông báo lỗi này cũng có thể là do các vấn đề khác.

Nếu bạn gặp phải giới hạn này và đang đưa ra yêu cầu sử dụng trường lặp lại, hãy thử giảm số lượng mục trong trường lặp lại bằng cách chia danh sách thao tác thành nhiều yêu cầu thay đổi tài nguyên.

Khi thực hiện truy vấn GAQL, số lượng mục tối đa trong mệnh đề IN là 20.000. Nếu vượt quá giới hạn đó, bạn sẽ nhận được lỗi FILTER_HAS_TOO_MANY_VALUES.

Trước
Tổng quan
Tiếp
Giới hạn của hệ thống