Hạn mức và hạn 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 thay đổi 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 cần lưu ý.

Loại yêu cầu, giới hạn và mã lỗi
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 cho mỗi yêu cầu	TOO_MANY_MUTATE_OPERATIONS
Yêu cầu về 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 cho 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 cho mỗi yêu cầu thay đổi	TOO_MANY_MUTATE_OPERATIONS

Giới hạn số lượt 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ố hoạt động API được thực hiện trên mỗi mã của nhà phát triển. Số hoạt động của API là tổng số của các yêu cầu get và thao tác thay đổi. Giới hạn cho các hoạt động API hằng ngày phụ thuộc vào cấp truy cập của mã thông báo nhà phát triển. Hướng dẫn về Cấp truy cập và Mục đích sử dụng được phép trình bày các giới hạn hoạt động API cụ thể cho từng cấp truy cập.

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

Các hạn chế 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 để tăng tính hiệu quả, thư viện ứng dụng của chúng tôi lại đặt kích thước thông báo tối đa là 64 MB.

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 thay đổi, hãy gửi ít thao tác hơn cho 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 các thông báo và mã lỗi gRPC.

Thay đổi yêu cầu

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ỗi yêu cầu thay đổi không được chứa nhiều hơn 10.000 thao tác.

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

Tiếp theo, chúng tôi sẽ trình bày các giới hạn và điều cần cân nhắc khác đối với các dịch vụ và loại yêu cầu cụ thể.

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 đượ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 ngoại lệ và sẽ được tính vào hạn mức thao tác hằng ngày.

Để 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

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.

Sau đây là một số ví dụ về các yêu cầu như vậ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 bằng 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ư do lỗi ở cấp mạng, sẽ không 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

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

• Giới hạn ở mức 1 yêu cầu mỗi giây cho mỗi mã khách hàng:

  • KeywordPlanIdeaService.GenerateKeywordIdeas
  • KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics
  • KeywordPlanIdeaService.GenerateKeywordForecastMetrics

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

• 1 QPS được tính là 60 yêu cầu mỗi 60 giây.

• Giới hạn ở 2 yêu cầu mỗi giây cho mỗi CID:

  • KeywordPlanIdeaService.GenerateAdGroupTheme

Hãy lưu ý những hạn mức 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/KeywordPlan	200
KeywordPlanAdGroupKeyword mỗi KeywordPlan	10.000
KeywordPlanCampaignKeyword (từ khoá phủ định)	1.000
KeywordPlanCampaign/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 từ lượt gọi hoặc lượt nhấp trên mỗi yêu cầu:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

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

Dịch vụ tải mức điều chỉnh lượt 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:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  Các 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: 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ể tạo biến thể cho những 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 kèm theo lỗi: MUTATE_NOT_ALLOWED.

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

  Các 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 thứ tự ngân sách cho cùng một tài khoản. Việc thực hiện thay đổi trước khi 12 giờ trôi qua có thể dẫn đến lỗi không thể khôi phục và chỉ có người đại diện tài khoản Google Ads mới có thể 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. Vì tính năng này gửi email mời đến người dùng khác nên có khả năng bị sử dụng sai mục đích. Do đó, tính năng này có một số hạn chế:

• 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 bạn thực hiện 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 thể có nhiều hơn 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 vượt quá, 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. Trong một thao tác tạo hoặc xoá UserData nhất định, mỗi tập hợp user_identifiers phải dành riêng cho một người dùng.

Để thực thi điều này, lỗi OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS hoặc UserDataError.TOO_MANY_USER_IDENTIFIERS sẽ được trả về khi có nhiều hơn 20 user_identifiers trong một tập hợp UserData.

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 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 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 tạo 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 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.