Hạn mức và định mức API

API Google Ads thực thi 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 biến đổi. 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
Các thao tác có cấp truy cập Trình khám phá 2.880 thao tác API mỗi ngày đối với tài khoản thực
15.000 thao tác API mỗi ngày đối với tài khoản kiểm thử 		RESOURCE_EXHAUSTED
Các thao tác có cấp truy cập Cơ bản 15.000 thao tác API mỗi ngày đối với cả tài khoản kiểm thử và tài khoản thực RESOURCE_EXHAUSTED
Yêu cầu biến đổi 10.000 thao tác biến đổi mỗi yêu cầu
100 thao tác hành động mỗi yêu cầu 		TOO_MANY_MUTATE_OPERATIONS
TOO_MANY_ACTION_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 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ụ ngân sách tài khoản và thanh toán 1 thao tác mỗi yêu cầu biến đổi TOO_MANY_MUTATE_OPERATIONS

Giới hạn thao tác API hằng ngày

Giới hạn sử dụng API hằng ngày dựa trên số lượng thao tác API được thực hiện cho mỗi mã của nhà phát triển. Thao tác API là tổng số yêu cầu get và thao tác biến đổi. Giới hạn đối với các thao tác API hằng ngày phụ thuộc vào cấp truy cập của mã của nhà phát triển. Hướng dẫn về Cấp truy cập và mức sử dụng cho phép nêu rõ các giới hạn thao tác API cụ thể cho từng cấp truy cập.

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

Giới hạn của gRPC

Tất cả thư viện ứng dụng API Google Ads client libraries đề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 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ả.

Phản hồ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 mỗi yêu cầu.

Các yêu cầu vi phạm giới hạn này sẽ không tạo ra GoogleAdsError, nhưng sẽ tạo ra lỗi gRPC .429 Resource Exhausted Tham khảo danh sách mã lỗi và thông báo gRPC.

Yêu cầu biến đổi

Ngoài việ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 biến đổi không được chứa quá 10.000 thao tác mỗi yêu cầu.

Các 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.

Các giới hạn và lưu ý bổ sung đối với các dịch vụ và loại yêu cầu cụ thể được nêu 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 trong 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 phân trang (ví dụ: các yêu cầu chứa 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 thao tác hằng ngày.

Để biết thêm thông tin về tính năng phân trang, hãy tham khảo bài viết 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 Get, Mutate, Search hoặc SearchStream đượ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.

Dưới đây là một vài 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 bằng GoogleAdsFailure vẫn được tính vào hạn mức thao tác hằng ngày của người dùng.

Các 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 thao tác hằng ngày của người dùng vì các yêu cầu sẽ không bao giờ tiếp cận được dịch vụ. Ví dụ về trường hợp này là 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 mỗi tài khoản 10.000
KeywordPlanAdGroup mỗi KeywordPlan 200
KeywordPlanAdGroupKeyword mỗi KeywordPlan 10.000
KeywordPlanCampaignKeyword (từ khoá phủ định) 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 giới hạn 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 về giá trị lượt chuyển đổi

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 về giá trị lượt chuyển đổi mới vào tập đó để các quy tắc này hoạt động. Nếu không có tập quy tắc về giá trị lượt chuyển đổi nào như vậy, bạn phải tạo một tập 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 bài viết Tạo tập quy tắc.

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

  • Bạn chỉ có thể thực hiện các thao tác biến đổi đối với các tài khoản được định cấu hình để lập hoá đơn hằng tháng.

    Các 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.

    Các 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 đơn đặt hàng ngân sách cho cùng một tài khoản. Việc thực hiện các thay đổi trước khi 12 giờ trôi qua có thể dẫn đến các lỗi không thể khắc phục. Bạn chỉ có thể giải quyết các lỗi này bằng cách liên hệ với người đại diện tài khoản Google Ads.

Lời mời đến tài khoản khách hàng

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

  • Người dùng không thể nhận được nhiều hơn một 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ó một lời mời đang chờ xử lý, thì lỗi này sẽ được trả về: ACCESS_INVITATION_ERROR_EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

  • Tài khoản khách hàng không thể có quá 70 lời mời đang chờ xử lý cùng một lúc. Nếu một yêu cầu được gửi khiến giá trị này bị vượt quá, thì lỗi này sẽ được trả về: ACCESS_INVITATION_ERROR_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 UserData đối tượng trong thao tác create hoặc remove 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. Việc vượt quá giới hạn này trong một đối tượng UserData sẽ dẫn đến 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, thì 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 thao tác 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 PII (Thông tin nhận dạng cá nhân) 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) để ngăn chặn lỗi liên kết.

Ví dụ: nếu một người dùng có 30 địa chỉ email, bạn có thể gửi hai đối tượng UserData.

  • UserData 1: {third_party_user_id: "user123", hashed_email: "email1@...", ... hashed_email: "email19@..."}
  • UserData 2: {third_party_user_id: "user123", hashed_email: "email20@...", ... hashed_email: "email30@..."}

Tổng giới hạn cho user_identifiers trên tất cả các thao tác trong một OfflineUserDataJob vẫn là 100.000.

Các loại giới hạn khác

Một trường lặp lại, chẳng hạn như danh sách các 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 tương tự này cũng có thể do các vấn đề khác.

Nếu bạn gặp phải giới hạn này và đang thực hiện các 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 triển khai danh sách các thao tác trong một yêu cầu biến đổi.

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 bạn vượt quá giới hạn đó, lỗi FILTER_HAS_TOO_MANY_VALUES sẽ được trả về.

Trước
Kiểm tra
Tiếp
Giới hạn của hệ thống