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, bilmeniz gereken bazı önemli sınırlar ve kotalar özetlenmektedir.

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

Günlük API kullanım sınırları, Google Cloud projenizin yaptığı API işlemlerinin sayısına göre belirlenir. API işlemleri, Search ve SearchStream isteklerinin, tek tek değiştirme işlemlerinin ve diğer hizmet isteklerinin toplamıdır. Günlük API işlemleriyle ilgili 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ılavuzunda, her erişim düzeyi için geçerli olan belirli API işlemi sınırları açıklanmaktadır.

Bu sınırları ihlal eden istekler, RESOURCE_EXHAUSTED hatasıyla reddedilir.

gRPC sınırlamaları

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

Yanıtlarda bu sınır aşılmamalı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ış kullanabilirsiniz. Değişiklikler için istek başına daha az işlem gönderin.

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

Değişiklik istekleri

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

Belirli hizmetler ve istek türleriyle ilgili ek sınırlar ve dikkat edilmesi gereken noktalar aşağıda açıklanmıştır.

Arama istekleri

Search veya SearchStream isteği, kullanıcının günlük işlem kotası kapsamında tek bir işlem olarak sayılır. Toplu işlem sayısından bağımsız olarak bir SearchStream isteği, bir API işlemi olarak kabul edilir.

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ına dahil edilir.

Sayfalara ayı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ı kapsamında bir işlem olarak sayılır.

Bu tür isteklere 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ına dahil edilmeye devam eder.

Başarısız olan ancak GoogleAdsFailure döndürmeyen istekler (ör. ağ düzeyindeki bir hatadan kaynaklananlar) hizmete hiçbir zaman ulaşmayacağından kullanıcının günlük işlem kotasına dahil edilmez. Buna örnek olarak ağ bağlantısı hatası verilebilir.

Anahtar kelime planlama hizmeti

Maliyet ve karmaşıklık nedeniyle, aşağıdaki anahtar kelime planlama hizmeti yöntemleri diğer istek türlerinden ayrı sınırlara tabidir.

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

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

  Bu sınırlamaları ihlal eden istekler, RESOURCE_EXHAUSTED hatasıyla reddedilir.

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

• CID başına saniyede 2 istek ile 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 kapsamındaki aşağıdaki yöntemler belirli kota sınırlarına tabidir.

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

Dönüşüm yükleme hizmeti

• İstek başına 2.000 çağrı 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, TOO_MANY_ADJUSTMENTS_IN_REQUEST hatasıyla reddedilir.

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.

Hesap için CUSTOMER attachment_type'lü bir ConversionValueRuleSet zaten varsa yeni dönüşüm değeri kurallarının etkinleştirilmesi için bu kümeye eklenmesi gerekir. Böyle bir dönüşüm değeri kuralı grubu yoksa Kural grupları oluşturma bölümünde açıklandığı gibi bir kural grubu oluşturmanız ve dönüşüm değeri kurallarınızı bu gruba 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ştirme 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ılamaz 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ği için kötüye kullanılma ihtimali vardır. Bu nedenle, özelliğin davranışıyla ilgili sınırlamalar vardır:

• Kullanıcılar, aynı müşteri hesabı için birden fazla bekleyen davet alamaz. Beklemede davetiyesi olan bir kullanıcıya davetiye göndermek için sonraki bir istekte bulunulursa ş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.

create veya remove işlemindeki her UserData nesnesi tek bir son kullanıcıya aittir. 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ıyla sonuçlanır.

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 bu kullanıcıya ait her UserData nesnesi en az bir ortak user_identifier içermelidir. Örneğin, aynı hashed_email, hashed_phone_number veya third_party_user_id. Google, ayrı UserData işlemlerindeki bilgileri doğru son kullanıcı profiliyle 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 bilgilerden (PII) yararlanıyorsanız bağlantı hatalarını önlemek için bu bilgilerin Google Ads API şartlarına (SHA-256, küçük harf, boşluk yok) göre normalleştirildiğinden ve karma oluşturma işlemi uygulandığından emin olun.

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

{
  "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 için user_identifiers'nın 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ı kabul edebilir). UploadUserDataRequest (UserDataService.UploadUserData) kullanılarak yapılan senkron yüklemelerde her istek, en fazla 10 işlem ve 100 user_identifiers ile sınırlıdır.

Diğer sınır türleri

Bir istekte çok fazla öğe içeren işlemler listesi gibi yinelenen bir alan şu hataya neden olabilir: REQUEST_SIZE_LIMIT_EXCEEDED. Aynı hata mesajı başka sorunlardan da kaynaklanabilir.

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

GAQL sorgusu oluştururken IN ifadesindeki 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.