Google Ads API là công cụ mạnh mẽ giúp quản lý và tối ưu hóa các chiến dịch quảng cáo một cách linh hoạt và hiệu quả. Tuy nhiên, để sử dụng công cụ này một cách tối ưu, bạn cần nắm rõ các hạn mức và giới hạn mà Google áp dụng. Những yếu tố này không chỉ ảnh hưởng đến số lượng thao tác mà bạn có thể thực hiện mà còn quyết định hiệu quả vận hành chiến dịch của bạn. Trong bài viết này, chúng tôi sẽ đi sâu phân tích các loại hạn mức, cách xử lý lỗi thường gặp và các mẹo tối ưu để tận dụng tối đa Google Ads API.
API Google Ads áp dụng các giới hạn và hạn mức đối với các thao tác, chẳng hạn như số lượng thao tác được phép trong một yêu cầu thay đổi duy nhất. Dưới đây là bảng tóm tắt các giới hạn và hạn mức quan trọng cần chú ý.
Phân loại yêu cầu, giới hạn và mã lỗi
- Thao tác với quyền truy cập cơ bản: tối đa 15.000 hoạt động API mỗi ngày – lỗi:
RESOURCE_EXHAUSTED. - Yêu cầu thay đổi: tối đa 10.000 thao tác trong một yêu cầu – lỗi:
TOO_MANY_MUTATE_OPERATIONS. - Yêu cầu dịch vụ lập kế hoạch: 1 QPS (query per second) – lỗi:
RESOURCE_EXHAUSTED. - Yêu cầu tải lượt chuyển đổi lên: tối đa 2.000 lượt chuyển đổi cho mỗi yêu cầu – lỗi:
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 trong một yêu cầu thay đổi – lỗi:
TOO_MANY_MUTATE_OPERATIONS.
Hạn mức thao tác API hằng ngày
Hạn mức API hằng ngày được tính dựa trên số thao tác thực hiện với mỗi mã phát triển viên. Tổng thao tác bao gồm số yêu cầu get và các thao tác thay đổi. Hạn mức này thay đổi tùy thuộc vào cấp truy cập của mã phát triển viên. Bạn có thể tham khảo chi tiết giới hạn cụ thể trong phần Cấp truy cập và mục đích sử dụng được phép.
Các yêu cầu vượt quá giới hạn sẽ bị từ chối với mã lỗi RESOURCE_EXHAUSTED.
Các hạn chế của gRPC
Tất cả thư viện ứng dụng trong API Google Ads đều sử dụng gRPC để xử lý yêu cầu và phản hồi. Theo mặc định, gRPC giới hạn kích thước thông báo ở mức 4 MB, tuy nhiên thư viện API Google Ads đã điều chỉnh giới hạn này lên tối đa 64 MB nhằm tăng hiệu suất hoạt động.
Phản hồi từ các yêu cầu không được vượt quá giới hạn 64 MB. Ví dụ: một yêu cầu tìm kiếm có nhiều trường dữ liệu có thể dẫn đến phản hồi vượt kích thước cho phép. Để tránh vi phạm giới hạn:
- Giảm số trường được chọn trong yêu cầu tìm kiếm.
- Sử dụng tính năng truyền trực tuyến (streaming) khi xử lý dữ liệu lớn.
- Với thao tác thay đổi, hãy chia nhỏ số thao tác trong từng yêu cầu.
Nếu vi phạm, yêu cầu sẽ không trả về lỗi GoogleAdsError, mà thay vào đó sẽ tạo lỗi gRPC 429 Resource Exhausted. Để biết thêm thông tin, tham khảo danh sách thông báo và mã lỗi của gRPC.
Yêu cầu thay đổi
Mỗi yêu cầu thay đổi trong API Google Ads có giới hạn tối đa 10.000 thao tác, bên cạnh hạn mức thao tác API hằng ngày của người dùng.
Nếu yêu cầu vượt quá giới hạn này, hệ thống sẽ từ chối với lỗi TOO_MANY_MUTATE_OPERATIONS.
Trong phần tiếp theo, chúng tôi sẽ trình bày chi tiết các giới hạn và khuyến nghị dành cho từng dịch vụ và loại yêu cầu cụ thể trong API Google Ads.
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 API hằng ngày của người dùng. Đối với SearchStream, số lượng lô dữ liệu trong phản hồi không ảnh hưởng đến số lần thao tác được tính, vì mỗi yêu cầu chỉ được tính là một thao tác API.
Yêu cầu được phân trang
Các yêu cầu phân trang (ví dụ: 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 API hằng ngày. Tuy nhiên, nếu next_page_token đã hết hạn hoặc không hợp lệ, yêu cầu sẽ phát sinh lỗi và được tính vào hạn mức thao tác API của người dùng.
Để biết thêm thông tin về cách sử dụng tính năng phân trang, hãy tham khảo tài liệu Phân trang qua kết quả.
Các loại yêu cầu khác
Các yêu cầu không thuộc loại Get, Mutate, Search, hoặc SearchStream đều được tính là một thao tác trong hạn mức thao tác API hằng ngày của người dùng. Dưới đây là một số ví dụ về các loại yêu cầu này:
- BatchJobService.ListMutateJobResults
- ConversionUploadService.UploadCallConversions
- ConversionUploadService.UploadClickConversions
- OfflineUserDataJobService.AddOfflineUserDataJobOperations
- OfflineUserDataJobService.CreateOfflineUserDataJob
- UserDataService.UploadUserData
Các yêu cầu trả về ngoại lệ API
Các yêu cầu bị từ chối với lỗi GoogleAdsFailure vẫn được tính vào hạn mức thao tác hằng ngày.
Ngược lại, các yêu cầu thất bại do lỗi mạng hoặc lỗi hệ thống (không trả về GoogleAdsFailure) sẽ không được tính vào hạn mức, vì chúng không đến được dịch vụ API. Ví dụ điển hình là lỗi kết nối mạng.
Dịch vụ lập kế hoạch
Vì độ phức tạp và chi phí xử lý, các phương thức trong Dịch vụ lập kế hoạch (Planning Service) được áp dụng các hạn mức riêng biệt, độc lập với các loại yêu cầu khác.
Hạn mức và giới hạn
- Giới hạn 1 yêu cầu mỗi giây (1 QPS) cho mỗi mã khách hàng:
- KeywordPlanIdeaService.GenerateKeywordIdeas
- KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
- KeywordPlanIdeaService.GenerateKeywordForecastMetrics
Nếu vượt quá hạn mức này, yêu cầu sẽ bị từ chối với mã lỗi:
RESOURCE_EXHAUSTED.
Lưu ý: 1 QPS tương đương với 60 yêu cầu trong vòng 60 giây. - Giới hạn 2 yêu cầu mỗi giây (2 QPS) cho mỗi CID:
- KeywordPlanIdeaService.GenerateAdGroupTheme
Hạn mức đối tượng trong kế hoạch từ khoá
| Đối tượng kế hoạch từ khoá | Số lượng tối đa |
|---|---|
| KeywordPlan trên mỗi tài khoản | 10.000 |
| KeywordPlanAdGroup trên mỗi kế hoạch | 200 |
| KeywordPlanAdGroupKeyword mỗi kế hoạch | 10.000 |
| KeywordPlanCampaignKeyword (từ khoá phủ định) | 1.000 |
| KeywordPlanCampaign trên mỗi kế hoạch | 1 |
Dịch vụ tải lượt chuyển đổi lên
Mỗi yêu cầu tải lượt chuyển đổi lên được giới hạn ở mức tối đa 2.000 lượt chuyển đổi, bao gồm cả lượt gọi và lượt nhấp:
- ConversionUploadService.UploadCallConversions
- ConversionUploadService.UploadClickConversions
Nếu yêu cầu vượt quá giới hạn này, hệ thống sẽ từ chối với mã lỗi: TOO_MANY_CONVERSIONS_IN_REQUEST.
Dịch vụ tải mức điều chỉnh lượt chuyển đổi lên
Mỗi yêu cầu tải mức điều chỉnh lượt chuyển đổi lên được giới hạn ở 2.000 mức điều chỉnh:
- ConversionAdjustmentUploadService.UploadConversionAdjustments
Các yêu cầu vượt quá giới hạn này sẽ bị từ chối với mã lỗi: TOO_MANY_ADJUSTMENTS_IN_REQUEST.
Dịch vụ thanh toán và ngân sách tài khoản
Giới hạn và lưu ý
- Chỉ những tài khoản được cấu hình cho hình thức thanh toán bằng hóa đơn hàng tháng mới có thể tạo biến thể ngân sách.
Nếu vi phạm, yêu cầu sẽ bị từ chối với lỗi:MUTATE_NOT_ALLOWED. - Mỗi yêu cầu thay đổi chỉ được phép thực hiện tối đa 1 thao tác.
Các yêu cầu vượt giới hạn này sẽ trả về lỗi:TOO_MANY_MUTATE_OPERATIONS.
Khoảng thời gian giữa các lần thay đổi
Khi thay đổi thứ tự ngân sách cho cùng một tài khoản, bạn cần đợi ít nhất 12 giờ trước khi thực hiện lần thay đổi tiếp theo. Nếu vi phạm khoảng thời gian này, hệ thống có thể trả về lỗi nghiêm trọng không thể khôi phục. Trong trường hợp này, chỉ đại diện tài khoản Google Ads mới có thể hỗ trợ giải quyết.
Lời mời truy cập vào 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 CustomerUserAccessService. Tuy nhiên, do tính năng này gửi email mời, việc sử dụng không đúng cách có thể gây ra các vấn đề. Vì vậy, hệ thống áp dụng một số hạn chế sau:
- Hạn chế lời mời cho một email:
- Một người dùng không thể nhận nhiều lời mời đang chờ xử lý từ cùng một tài khoản khách hàng.
- Nếu gửi lời mời tiếp theo cho email đã có lời mời đang chờ xử lý, lỗi sẽ được trả về:
ACCESS_INVITATION_ERROR_EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.
- Giới hạn số lượng lời mời đang chờ xử lý:
- Một tài khoản khách hàng không được có hơn 70 lời mời đang chờ xử lý cùng một lúc.
- Nếu yêu cầu mới vượt quá giới hạn này, hệ thống sẽ trả về lỗi:
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ý thông qua UserDataService và OfflineUserDataJobService, nhằm hỗ trợ việc xử lý dữ liệu trong các chiến dịch quảng cáo Google Ads. Khi thực hiện thao tác tạo hoặc xóa UserData, mỗi tập hợp user_identifiers phải được đảm bảo gắn kết với một người dùng duy nhất.
Để đảm bảo tuân thủ, nếu có nhiều hơn 20 user_identifiers trong một tập hợp UserData, hệ thống sẽ trả về lỗi OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS hoặc UserDataError.TOO_MANY_USER_IDENTIFIERS.
Các loại hạn mức khác
Trong trường hợp sử dụng các trường lặp lại (ví dụ: danh sách thao tác), nếu số lượng mục vượt quá giới hạn quy định trong một yêu cầu, hệ thống có thể trả về lỗi REQUEST_SIZE_LIMIT_EXCEEDED. Thông báo lỗi này cũng có thể xuất hiện do những vấn đề khác liên quan đến kích thước yêu cầu.
Nếu bạn gặp phải giới hạn này khi sử dụng các trường lặp lại, hãy cân nhắc giảm số lượng mục bằng cách chia nhỏ danh sách thao tác trong từng yêu cầu thay đổi.
Khi tạo truy vấn GAQL (Google Ads Query Language), mệnh đề IN được giới hạn ở mức tối đa 20.000 mục. Nếu vượt quá giới hạn này, hệ thống sẽ trả về lỗi FILTER_HAS_TOO_MANY_VALUES.
Hiểu rõ các hạn mức và hạn chế của Google Ads API không chỉ giúp bạn tránh được các lỗi phổ biến mà còn tối ưu hóa hiệu suất hoạt động cho chiến dịch quảng cáo của mình. Bằng cách tuân thủ các quy tắc và áp dụng những mẹo được đề xuất, bạn có thể khai thác tối đa sức mạnh của Google Ads API mà vẫn đảm bảo hiệu quả kinh doanh. Đừng để các hạn chế trở thành rào cản, hãy biến chúng thành cơ hội để cải thiện chiến lược quảng cáo của bạn ngay hôm nay.
