Kuota

Dokumen ini mencantumkan kuota yang berlaku untuk Merchant API.

Merchant API menggunakan kuota untuk membantu memastikan lingkungan yang stabil dan adil bagi semua pengguna. Kuota mencegah satu pengguna API membebani sistem secara berlebihan, sehingga memastikan performa tinggi. Pemahaman terhadap kuota ini menjadi kunci untuk mengelola data produk dan menskalakan bisnis di Google.

Konsep umum

Kuota Merchant API dikelola melalui grup kuota.

Metode API dipetakan ke grup kuota. Struktur pemetaan ini dapat bervariasi:

  • Satu metode per grup: Beberapa grup kuota berlaku untuk satu metode API. Misalnya, metode sumber data listingan accounts.dataSources.list memiliki grup kuota khusus.
  • Beberapa metode per grup (penggabungan): Sering kali, metode terkait digabungkan menjadi satu grup kuota. Semua metode dalam grup tersebut memiliki batas harian dan per menit yang sama. Contoh umum meliputi:
    • Mengelompokkan semua operasi baca untuk metode dan resource terkait, seperti merchant-accounts-read-methods.
    • Mengelompokkan semua operasi tulis untuk metode dan resource terkait, seperti merchant-accounts-write-methods.

Setiap panggilan metode dihitung satu kali, terlepas dari jenisnya. Permintaan list sebanyak 250 item hanya dihitung satu kali, bukan sebagai 250 permintaan get.

Batch HTTP bawaan tidak memengaruhi kuota. Setiap permintaan tunggal dalam batch permintaan dihitung sebagai satu permintaan terhadap kuota. Misalnya, permintaan batch yang berisi 500 permintaan insert akan ditagih sebagai 500 permintaan metode insert individual.

Pengecualian untuk batching region khusus: Metode batch region khusus (batchCreate, batchUpdate, batchDelete) dihitung sebagai satu panggilan API terhadap grup kuota merchant_regions, terlepas dari jumlah operasi region yang ada dalam payload.

Untuk mengelola integrasi secara efektif, Anda harus meninjau grup kuota tertentu yang terkait dengan setiap metode API yang ingin Anda gunakan. Anda dapat menemukan detail ini dalam metode daftar kuota. Untuk mengetahui informasi selengkapnya, lihat Pemantauan dan Visibilitas.

Kebijakan update

Merchant API menerapkan kebijakan berikut terkait pembaruan:

  • Secara default, Anda dapat memperbarui produk hingga dua kali per hari. Anda harus menyebarkan panggilan secara merata sepanjang hari untuk mematuhi kuota per menit.
  • Secara default, Anda hanya dapat memperbarui sub-akun hingga dua kali per hari. Kuota update sub-akun harian Anda adalah batas gabungan berdasarkan total sub-akun yang diizinkan.
  • Secara default, Anda hanya dapat memanggil metode sumber data untuk sub-akun seperti list atau create hingga dua kali per sub-akun per hari.

Kuota kapasitas

Setiap grup kuota memiliki dua jenis batas (dan penggunaan harian):

  • Batas Harian (quotaLimit): Jumlah maksimum permintaan yang diizinkan per hari. Batas kuota harian direset pada 12.00 siang UTC.
  • Batas Per Menit (quotaMinuteLimit): Jumlah maksimum permintaan yang diizinkan per menit, yang mengontrol kecepatan permintaan. Kuota per menit membatasi penggunaan jendela geser, dengan periode penegakan dimulai dari saat panggilan API pertama untuk metode dan resource tersebut dilakukan. Misalnya, jika Anda melakukan panggilan pada 10.01.30 AM, periode kuota per menit untuk metode tersebut akan berjalan hingga 10.02.30 AM.
  • Penggunaan Harian (quotaUsage): Jumlah permintaan yang telah dibuat dan dihitung terhadap batas harian untuk hari ini. Jika kolom tidak ada, berarti belum ada kuota yang digunakan untuk grup ini.

Anda dapat menemukan tiga kolom yang dijelaskan sebelumnya (quotaLimit, quotaMinuteLimit, dan quotaUsage) dalam respons metode quotas.list.

