Kotalar

Bu belgede, Merchant API için geçerli olan kotalar listelenmiştir.

Merchant API, tüm kullanıcılar için istikrarlı ve adil bir ortam sağlamak amacıyla kotalar kullanır. Kotalar, tek bir API kullanıcısının sisteme aşırı yük bindirmesini önleyerek yüksek performans sağlar. Bu kotaları anlamak, ürün verilerinizi yönetmek ve Google'da işletmenizi büyütmek için çok önemlidir.

Genel kavramlar

Merchant API kotaları, kota grupları aracılığıyla yönetilir.

API yöntemleri, kota gruplarıyla eşlenir. Bu eşlemenin yapısı değişiklik gösterebilir:

• Grup başına tek yöntem: Bazı kota grupları tek bir API yöntemine uygulanır. Örneğin, veri kaynaklarını listeleme yönteminin (accounts.dataSources.list) kendi özel kota grubu vardır.
• Grup başına birden fazla yöntem (paketleme): Genellikle ilgili yöntemler tek bir kota grubunda paketlenir. Bu gruptaki tüm yöntemler aynı günlük ve dakika başına sınırları paylaşır. Yaygın örnekler şunlardır:
  • İlgili yöntemler ve kaynaklar için tüm okuma işlemlerini gruplandırma (ör. merchant-accounts-read-methods).
  • İlgili yöntemler ve kaynaklar için tüm yazma işlemlerini gruplandırma (ör. merchant-accounts-write-methods).

Her yöntem çağrısı, türünden bağımsız olarak bir kez sayılır. 250 öğelik bir list isteği, 250 get isteği olarak değil, yalnızca bir kez sayılır.

Yerleşik HTTP toplu işlemi, kotayı etkilemez. Bir istek grubundaki her bir istek, kotadan bir istek olarak düşülür. Örneğin, 500 insert isteği içeren bir toplu istek, 500 ayrı insert yöntemi isteği olarak ücretlendirilir.

Özel bölge toplu işlemi için istisna: Özel bölge toplu işlem yöntemleri (batchCreate, batchUpdate, batchDelete), yükte bulunan bölge işlemlerinin sayısına bakılmaksızın merchant_regions kota grubu için tek bir API çağrısı olarak sayılır.

Entegrasyonunuzu etkili bir şekilde yönetmek için kullanmayı planladığınız her API yöntemiyle ilişkili belirli kota grubunu incelemeniz gerekir. Bu ayrıntıları kotalar listesi yönteminde bulabilirsiniz. Daha fazla bilgi için İzleme ve Görünürlük başlıklı makaleyi inceleyin.

Politikayı güncelleme

Merchant API, güncellemelerle ilgili olarak aşağıdaki politikaları uygular:

• Varsayılan olarak, ürünlerinizi günde en fazla iki kez güncelleyebilirsiniz. Dakika başına kota kuralına uymak için çağrıları gün içine eşit şekilde dağıtmanız gerekir.
• Varsayılan olarak, alt hesaplarınızı günde en fazla iki kez güncelleyebilirsiniz. Günlük alt hesap güncelleme kotanız, izin verilen toplam alt hesap sayınıza göre belirlenen toplu bir sınırdır.
• Varsayılan olarak, alt hesaplarınız için list veya create gibi veri kaynağı yöntemlerini alt hesap başına günde en fazla iki kez çağırabilirsiniz.

Sıklık kotaları

Her kota grubunun iki tür sınırı (ve günlük kullanımı) vardır:

• Günlük Sınır (quotaLimit): Günlük izin verilen maksimum istek sayısı. Günlük kota sınırları 12:00 UTC'de sıfırlanır.
• Dakika Başına Sınır (quotaMinuteLimit): Dakika başına izin verilen maksimum istek sayısıdır. İsteklerin hızını kontrol eder. Dakika başına kota sınırları, kayan bir pencere kullanır. Yaptırım dönemi, ilgili yöntem ve kaynak için ilk API çağrısının yapıldığı andan itibaren başlar. Örneğin, 10:01:30'da bir çağrı yaparsanız bu yöntemin dakika başına kota aralığı 10:02:30'a kadar devam eder.
• Günlük Kullanım (quotaUsage): Gönderilmiş ve geçerli günün günlük sınırına dahil edilmiş isteklerin sayısı. Alan eksikse bu grup için henüz kota kullanılmamıştır.

Daha önce açıklanan üç alanı (quotaLimit, quotaMinuteLimit ve quotaUsage) quotas.list yönteminin yanıtında bulabilirsiniz.

Günlük ve dakikalık sınırlar, farklı kota grupları arasında önemli ölçüde değişiklik gösterir. Ürün verilerini okuma gibi daha yüksek beklenen hacme veya daha düşük sistem maliyetine sahip işlemler genellikle daha yüksek sınırlara sahiptir. Buna karşılık, hesap değişiklikleri gibi daha yoğun veya hassas işlemlerin sınırları daha düşük olabilir.

