API sınırları ve kotaları

Google Ads API, tek bir değişiklik isteğinde gönderilebilecek işlem sayısı gibi API işlemleriyle ilgili sınırlamalar uygular. Aşağıdaki tabloda, dikkat edilmesi gereken önemli sınırlardan ve kotalardan bazıları özetlenmiştir.

Günlük API işlemi sınırları

Günlük API kullanım sınırları, Google Cloud projeniz tarafından yapılan API işlemlerinin sayısına bağlıdır. API işlemleri; Search ve SearchStream isteklerinin, bağımsız mutasyon işlemlerinin ve diğer hizmet isteklerinin toplamıdır. Günlük API işlemlerinin sınırları, Google Cloud projenizin API erişim düzeyine bağlıdır. Erişim düzeyleri ve izin verilen kullanım kılavuzu, her erişim düzeyi için belirli API işlem sınırlarını özetler.

Bu sınırları ihlal eden istekler şu hatayla reddedilir: RESOURCE_EXHAUSTED.

gRPC sınırlamaları

Tüm Google Ads API istemci kitaplıkları, istek ve yanıt oluşturmak için gRPC kullanır. gRPC'nin varsayılan mesaj boyutu 4 MB'tır ancak istemci kitaplıklarımız, verimliliği artırmak için maksimum mesaj boyutunu 64 MB olarak ayarlar.

Yanıtlar bu sınırı aşmamalıdır. Örneğin, çok sayıda alan içeren bir arama isteği, boyutu 64 MB'ı aşan bir yanıt oluşturabilir. Bu sınıra takılmamak için seçilen alanların sayısını azaltabilir veya akış özelliğini kullanabilirsiniz. Değişiklikler için istek başına daha az işlem gönderin.

Bu sınırlamayı ihlal eden istekler GoogleAdsError oluşturmaz, ancak RESOURCE_EXHAUSTED (gRPC kodu 8 / HTTP 429) hatası oluşturur. gRPC hata kodları ve mesajları listesine bakın.

Değişiklik istekleri

Kullanıcının günlük işlem kotasına dahil edilmesinin yanı sıra, bir değişiklik isteği,istek başına 10.000'den fazla değişiklik işlemi içeremez. Bu sınırlamayı ihlal eden istekler şu hatayla reddedilir: TOO_MANY_MUTATE_OPERATIONS.

Belirli hizmetler ve istek türleri için ek sınırlamalar ve dikkat edilmesi gereken noktalar aşağıda açıklanmıştır.

Arama istekleri

Bir Search veya SearchStream isteği, kullanıcının günlük işlem kotası için bir işlem olarak sayılır. Bir SearchStream isteği, grup sayısından bağımsız olarak bir API işlemi olarak sayılır.

Sayfalandırılmış istekler

Sayfalandırılmış istekler (ör. geçerli bir next_page_token içeren istekler) kullanıcının günlük işlem kotasına dahil edilmez. Ancak süresi dolmuş veya geçersiz bir sayfa jetonu içeren sayfalama istekleri bir istisna oluşturur ve günlük işlem kotasından düşülür.

Sayfalandırma hakkında daha fazla bilgi için Sonuçlar arasında gezinme başlıklı makaleyi inceleyin.

Diğer istek türleri

Mutate, Search veya SearchStream isteği olmayan bir istek, kullanıcının günlük işlem kotasından bir işlem olarak sayılır.

Bu tür taleplere birkaç örnek:

• BatchJobService.ListBatchJobResults
• ConversionUploadService.UploadCallConversions
• ConversionUploadService.UploadClickConversions
• OfflineUserDataJobService.AddOfflineUserDataJobOperations
• OfflineUserDataJobService.CreateOfflineUserDataJob
• UserDataService.UploadUserData

API istisnaları döndüren istekler

GoogleAdsFailure ile reddedilen istekler, kullanıcının günlük işlem kotasından düşülür.

Başarısız olan ancak ağ düzeyindeki bir hata gibi nedenlerle GoogleAdsFailure döndürmeyen istekler, hizmete ulaşmayacağı için kullanıcının günlük işlem kotasına dahil edilmez. Ağ bağlantısı hatası buna örnek olarak verilebilir.