Batas harian dan per menit tertentu sangat bervariasi di antara berbagai grup kuota. Operasi dengan volume yang diharapkan lebih tinggi atau biaya sistem yang lebih rendah, seperti membaca data produk, biasanya memiliki batas yang lebih tinggi. Sebaliknya, operasi yang lebih intensif atau sensitif, seperti modifikasi akun, mungkin memiliki batas yang lebih rendah.

Alokasi dan hierarki kuota

Bagian ini menjelaskan atas nama siapa Merchant API melacak dan menerapkan penggunaan kuota:

Secara umum, kuota ditagih berdasarkan pengguna yang membuat permintaan API.

  • Akun mandiri: Untuk akun mandiri yang mengautentikasi panggilan API, permintaan tersebut akan mengurangi kuota akun tersebut.
    • Contoh: Penjual Shoe Store A (ID Akun: 12345) melakukan autentikasi menggunakan akun layanannya sendiri untuk memanggil products.insert yang menargetkan akunnya sendiri (accounts/12345). Kuota yang digunakan berasal dari kumpulan kuota Shoe Store A.
  • Akun tingkat lanjut: Melakukan autentikasi sebagai akun tingkat lanjut menggunakan kuota dari kumpulan akun tingkat lanjut, meskipun saat menargetkan sub-akun.
    • Contoh: Agensi dengan Akun Pengelola Retail (ID Akun Lanjutan: 12345) mengelola sub-akun Toko Pakaian B (ID Akun: 11111). Agensi melakukan autentikasi menggunakan kredensialnya sendiri dan memanggil products.insert penargetan Toko Pakaian B (accounts/11111). Kuota diambil dari kumpulan agensi induk (ID Akun Lanjutan: 12345), bukan dari kumpulan sub-akun.
  • Sub-akun: Saat panggilan API diautentikasi menggunakan kredensial sub-akun, kuota akan ditagih ke kumpulan individual sub-akun tersebut. Akun ini berfungsi sama seperti akun mandiri, meskipun dikelola oleh akun tingkat lanjut induk.
    • Contoh: Dengan penyiapan yang sama seperti sebelumnya, jika Toko Pakaian B (ID Akun: 11111) melakukan autentikasi menggunakan kredensial yang disiapkan khusus untuk sub-akunnya guna memanggil products.insert yang menargetkan akunnya sendiri (accounts/11111), kuota akan digunakan dari kumpulan kuota individual Toko Pakaian B, sehingga kumpulan kuota agensi induk tidak terpengaruh.

Pengecualian terhadap aturan umum

Ada beberapa pengecualian khusus yang berlaku untuk aturan umum alokasi kuota:

  • Accounts.list: Kuota untuk metode ini ditagih kepada pengguna yang diautentikasi atau akun layanan yang melakukan panggilan, bukan ID akun Merchant Center. Penggunaan kuotanya tidak akan terlihat di halaman diagnostik Merchant Center API standar. Jika Anda memiliki akun tingkat lanjut, sebaiknya gunakan metode accounts.listSubaccounts, yang dihitung dalam kuota akun tingkat lanjut Anda.
  • Metode penyelesaian masalah: Metode ini selalu mengurangi kuota untuk akun yang masalahnya diminta, meskipun akun lain mengautentikasi permintaan.

Hierarki Alokasi

  • Layanan Perbandingan Belanja (CSS): CSS adalah situs yang mengagregasi penawaran produk dan mengarahkan pengguna ke situs retailer untuk melakukan pembelian. Saat melakukan panggilan API, kuota diterapkan ke kelompok CSS, domain CSS, akun, atau sub-akun tertentu yang Anda autentikasi.

    Contoh:

    • Grup CSS bernama Europe Shopping Group (ID Akun: 10001) ingin mencantumkan domain CSS terkaitnya. Dengan melakukan autentikasi menggunakan kredensialnya sendiri untuk melakukan panggilan API ini, kuota akan digunakan langsung dari kumpulan kuota Grup Shopping Eropa.
    • Domain CSS TopDeals CSS (ID Akun: 20002) melakukan autentikasi untuk memanggil metode yang menargetkan salah satu akun penjual terkaitnya (accounts/30003) untuk menetapkan label. Kuota ini digunakan dari kumpulan kuota CSS TopDeals, bukan kumpulan kuota akun penjual.

  • Marketplace: Marketplace adalah platform online yang menghosting beberapa penjual individu. Akun ini berfungsi sebagai akun tingkat lanjut khusus yang memungkinkan Anda membuat sub-akun individual untuk setiap penjual.