Kota tahsisi ve hiyerarşisi

Bu bölümde, Merchant API'nin kota kullanımını kimin adına izlediği ve uyguladığı açıklanmaktadır:

Genel olarak kota, API isteğini yapan kullanıcıya göre ücretlendirilir.

• Bağımsız hesaplar: API çağrısının kimliğini doğrulayan bağımsız hesaplarda, istek ilgili hesabın kotasından düşülür.
  • Örnek: A Ayakkabı Mağazası (Hesap Kimliği: 12345) adlı satıcı, kendi hesabını (accounts/12345) hedefleyen products.insert yöntemini çağırmak için kendi hizmet hesabını kullanarak kimlik doğrulaması yapar. Kota, A Ayakkabı Mağazası'nın kota havuzundan kullanılır.
• Gelişmiş hesaplar: Gelişmiş hesap olarak kimlik doğrulama, alt hesap hedeflenirken bile gelişmiş hesabın havuzundaki kotayı kullanır.
  • Örnek: Bir ajansın Perakende Yönetim Hesabı (Gelişmiş Hesap Kimliği: 12345), Giyim Mağazası B (Hesap Kimliği: 11111) adlı bir alt hesabı yönetiyor. Ajans, kendi kimlik bilgilerini kullanarak kimlik doğrulaması yapar ve Giyim Mağazası B'yi (accounts/11111) hedefleyen products.insert çağrıları yapar. Kota, alt hesabın havuzundan değil, üst ajansın havuzundan (gelişmiş hesap kimliği: 12345) kullanılır.
• Alt hesaplar: API çağrılarının kimliği bir alt hesabın kimlik bilgileri kullanılarak doğrulandığında kota, ilgili alt hesabın bireysel havuzundan düşülür. Bu hesap, üst düzey bir gelişmiş hesap tarafından yönetilse de bağımsız bir hesapla aynı şekilde çalışır.
  • Örnek: Öncekiyle aynı kurulumu kullanarak Giyim Mağazası B (hesap kimliği: 11111), kendi hesabını (accounts/11111) hedefleyen products.insert yöntemini çağırmak için alt hesabına özel olarak ayarlanmış kimlik bilgilerini kullanarak kimlik doğrulaması yaparsa kota, Giyim Mağazası B'nin bireysel kota havuzundan kullanılır ve üst ajansın havuzuna dokunulmaz.

Genel kurallarla ilgili istisnalar

Kota tahsisiyle ilgili genel kurallar için geçerli olan birkaç istisna vardır:

• Accounts.list: Bu yöntemin kotası, Merchant Center hesap kimliğinden değil, çağrıyı yapan kimliği doğrulanmış kullanıcıdan veya hizmet hesabından alınır. Kota kullanımı, standart Merchant Center API Teşhis Aracı sayfasında gösterilmez. Gelişmiş hesabınız varsa gelişmiş hesap kotanızda hesaba katılan accounts.listSubaccounts yöntemini kullanmanızı öneririz.
• Sorun çözme yöntemleri: Bu yöntemler, isteğin kimliğini farklı bir hesap doğruluyor olsa bile her zaman sorunları istenen hesabın kotasından düşer.

Tahsis Hiyerarşisi

• Karşılaştırmalı Alışveriş Hizmetleri (CSS): CSS, ürün tekliflerini toplayan ve kullanıcıları satın alma işlemi yapmaları için perakendecilerin web sitelerine yönlendiren web siteleridir. API çağrıları yapılırken kotalar, kimlik doğrulaması yaptığınız belirli CSS grubuna, CSS alanına, hesaba veya alt hesaba uygulanır.

  Örnekler:

  • Europe Shopping Group (Hesap Kimliği: 10001) adlı bir CSS grubu, ilişkili CSS alanlarını listelemek istiyor. Bu API çağrısını yapmak için kendi kimlik bilgileriyle kimlik doğrulaması yapıldığında kota doğrudan Europe Shopping Group kota havuzundan kullanılır.
  • TopDeals CSS adlı CSS alanının (hesap kimliği: 20002), etiket atamak için ilişkili satıcı hesaplarından birini (accounts/30003) hedefleyen bir yöntemi çağırmak üzere kimlik doğrulaması yaptığını varsayalım. Kota, satıcı hesabının havuzundan değil, TopDeals CSS'nin kota havuzundan kullanılır.

• Pazar yerleri: Pazar yerleri, birden fazla satıcıyı barındıran online platformlardır. Bu hesaplar, her satıcınız için ayrı alt hesaplar oluşturmanıza olanak tanıyan özel gelişmiş hesaplar olarak işlev görür.

