API Google Ads thực thi các giới hạn về hoạt động 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. Bảng dưới đây tóm tắt một số giới hạn và hạn mức quan trọng cần lưu ý.
| Loại yêu cầu, giới hạn và mã lỗi | |||
|---|---|---|---|
| Yêu cầu được phân trang | 10.000 hàng mỗi trang |
INVALID_PAGE_SIZE
|
|
| Các thao tác có quyền truy cập cơ bản | 15.000 hoạt động API mỗi ngày |
RESOURCE_EXHAUSTED
|
|
| Thay đổi yêu cầu | 10.000 thao tác mỗi yêu cầu |
TOO_MANY_MUTATE_OPERATIONS
|
|
| Yêu cầu liên quan đến 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
|
|
| Các yêu cầu liên quan đến Dịch 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 |
TOO_MANY_MUTATE_OPERATIONS
|
|
Giới hạn hoạt động hằng ngày của API
Hạn mức sử dụng API hằng ngày dựa trên số hoạt động API được thực hiện trên mỗi mã của nhà phát triển. Toán tử API là tổng cộng của yêu cầu nhận và thao tác thay đổi. Giới hạn về số lần hoạt động của 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à quyền sử dụng được phép nêu ra các giới hạn hoạt động cụ thể của API cho từng cấp truy cập.
Hệ thống sẽ từ chối những yêu cầu vi phạm các giới hạn này với lỗi:
RESOURCE_EXHAUSTED.
Các giới hạn của gRPC
Tất cả thư viện ứng dụng của API Google Ads đề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 tính 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 được chọn, giảm kích thước trang hoặc sử dụng tính năng phát trực tuyến. Đối với các thay đổi, hãy gửi ít thao tác hơn trong 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.
Thay đổi yêu cầu
Ngoài việc được tính vào hạn mức hoạt động hằng ngày của người dùng, một yêu cầu thay đổi không được chứa nhiều hơn 10.000 thao tác trên 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 cân nhắc bổ sung cho các dịch vụ và loại yêu cầu cụ thể được trình bày bên dưới.
Tìm kiếm yêu cầu
Yêu cầu Search hoặc SearchStream được tính là một thao tác so với hạn mức hoạt động hằng ngày của người dùng. Một yêu cầu SearchStream sẽ được tính là một thao tác API, bất kể số lượng lô.
Yêu cầu được phân trang
Các yêu cầu được 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 hoạt động hằng ngày của người dùng.
Tuy nhiên, các yêu cầu phân trang có 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 trường hợp ngoại lệ và sẽ được tính vào hạn mức hoạt động hằng ngày.
Các yêu cầu được phân trang (chẳng hạn như yêu cầu tìm kiếm) cũng phải tuân theo giới hạn Page size cannot exceed 10,000 rows và sẽ bị từ chối nếu vi phạm giới hạn này với lỗi: INVALID_PAGE_SIZE.
Để biết thêm thông tin chi tiết về tính năng phân trang, hãy tham khảo bài viết Phân trang thông qua kết quả.
Các loại yêu cầu khác
Những yêu cầu không phải là yêu cầu Get, Mutate, Search hoặc SearchStream sẽ được tính là một thao tác trong hạn mức hoạt động hằng ngày của người dùng.
Sau đây là một số ví dụ về những yêu cầu này:
BatchJobService.ListMutateJobResultsConversionUploadService.UploadCallConversionsConversionUploadService.UploadClickConversionsOfflineUserDataJobService.AddOfflineUserDataJobOperationsOfflineUserDataJobService.CreateOfflineUserDataJobUserDataService.UploadUserData
Yêu cầu trả về ngoại lệ API
Các yêu cầu bị từ chối có 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.
Các yêu cầu không thành công nhưng không trả về GoogleAdsFailure, chẳng hạn như từ 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ờ đạt đến dịch vụ. Ví dụ như lỗi kết nối mạng.
Dịch vụ lập kế hoạch
Do chi phí và tính phức tạp, các phương thức dịch vụ Lập kế hoạch nêu dưới đây phải tuân theo các giới hạn riêng biệt với các loại yêu cầu khác.
Giới hạn ở 1 yêu cầu mỗi giây cho mỗi mã khách hàng hoặc mã của nhà phát triển:
KeywordPlanService.GetKeywordPlanKeywordPlanService.GenerateHistoricalMetricsKeywordPlanService.GenerateForecastMetrics
Hệ thống sẽ từ chối những yêu cầu vi phạm các giới hạn này với lỗi:
RESOURCE_EXHAUSTED.1 QPS được tính là 60 yêu cầu trong mỗi 60 giây.
Hãy lưu ý đến những giới hạn này khi tạo kế hoạch từ khoá.
| Đối tượng kế hoạch từ khóa | Số lượng tối đa |
|---|---|
KeywordPlan trên mỗi tài khoản |
10.000 |
KeywordPlanAdGroup trên mỗi KeywordPlan |
200 |
KeywordPlanAdGroupKeyword trên mỗi KeywordPlan |
10.000 |
KeywordPlanCampaignKeyword (từ khoá phủ định) |
1.000 |
KeywordPlanCampaign trên mỗi KeywordPlan |
1 |
Dịch vụ tải lượt chuyển đổi lên
Giới hạn ở 2.000 lượt chuyển đổi cuộc gọi hoặc lượt nhấp cho mỗi yêu cầu:
Hệ thống sẽ từ chối những yêu cầu vi phạm các giới hạn này với lỗi:
TOO_MANY_CONVERSIONS_IN_REQUEST.
Dịch vụ tải điều chỉnh chuyển đổi lên
Giới hạn ở 2.000 mức điều chỉnh lượt chuyển đổi cho mỗi yêu cầu:
Hệ thống sẽ từ chối những yêu cầu vi phạm các giới hạn này với lỗi:
TOO_MANY_ADJUSTMENTS_IN_REQUEST.
Dịch vụ thanh toán và ngân sách tài khoản
Bạn chỉ có thể thực hiện thay đổi đối với những tài khoản đã thiết lập để sử dụng 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 kèm theo lỗi:
MUTATE_NOT_ALLOWED.Chỉ được phép thực hiện 1 thao tác đối với yêu cầu thay đổi.
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.Bạn nên đợi ít nhất 12 giờ giữa các lần thay đổi yêu cầu ngân sách cho cùng một tài khoản. Nếu bạn thực hiện các thay đổi trước thời hạn 12 giờ kể từ giờ, thì các lỗi không thể khôi phục có thể dẫn đến những lỗi không thể khôi phục. Chỉ người đại diện tài khoản Google Ads của bạn mới có thể giải quyết vấn đề này.
Lời mời đến tài khoản khách hàng
Người dùng mới có thể được mời vào các tài khoản khách hàng hiện tại bằng CustomerUserAccessService. Vì chức năng này gửi email mời đến người dùng khác nên chức năng này có khả năng bị sử dụng sai mục đích và do đó có các hạn chế về hoạt động:
Người dùng không được nhận được 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 bạn gửi yêu cầu tiếp theo để gửi lời mời đến người dùng đã có 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 đượ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 được gửi và giá trị này vượt quá, thì 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ý bằng UserDataService và OfflineUserDataJobService.
Trong một thao tác tạo/xoá UserData cụ thể, mỗi nhóm user_identifiers phải dành riêng cho một người dùng.
Để thực thi việc này, hệ thống sẽ trả về lỗi OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS hoặc UserDataError.TOO_MANY_USER_IDENTIFIERS khi có nhiều hơn 20 user_identifiers trong tập hợp UserData.
Các loại giới hạn khác
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 tương tự này cũng có thể do các vấn đề khác.
Nếu bạn gặp phải hạn chế này và đang đưa ra 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 thao tác trong yêu cầu thay đổi.
Khi tạo một 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 đó, hệ thống sẽ trả về lỗi FILTER_HAS_TOO_MANY_VALUES.