Diagram berikut menunjukkan hierarki grup CSS, CSS, Marketplace, akun lanjutan, akun mandiri, dan sub-akun.

Kelompok CSS adalah tingkat autentikasi menyeluruh, dengan kemungkinan CSS individual di dalamnya, akun dalam CSS tersebut, dan sub-akun sebagai tingkat paling individual.

Penyesuaian Kuota Otomatis

Merchant API memiliki sistem pengelolaan kuota otomatis untuk layanan tertentu, yang menyesuaikan batas kuota untuk penjual yang berkembang berdasarkan penggunaan, penawaran, dan ukuran akun Anda. Merchant API menghitung ulang kuota ini setiap hari.

Grup kuota yang disertakan dalam penyesuaian kuota otomatis adalah:

Layanan produk

  • Semua grup kuota metode yang terkait dengan resource products dan productInputs.
  • Kuota panggilan harian umumnya ditetapkan 2 kali lipat jumlah kuota penawaran yang dimiliki penjual. Hal ini mengasumsikan bahwa penjual mungkin perlu memperbarui setiap produknya hingga dua kali per hari.
  • Produk individual dapat diupdate lebih dari dua kali, tetapi panggilan API harian secara keseluruhan tidak boleh melebihi kuota panggilan harian gabungan.

Layanan akun

  • Semua grup kuota metode yang terkait dengan berbagai resource terkait akun terperinci di Merchant API.
  • Kuota panggilan harian ditetapkan ke jumlah maksimum sub-akun yang diizinkan untuk akun tersebut. Hal ini memungkinkan hingga dua kali panggilan baca per sub-akun per hari.

Layanan sumber data

  • Semua grup kuota metode yang terkait dengan sumber data terkait resource di Merchant API seperti list atau create yang dilakukan akun tingkat lanjut pada sub-akunnya.
  • Kuota panggilan harian umumnya ditetapkan menjadi 2 kali jumlah sub-akun yang dimiliki akun tingkat lanjut. Hal ini mengasumsikan bahwa penjual dapat memperbarui sumber data setiap sub-akunnya hingga dua kali per hari.

Hanya layanan yang dijelaskan sebelumnya yang memiliki penyesuaian kuota otomatis. Layanan lain memiliki kuota default, dan setiap penambahan harus diminta secara manual. Untuk mengetahui informasi selengkapnya, lihat bagian Proses penambahan kuota.

Yang terjadi jika kuota terlampaui

Setelah kuota terlampaui, error akan muncul dalam respons API dan di halaman diagnostik dalam akun Merchant Center Anda:

  • Per menit: 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"
                }
            }
        ]
    }
}
  • Per hari: 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"
                }
            }
        ]
    }
}

Error berikut adalah batas Merchant Center, dan tidak terkait dengan kuota Merchant API. Anda dapat mencoba meminta kuota tambahan untuk item, feed, atau sub-akun:

  • too_many_items: Kuota penjual terlampaui
  • too_many_subaccounts: Jumlah maksimum sub-akun tercapai

Pemantauan dan visibilitas

Untuk memeriksa kuota dan penggunaan panggilan saat ini untuk akun, panggil quotas.list dengan nama akun.

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

Ganti kode berikut:

  • ACCOUNT_ID: ID Merchant Center Anda
  • ACCESS_TOKEN: token otorisasi untuk melakukan panggilan API

Setelah permintaan berhasil, API akan menampilkan daftar resource quotaGroups yang berisi resource name grup kuota, berbagai kuota, dan metode yang berlaku untuk kuota grup.

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

Proses penambahan kuota