Aşağıdaki şemada CSS grupları, CSS, pazar yerleri, gelişmiş hesaplar, bağımsız hesaplar ve alt hesapların hiyerarşisi gösterilmektedir.

Otomatik Kota Ayarlaması

Merchant API, belirli hizmetler için otomatik kota yönetim sistemine sahiptir. Bu sistem, büyüyen satıcıların kota sınırlarını kullanım, teklif ve hesap boyutuna göre ayarlar. Merchant API, bu kotaları her gün yeniden hesaplar.

Otomatik kota ayarlamalarına dahil edilen kota grupları şunlardır:

Ürün hizmetleri

• products ve productInputs kaynaklarıyla ilgili yöntemlerin tüm kota grupları.
• Günlük çağrı kotası genellikle satıcının sahip olduğu teklif kotası sayısının 2 katı olarak ayarlanır. Bu, bir satıcının ürünlerinin her birini günde iki kez güncellemesi gerekebileceğini varsayar.
• Tek tek ürünler ikiden fazla kez güncellenebilir ancak toplam günlük API çağrılarınız, toplam günlük çağrı kotasını aşamaz.

Hesap hizmetleri

• Merchant API'deki hesapla ilgili çeşitli ayrıntılı kaynaklarla ilgili yöntemlerin tüm kota grupları.
• Günlük çağrı kotası, ilgili hesap için izin verilen maksimum alt hesap sayısına ayarlanır. Bu sayede, alt hesap başına günde en fazla iki okuma çağrısı yapılabilir.

Veri kaynağı hizmetleri

• Gelişmiş bir hesabın alt hesaplarında gerçekleştirdiği, Merchant API'deki veri kaynağıyla ilgili kaynaklarla (ör. list veya create) ilgili yöntemlerin tüm kota grupları.
• Günlük çağrı kotası genellikle gelişmiş hesabın sahip olduğu alt hesap sayısının 2 katı olarak ayarlanır. Bu, bir satıcının alt hesaplarının veri kaynaklarının her birini günde en fazla iki kez güncelleyebileceğini varsayar.

Yalnızca daha önce açıklanan hizmetlerde otomatik kota ayarlamaları yapılır. Diğer hizmetlerin varsayılan bir kotası vardır ve artışların manuel olarak istenmesi gerekir. Daha fazla bilgi için Kota artırma süreci bölümüne bakın.

Kotalar aşıldığında ne olur?

Kota aşıldıktan sonra API yanıtlarında ve Merchant Center hesabınızdaki Teşhis sayfasında hatalar gösterilir:

• Dakika başına: quota/request_rate_too_high

{
    "error": {
        "code": 429,
        "message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
                }
            }
        ]
    }
}

• Günlük: quota/daily_limit_exceeded

{
    "error": {
        "code": 429,
        "message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_TOO_MANY_REQUESTS"
                }
            }
        ]
    }
}

Aşağıdaki hatalar Merchant Center sınırlarıdır ve Merchant API kotalarıyla ilgili değildir. Öğeler, feed'ler veya alt hesaplar için ek kota isteğinde bulunmayı deneyebilirsiniz:

• too_many_items: Satıcı kotası aşıldı
• too_many_subaccounts: Maksimum alt hesap sayısına ulaşıldı

İzleme ve görünürlük

Bir hesabın mevcut çağrı kotalarını ve kullanımını kontrol etmek için hesabın adıyla quotas.list yöntemini çağırın.

POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

Aşağıdakini değiştirin:

• ACCOUNT_ID: Merchant Center kimliğiniz
• ACCESS_TOKEN: API çağrısı yapmak için yetkilendirme jetonu

İstek başarılı olursa API, kota grubunun name kaynağını, farklı kotaları ve grup kotasının geçerli olduğu yöntemleri içeren quotaGroups kaynaklarının listesini döndürür.

{
    "quotaGroups": [
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
            "quotaUsage": "2",
            "quotaLimit": "1000",
            "methodDetails": [
                {
                    "method": "quotaservice.listquotagroups",
                    "version": "v1",
                    "subapi": "quota",
                    "path": "quota/v1/quotaservice.listquotagroups"
                }
            ],
            "quotaMinuteLimit": "10"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
            "quotaLimit": "10000",
            "methodDetails": [
                {
                    "method": "commissiongroupservice.listcommissiongroups",
                    "version": "v1",
                    "subapi": "youtube",
                    "path": "youtube/v1/commissiongroupservice.listcommissiongroups"
                }
            ],
            "quotaMinuteLimit": "60"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
            "quotaLimit": "20000000",
            "methodDetails": [
                {
                    "method": "merchantreviewsservice.listmerchantreviews",
                    "version": "v1",
                    "subapi": "reviews",
                    "path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
                }
            ],
            "quotaMinuteLimit": "60000"
        }
    ]
}

