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 memberikan beban yang berlebihan pada sistem, 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): Metode terkait sering 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 untuk 250 item hanya dihitung satu kali, bukan sebagai 250 permintaan get.

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

Pengecualian untuk batching wilayah khusus: Metode batch wilayah khusus (batchCreate, batchUpdate, batchDelete) dihitung sebagai satu panggilan API terhadap grup kuota merchant_regions, terlepas dari jumlah operasi wilayah yang terdapat 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 pembaruan

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 agar mematuhi kuota per menit.
  • Secara default, Anda hanya dapat memperbarui sub-akun hingga dua kali per hari. Kuota pembaruan 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. Batas kuota per menit menggunakan jendela bergulir, dengan periode penerapan dimulai dari saat panggilan API pertama untuk metode dan resource tersebut dilakukan. Misalnya, jika Anda melakukan panggilan pada 10.01.30, jendela kuota per menit untuk metode tersebut akan berjalan hingga 10.02.30.
  • Penggunaan Harian (quotaUsage): Jumlah permintaan yang telah dibuat dan dihitung terhadap batas harian untuk hari ini. Jika kolom ini 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 antara grup kuota yang berbeda. 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 dihitung terhadap kuota akun tersebut.
    • Contoh: Penjual Toko Sepatu A (ID Akun: 12345) melakukan autentikasi menggunakan akun layanannya sendiri untuk memanggil products.insert yang menargetkan akunnya sendiri (accounts/12345). Kuota digunakan dari kumpulan kuota Toko Sepatu A.
  • Akun tingkat lanjut: Melakukan autentikasi sebagai akun tingkat lanjut akan menggunakan kuota dari kumpulan akun tingkat lanjut, meskipun saat menargetkan sub-akun.
    • Contoh: Agensi Akun Pengelolaan Retail (ID Akun Tingkat Lanjut: 12345) mengelola sub-akun Toko Pakaian B (ID Akun: 11111). Agensi melakukan autentikasi menggunakan kredensialnya sendiri dan memanggil products.insert yang menargetkan Toko Pakaian B (accounts/11111). Kuota digunakan dari kumpulan agensi induk (ID Akun Tingkat Lanjut: 12345), bukan kumpulan sub-akun.
  • Sub-akun: Saat panggilan API diautentikasi menggunakan kredensial sub-akun, kuota akan ditagih ke kumpulan individual sub-akun tersebut. Hal ini beroperasi dengan cara yang sama seperti akun mandiri, meskipun dikelola oleh akun tingkat lanjut induk.
    • Contoh: Menggunakan penyiapan yang sama seperti sebelumnya, jika Toko Pakaian B (ID Akun: 11111) melakukan autentikasi menggunakan kredensial yang disiapkan khusus untuk sub-akunnya untuk memanggil products.insert yang menargetkan akunnya sendiri (accounts/11111), kuota akan digunakan dari kumpulan kuota individual Toko Pakaian B sehingga kumpulan agensi induk tidak terpengaruh.

Pengecualian untuk aturan umum

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

  • Accounts.list: Kuota untuk metode ini ditagih terhadap pengguna atau akun layanan yang diautentikasi 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 terhadap kuota akun tingkat lanjut Anda.
  • Metode Issueresolution: Metode ini selalu dihitung terhadap kuota untuk akun yang masalahnya diminta, meskipun akun lain mengautentikasi permintaan tersebut.

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 terkait. Dengan melakukan autentikasi menggunakan kredensialnya sendiri untuk melakukan panggilan API ini, kuota akan digunakan langsung dari kumpulan kuota Europe Shopping Group.
    • Domain CSS TopDeals CSS (ID Akun: 20002) melakukan autentikasi untuk memanggil metode yang menargetkan salah satu akun penjual terkait (accounts/30003) untuk menetapkan label. Kuota digunakan dari TopDeals CSS kumpulan kuota, bukan kumpulan akun penjual.

  • Marketplace: Marketplace adalah platform online yang menghosting beberapa penjual individu. Marketplace 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 tingkat lanjut, akun mandiri, dan sub-akun.

Kelompok CSS adalah tingkat autentikasi menyeluruh, dengan kemungkinan CSS individual di dalamnya, akun di dalamnya, 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 jumlah kuota penawaran yang dimiliki penjual. Hal ini mengasumsikan bahwa penjual mungkin perlu memperbarui setiap produknya hingga dua kali per hari.
  • Produk individual dapat diperbarui lebih dari dua kali, tetapi panggilan API harian Anda 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 resource terkait sumber data di Merchant API, seperti list atau create, yang dilakukan akun tingkat lanjut pada sub-akunnya.
  • Kuota panggilan harian umumnya ditetapkan 2 kali jumlah sub-akun yang dimiliki akun tingkat lanjut. Hal ini mengasumsikan bahwa penjual dapat memperbarui setiap sumber data sub-akunnya hingga dua kali per hari.

Hanya layanan yang dijelaskan sebelumnya yang memiliki penyesuaian kuota otomatis. Layanan lain memiliki kuota default, dan 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 me minta 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 quotaGroups resource yang berisi resource name grup kuota, berbagai kuota, dan metode yang diterapkan 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 Hubungi dukungan, pilih Permintaan penambahan kuota untuk kolom "Apa Masalah/Pertanyaan" yang wajib diisi, dan isi semua kolom yang wajib diisi, termasuk ID Merchant Center, metode target, dan justifikasi bisnis.

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

Sebaiknya periksa kuota Anda secara berkala untuk memastikan Anda memiliki kuota yang cukup untuk penerapan, dan lihat cara kuota Anda disesuaikan secara otomatis. Gunakan metode quotas.list untuk melihat batas kuota harian, 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 menggunakan 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).
  • Pembatasan Proaktif: Terapkan pembatasan kapasitas sisi klien (pembatasan) di aplikasi Anda. Jangan hanya mengandalkan server Google untuk menolak traffic berlebih. Kontrol kecepatan permintaan Anda di sumber.

Penanganan Error yang Baik

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

Meminimalkan Panggilan yang Berlebihan

  • Cegah Panggilan yang Tidak Valid (404 NOT_FOUND): Hindari meminta atau menghapus resource yang tidak ada lagi. Bahkan panggilan yang gagal akan menggunakan kuota API. Pantau error NOT_FOUND di Diagnostik Merchant Center API untuk mendeteksi pelacakan status yang tidak valid atau polling yang tidak perlu.
  • Verifikasi Sebelum Pembaruan: Sebelum mengirim permintaan pembaruan, periksa apakah data benar-benar telah berubah. Hindari mengirim pembaruan yang menulis nilai yang sama.
  • Gunakan Caching: Cache respons baca (misalnya, detail produk, setelan) secara lokal jika sesuai untuk menghindari panggilan get atau list berulang untuk data yang tidak berubah.
  • Akun Tingkat Lanjut dan Sub-akun: 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 melakukan panggilan (bukan ID MC) dan tidak terlihat dalam diagnostik standar. listSubaccounts dihitung terhadap kuota MCA Anda.
Sebelumnya
Overview
Berikutnya
Merchant Center limits