Anahtar Kelime Planlayıcı hizmeti

Maliyet ve karmaşıklık nedeniyle, aşağıdaki Anahtar Kelime Planlayıcı hizmet yöntemleri diğer istek türlerinden ayrı sınırlara tabidir.

• Müşteri kimliği başına saniyede 1 istekle sınırlıdır:

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

  Bu sınırlamaları ihlal eden istekler şu hatayla reddedilir: RESOURCE_EXHAUSTED.

• 1 QPS, 60 saniyede 60 istek olarak hesaplanır.

• Müşteri kimliği başına saniyede 2 istekle sınırlıdır:

  • KeywordPlanIdeaService.GenerateAdGroupThemes

Anahtar kelime planı oluştururken bu sınırları göz önünde bulundurun.

Kitle analizi hizmeti

AudienceInsightsService içindeki aşağıdaki yöntemler belirli kota sınırlarına tabidir.

• Müşteri kimliği başına günde yaklaşık 200 istekle sınırlıdır:
  • AudienceInsightsService.GenerateAudienceCompositionInsights
  • AudienceInsightsService.GenerateSuggestedTargetingInsights
• Google Cloud projesi başına saniyede 2 istekle sınırlıdır:
  • AudienceInsightsService.GenerateTargetingSuggestionMetrics

Dönüşüm yükleme hizmeti

• İstek başına 2.000 telefon araması veya tıklama dönüşümüyle sınırlıdır:

  • ConversionUploadService.UploadCallConversions
  • ConversionUploadService.UploadClickConversions

  Bu sınırları ihlal eden istekler şu hatayla reddedilir: TOO_MANY_CONVERSIONS_IN_REQUEST.

Dönüşüm ayarlama yükleme hizmeti

• İstek başına 2.000 dönüşüm ayarlamasıyla sınırlıdır:

  • ConversionAdjustmentUploadService.UploadConversionAdjustments

  Bu sınırları ihlal eden istekler şu hatayla reddedilir: TOO_MANY_ADJUSTMENTS_IN_REQUEST.

Dönüşüm değeri kuralları

• Hesap başına 100.000 dönüşüm değeri kuralıyla sınırlıdır.

  Bu sınırı ihlal eden istekler ResourceCountLimitExceededError.ACCOUNT_LIMIT hatasıyla reddedilir.

Hesapta attachment_type değeri CUSTOMER olan bir ConversionValueRuleSet zaten varsa yeni dönüşüm değeri kurallarını etkinleştirmek için bu kuralları ilgili gruba eklemeniz gerekir. Böyle bir dönüşüm değeri kural kümesi yoksa bir kural kümesi oluşturmanız ve dönüşüm değeri kurallarınızı Kural kümeleri oluşturma bölümünde açıklandığı şekilde bu kümeye eklemeniz gerekir.

Faturalandırma ve hesap bütçesi hizmetleri

• Değişiklikler yalnızca aylık faturalandırma için yapılandırılmış hesaplarda yapılabilir.

  Bu sınırlamayı ihlal eden istekler şu hatayla reddedilir: MUTATE_NOT_ALLOWED.

• Değişiklik istekleri için yalnızca 1 işleme izin verilir.

  Bu sınırlamayı ihlal eden istekler şu hatayla reddedilir: TOO_MANY_MUTATE_OPERATIONS.

• Aynı hesapta hesap bütçesi (AccountBudget veya AccountBudgetProposal) değişiklikleri arasında en az 12 saat beklemeniz gerekir. 12 saat geçmeden değişiklik yapılması, yalnızca Google Ads hesap temsilciniz tarafından çözülebilecek, kurtarılamayan hatalara neden olabilir.

Müşteri hesaplarına davetler

Yeni kullanıcılar, CustomerUserAccessInvitationService ile mevcut müşteri hesaplarına davet edilebilir. Bu özellik, diğer kullanıcılara davet e-postaları gönderdiğinden kötüye kullanılma potansiyeline sahiptir. Bu nedenle, davranışıyla ilgili sınırlamalar vardır:

