Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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

Google Ads API thực thi các giới hạn đối với hoạt động của API, chẳng hạn như số lượng hoạt động có thể được gửi trong một yêu cầu thay đổi tài nguyên. 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`
Thao tác với cấp truy cập Người khám phá	2.880 thao tác API mỗi ngày đối với tài khoản chính thức 15.000 thao tác API mỗi ngày đối với tài khoản thử nghiệm	`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 có 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 tài nguyên	10.000 thao tác thay đổi tài nguyên 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ụ lập hoá đơ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`

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

Số lượng 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 bao gồm nhiều trường có thể tạo ra phản hồi 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.

Những 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 RESOURCE_EXHAUSTED (mã gRPC 8/HTTP 429). Tham khảo danh sách mã lỗi 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 ở 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 được phân trang

Yêu cầu được 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 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 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ề tính năng phân trang, hãy tham khảo bài viết Phân trang 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 vài ví dụ về những 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 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ụ 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.

Giới hạn ở mức 1 yêu cầu mỗi giây cho mỗi mã khách hàng:
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.
1 QPS được tính là 60 yêu cầu mỗi 60 giây.
Giới hạn ở mức 2 yêu cầu mỗi giây cho mỗi mã khách hàng:
- KeywordPlanIdeaService.GenerateAdGroupThemes

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

Giới hạn khoảng 200 yêu cầu mỗi ngày cho mỗi CID:
- AudienceInsightsService.GenerateAudienceCompositionInsights
- AudienceInsightsService.GenerateSuggestedTargetingInsights
Giới hạn ở mức 2 yêu cầu mỗi giây cho mỗi dự án trên Google Cloud:
- AudienceInsightsService.GenerateTargetingSuggestionMetrics

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

Giới hạn ở mức 2.000 lượt chuyển đổi dẫn đến cuộc gọi hoặc lượt nhấp cho mỗi yêu cầu:
- ConversionUploadService.UploadCallConversions
- ConversionUploadService.UploadClickConversions
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: 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
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: TOO_MANY_ADJUSTMENTS_IN_REQUEST.

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 tài khoản đã có một ConversionValueRuleSet có attachment_type là CUSTOMER, 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 đó có hiệu lực. Nếu chưa có nhóm quy tắc về giá trị lượt chuyển đổi nào như vậy, bạn phải tạo một nhóm và thêm các quy tắc về giá trị lượt chuyển đổi vào nhóm đó như mô tả trong phần Tạo nhóm 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 thay đổi đối với những tài khoản được thiết lập để 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 cho các yêu cầu thay đổi tài nguyê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: 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) cho cùng một tài khoản. Việc thực hiện thay đổi trước khi hết 12 giờ có thể dẫn đến lỗi không thể khôi phục và chỉ có thể được giải quyết bở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 cho 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ào đúng hồ sơ người dùng cuối.

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 những thông tin đó được chuẩn hoá và băm theo yêu cầu của API Google Ads (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 cộng với email từ 1 đến 19 trong đối tượng đầu tiên để nằm trong giới hạn 20 giá trị nhận dạng và thirdPartyUserId cộng với 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 giới hạn cho user_identifiers trên tất cả các thao tác trong một AddOfflineUserDataJobOperationsRequest là 100.000 (một 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 trong 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 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 chia danh sách thao tác thành nhiều yêu cầu thay đổi tài nguyên.

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.

Tổng quan

Tiếp

Giới hạn của hệ thống