Untuk meminta kuota tambahan, buka Formulir kontak dukungan, pilih Permintaan penambahan kuota untuk kolom "Apa Masalah/Pertanyaannya" yang diperlukan, dan isi semua kolom yang wajib diisi, termasuk ID Merchant Center, metode target, dan justifikasi bisnis Anda.

  • Untuk resource dengan kuota otomatis (products, accounts, dan datasources untuk akun lanjutan): Anda hanya dapat meminta peningkatan sementara untuk skenario khusus seperti peluncuran di pasar baru atau selama musim belanja dengan traffic tinggi. Kami tidak menerima peningkatan kuota permanen untuk jenis resource ini.
  • Untuk semua resource lainnya tanpa kuota otomatis: Minta peningkatan kuota sesuai kebutuhan.

Sebaiknya periksa kuota Anda secara berkala untuk memastikan Anda memiliki kuota yang cukup untuk penerapan Anda, dan lihat cara kuota Anda disesuaikan secara otomatis. Gunakan metode quotas.list untuk melihat batas kuota harian saat ini, batas per menit, dan penggunaan harian saat ini untuk setiap grup metode API.

Praktik Terbaik

Menerapkan praktik terbaik ini akan membantu memastikan integrasi Anda berjalan lancar, menghindari error kuota yang tidak terduga, dan memanfaatkan resource Merchant Center secara efisien.

Mengoptimalkan Distribusi Permintaan

  • Sebarkan Permintaan Secara Merata: Hindari mengirimkan permintaan dalam jumlah besar secara tiba-tiba. Sebarkan panggilan API harian Anda secara merata sepanjang hari agar tetap berada dalam batas kuota per menit (quotaMinuteLimit).
  • Throttling Proaktif: Terapkan pembatasan kapasitas (throttling) sisi klien di aplikasi Anda. Jangan hanya mengandalkan server Google untuk menolak traffic berlebih. Kontrol rasio permintaan Anda di sumber.

Penanganan Error yang Baik

  • Tangani HTTP 429: Aplikasi Anda harus siap menangani error 429 Too Many Requests (quota/request_rate_too_high).
  • Backoff Eksponensial dengan Jitter: Saat mencoba ulang permintaan yang gagal (terutama setelah 429), gunakan backoff eksponensial (waktu tunggu yang meningkat) dan tambahkan "jitter" (penundaan acak). Jitter mencegah "badai percobaan ulang", saat beberapa instance klien mencoba lagi pada waktu yang sama persis, sehingga membebani server lagi.
  • Mematuhi Petunjuk Coba Lagi: Jika respons API berisi detail atau header coba lagi, gunakan untuk menentukan kapan harus melanjutkan panggilan.

Meminimalkan Panggilan yang Berlebihan

  • Mencegah Panggilan Usang (404 NOT_FOUND): Hindari permintaan atau penghapusan resource yang tidak ada lagi. Bahkan panggilan yang gagal akan menggunakan kuota API. Pantau error NOT_FOUND di Diagnostik API Merchant Center untuk mendeteksi pelacakan status yang tidak aktif atau polling yang tidak perlu.
  • Verifikasi Sebelum Update: Sebelum mengirim permintaan update, periksa apakah data benar-benar telah berubah. Hindari mengirim update yang menulis nilai yang sama.
  • Gunakan Caching: Cache respons baca (misalnya, detail produk, setelan) secara lokal jika sesuai untuk menghindari panggilan get atau list yang berulang untuk data yang tidak berubah.
  • Akun dan Sub-akun Tingkat Lanjut: Jika Anda adalah akun tingkat lanjut, lakukan autentikasi di tingkat akun tingkat lanjut jika Anda ingin panggilan dihitung terhadap kumpulan bersama akun tingkat lanjut.
  • Gunakan listSubaccounts: Untuk akun tingkat lanjut, gunakan accounts.listSubaccounts, bukan accounts.list. Kuota accounts.list ditagih kepada pengguna yang memanggil (bukan ID MC) dan tidak terlihat dalam diagnostik standar. listSubaccounts dihitung dalam kuota MCA Anda.
Sebelumnya
Overview
Berikutnya
Merchant Center limits