• Kullanıcılar aynı müşteri hesabı için birden fazla bekleyen davet alamaz. Beklemede olan bir davetiyesi bulunan kullanıcıya davetiye göndermek için başka bir istek gönderilirse şu hata döndürülür: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

• Müşteri hesaplarında aynı anda en fazla 70 bekleyen davetiye olabilir. Bu değerin aşılmasına neden olan bir istek gönderilirse şu hata döndürülür: PENDING_INVITATIONS_LIMIT_EXCEEDED.

Kullanıcı verileri

Kullanıcı verileri, UserDataService ve OfflineUserDataJobService ile yönetilir.

Bir create veya remove işlemindeki her UserData nesnesi tek bir son kullanıcıyla ilgilidir. Tek bir UserData nesnesindeki user_identifiers alanı en fazla 20 tanımlayıcıyla sınırlıdır. Tek bir UserData nesnesinde bu sınırın aşılması, OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS veya UserDataError.TOO_MANY_USER_IDENTIFIERS hatasına neden olur.

20'den fazla tanımlayıcısı olan kullanıcıları işleme

Tek bir son kullanıcının yüklemeniz gereken 20'den fazla tanımlayıcısı varsa bu tanımlayıcıları birden fazla UserData nesnesine dağıtmanız gerekir. Google'ın tüm bu tanımlayıcıları aynı son kullanıcıyla ilişkilendirebilmesi için söz konusu kullanıcıya ait her UserData nesnesinin en az bir ortak user_identifier (ör. aynı hashed_email, hashed_phone_number veya third_party_user_id) içermesi gerekir. Google, ayrı UserData işlemlerinden gelen bilgileri doğru son kullanıcı profiline bağlamak ve birleştirmek için bu paylaşılan tanımlayıcıları kullanır.

Karma oluşturma işlemi uygulanmış e-postalar veya telefon numaraları gibi kimliği tanımlayabilecek bilgiler kullanıyorsanız bağlantı hatalarını önlemek için bunların Google Ads API şartlarına göre normalleştirildiğinden ve karma oluşturma işlemi uygulandığından (SHA-256, küçük harf, boşluksuz) emin olun.

Örneğin, bir kullanıcının 30 e-posta adresi varsa ortak bir third_party_user_id paylaşan iki UserData nesnesi gönderebilirsiniz (20 tanımlayıcı sınırını aşmamak için thirdPartyUserId ve 1 ile 19 arasındaki e-postaları ilk nesneye, thirdPartyUserId ve 20 ile 30 arasındaki e-postaları ikinci nesneye yerleştirin):

{
  "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" }
  ]
}

Tek bir AddOfflineUserDataJobOperationsRequest içindeki tüm işlemler genelinde user_identifiers için toplam sınır 100.000'dir (bir OfflineUserDataJob, iş başına önerilen maksimum 1.000.000 işlem olmak üzere birden fazla AddOfflineUserDataJobOperationsRequest çağrısını kabul edebilir). UploadUserDataRequest (UserDataService.UploadUserData) kullanan eşzamanlı yüklemelerde her istek, tüm istek genelinde maksimum 10 işlem ve 100 user_identifiers ile sınırlıdır.

Diğer sınır türleri

İstekte çok fazla öğe içeren yinelenen bir alan (ör. işlem listesi) şu hataya neden olabilir: REQUEST_SIZE_LIMIT_EXCEEDED. Bu hata mesajı, başka sorunlardan da kaynaklanabilir.

Bu sınırlamayla karşılaşırsanız ve yinelenen alan kullanan istekler gönderiyorsanız işlem listesini birden fazla değişiklik isteğine bölerek yinelenen alandaki öğe sayısını azaltmayı deneyin.

GAQL sorgusu yaparken IN yan tümcesindeki maksimum öğe sayısı 20.000'dir. Bu sınırı aşarsanız FILTER_HAS_TOO_MANY_VALUES hatası döndürülür.