Kota artışı süreci

Ek kota istemek için Destek ekibiyle iletişime geçme formunu açın, zorunlu "Sorun/Soru nedir?" alanında Kota artırma isteği'ni seçin ve Merchant Center kimliğiniz, hedef yöntemleriniz ve işletme gerekçeniz dahil olmak üzere tüm zorunlu alanları doldurun.

• Otomatik kotaları olan kaynaklar için (products, accounts ve gelişmiş hesaplar için datasources): Yalnızca yeni bir pazarda lansman yapma veya trafiğin yoğun olduğu alışveriş sezonları gibi özel senaryolar için geçici bir artış isteğinde bulunabilirsiniz. Bu tür kaynaklar için kalıcı kota artışlarını kabul etmiyoruz.
• Otomatik kotası olmayan diğer tüm kaynaklar için: Gerektiğinde kota artışı isteyin.

Uygulamanız için yeterli kotanız olduğundan emin olmak ve kotanızın otomatik olarak nasıl ayarlandığını görmek için kotalarınızı düzenli olarak kontrol etmenizi öneririz. Her bir API yöntemi grubu için mevcut günlük kota sınırınızı, dakika sınırınızı ve mevcut günlük kullanımınızı görmek üzere quotas.list yöntemini kullanın.

En İyi Uygulamalar

Bu en iyi uygulamaları hayata geçirmek, entegrasyonunuzun sorunsuz çalışmasını sağlar, beklenmedik kota hatalarını önler ve Merchant Center kaynaklarını verimli bir şekilde kullanır.

İstek Dağıtımını Optimize Etme

• İstekleri eşit şekilde dağıtın: Çok sayıda isteği aynı anda göndermekten kaçının. Dakika başına kota sınırları (quotaMinuteLimit) içinde kalmak için günlük API çağrılarınızı gün boyunca eşit şekilde dağıtın.
• Proaktif kısıtlama: Uygulamanızda istemci tarafı sıklık sınırlaması (kısıtlama) uygulayın. Fazla trafiği reddetmek için yalnızca Google'ın sunucularına güvenmeyin. İstek hızınızı kaynakta kontrol edin.

Hataları Sorunsuz Yönetme

• HTTP 429'u işleme: Uygulamanız, 429 Çok Fazla İstek hatasını (quota/request_rate_too_high) işleyecek şekilde hazırlanmalıdır.
• Dalgalanma ile eksponansiyel geri yükleme: Başarısız istekleri yeniden denerken (özellikle 429 hatasından sonra) eksponansiyel geri yükleme (bekleme sürelerini artırma) kullanın ve "dalgalanma" (rastgele gecikme) ekleyin. Jitter, birden fazla istemci örneğinin aynı anda yeniden deneme yaparak sunucuyu tekrar aşırı yüklediği "yeniden deneme fırtınalarını" önler.
• Yeniden deneme ipuçlarına uyun: API yanıtı, yeniden deneme ayrıntıları veya üstbilgiler içeriyorsa çağrıların ne zaman devam ettirileceğini belirlemek için bunları kullanın.

Gereksiz çağrıları en aza indirme

• Eski çağrıları önleme (404 NOT_FOUND): Artık mevcut olmayan kaynakları istemekten veya silmekten kaçının. Başarısız çağrılar bile API kotasını tüketir. Eski durum izleme veya gereksiz yoklama işlemlerini tespit etmek için Merchant Center API Teşhis Aracı'ndaki NOT_FOUND hatalarını izleyin.
• Güncellemeden önce doğrulayın: Güncelleme isteği göndermeden önce verilerin gerçekten değişip değişmediğini kontrol edin. Aynı değerleri yazan güncellemeler göndermekten kaçının.
• Önbelleğe alma özelliğini kullanın: Değişmeyen veriler için tekrarlanan get veya list çağrılarından kaçınmak amacıyla, uygun olduğunda okuma yanıtlarını (ör. ürün ayrıntıları, ayarlar) yerel olarak önbelleğe alın.

Kota hiyerarşisi ve istisnalar arasında gezinme

• Gelişmiş hesaplar ve alt hesaplar: Gelişmiş hesap kullanıyorsanız ve çağrıların gelişmiş hesapların paylaşılan havuzuna sayılmasını istiyorsanız gelişmiş hesap düzeyinde kimlik doğrulaması yapın.
• listSubaccounts kullanın: Gelişmiş hesaplar için accounts.list yerine accounts.listSubaccounts kullanın. accounts.list kotası, çağrıyı yapan kullanıcıdan (MC kimliğinden değil) alınır ve standart teşhislerde görünmez. listSubaccounts, çok müşterili hesap kotanızdan düşülür.