سهمیه‌ها

این سند سهمیه‌هایی را که برای Merchant API اعمال می‌شود فهرست می‌کند.

‫Merchant API از سهمیه‌ها استفاده می‌کند تا به تضمین محیطی پایدار و عادلانه برای همه کاربران کمک کند. سهمیه‌ها از اینکه یک کاربر API بار بیش‌ازحدی بر سیستم تحمیل کند جلوگیری می‌کنند و عملکرد بالا را تضمین می‌کنند. درک این سهمیه‌ها کلید مدیریت داده‌های محصول و مقیاس‌بندی کسب‌وکارتان در Google است.

مفاهیم کلی

سهمیه‌های Merchant API ازطریق گروه‌های سهمیه مدیریت می‌شوند.

روش‌های میانای برنامه‌سازی کاربردی به گروه‌های سهمیه نگاشت می‌شوند. ساختار این نگاشت می‌تواند متفاوت باشد:

  • یک روش برای هر گروه: برخی‌از گروه‌های سهمیه برای یک روش میانای برنامه‌سازی کاربردی اعمال می‌شوند. برای مثال، روش فهرست کردن منابع داده accounts.dataSources.list گروه سهمیه اختصاصی خودش را دارد.
  • چند روش در هر گروه (دسته‌بندی): اغلب، روش‌های مرتبط در یک گروه سهمیه واحد دسته‌بندی می‌شوند. همه روش‌های موجود در آن گروه حدود روزانه و دقیقه‌ای یکسانی دارند. نمونه‌های رایج عبارت‌اند از:
    • گروه‌بندی همه عملیات‌های خواندن برای روش‌ها و منابع مرتبط، مانند merchant-accounts-read-methods.
    • گروه‌بندی همه عملیات نوشتن برای روش‌ها و منابع مرتبط، مانند merchant-accounts-write-methods.

هر فراخوانی روش، صرف‌نظر از نوع آن، یک‌بار شمرده می‌شود. یک درخواست list برای ۲۵۰ مورد فقط یک‌بار محاسبه می‌شود، نه به‌عنوان ۲۵۰ درخواست get.

دسته‌بندی HTTP داخلی بر سهمیه تأثیر نمی‌گذارد. هر درخواست تکی در یک دسته درخواست به‌عنوان یک درخواست در سهمیه محاسبه می‌شود. برای مثال، یک درخواست دسته‌ای حاوی ۵۰۰ درخواست insert به‌عنوان ۵۰۰ درخواست روش insert جداگانه شارژ می‌شود.

استثنا برای دسته‌بندی منطقه اختصاصی: روش‌های دسته‌بندی منطقه تخصصی (batchCreate، batchUpdate، batchDelete) به‌عنوان یک فراخوانی API تکی دربرابر گروه سهمیه merchant_regions به‌حساب می‌آیند، صرف‌نظر از تعداد عملیات منطقه موجود در بار داده.

برای مدیریت مؤثر ادغام، باید گروه سهمیه خاص مرتبط با هر روش میانای برنامه‌سازی کاربردی را که قصد استفاده از آن را دارید مرور کنید. می‌توانید این جزئیات را در روش فهرست سهمیه‌ها پیدا کنید. برای اطلاعات بیشتر، به پایش و رؤیت‌پذیری مراجعه کنید.

خط‌مشی به‌روزرسانی

Merchant API خط‌مشی‌های زیر را ازنظر به‌روزرسانی‌ها اعمال می‌کند:

  • به‌طور پیش‌فرض، می‌توانید محصولاتتان را حداکثر دو بار در روز به‌روز کنید. برای رعایت سهمیه دقیقه‌ای، باید تماس‌ها را به‌طور یکنواخت درطول روز پخش کنید.
  • به‌طور پیش‌فرض، فقط می‌توانید حساب‌های فرعی‌تان را حداکثر دو بار در روز به‌روز کنید. سهمیه به‌روزرسانی حساب فرعی روزانه شما یک حد مجموع براساس کل حساب‌های فرعی مجاز شما است.
  • به‌طور پیش‌فرض، فقط می‌توانید روش‌های منبع داده را برای حساب‌های فرعی‌تان مثل list یا create حداکثر دو بار در روز برای هر حساب فرعی فراخوانی کنید.

سهمیه‌های نرخ

هر گروه سهمیه دو نوع محدودیت (و استفاده روزانه) دارد:

  • حد روزانه (quotaLimit): حداکثر تعداد درخواست‌های مجاز در روز. محدودیت‌های سهمیه روزانه در ساعت ۱۲:۰۰ ظهر به‌وقت ساعت هماهنگ جهانی بازنشانی می‌شود.
  • محدودیت در دقیقه (quotaMinuteLimit): حداکثر تعداد درخواست‌های مجاز در دقیقه که نرخ درخواست‌ها را کنترل می‌کند. محدودیت‌های سهمیه دقیقه‌ای از پنجره متحرک استفاده می‌کنند، که در آن دوره اجرا از لحظه‌ای شروع می‌شود که اولین فراخوانی API برای آن روش و منبع انجام می‌شود. برای مثال، اگر تماسی در ساعت ۱۰:۰۱:۳۰ صبح برقرار کنید، پنجره سهمیه دقیقه‌ای برای آن روش تا ساعت ۱۰:۰۲:۳۰ صبح اجرا می‌شود.
  • استفاده روزانه (quotaUsage): تعداد درخواست‌هایی که قبلاً انجام شده و در حد روزانه برای روز جاری محاسبه شده است. اگر فیلد وجود نداشته باشد، هنوز هیچ سهمیه‌ای برای این گروه مصرف نشده است.

می‌توانید سه فیلد شرح‌داده‌شده در بالا (quotaLimit، quotaMinuteLimit، و quotaUsage) را در پاسخ روش quotas.list پیدا کنید.

حدود روزانه و دقیقه‌ای خاص بین گروه‌های سهمیه مختلف به‌طور قابل‌توجهی متفاوت است. عملیات با حجم موردانتظار بالاتر یا هزینه سیستم کمتر، مانند خواندن داده‌های محصول، معمولاً محدودیت‌های بالاتری دارند. برعکس، عملیات‌های فشرده‌تر یا حساس‌تر، مانند اصلاحات حساب، ممکن است محدودیت‌های کمتری داشته باشند.

سلسله‌مراتب و تخصیص سهمیه

این بخش توضیح می‌دهد که Merchant API ازطرف چه کسی استفاده از سهمیه را ردیابی و اعمال می‌کند:

به‌طور کلی، سهمیه براساس کاربری که درخواست API را انجام می‌دهد کسر می‌شود.

  • حساب‌های مستقل: برای حساب‌های مستقلی که یک فراخوانی میانای برنامه‌سازی کاربردی را اصالت‌سنجی می‌کنند، آن درخواست جزو سهمیه آن حساب محسوب می‌شود.
    • مثال: فروشنده Shoe Store A (شناسه حساب: ۱۲۳۴۵) بااستفاده از حساب سرویس خودش برای فراخوانی products.insert با هدف قرار دادن حساب خودش (accounts/12345) اصالت‌سنجی می‌کند. سهمیه از استخر سهمیه Shoe Store A مصرف می‌شود.
  • حساب‌های پیشرفته: اصالت‌سنجی به‌عنوان حساب پیشرفته سهمیه را از مجموعه حساب پیشرفته مصرف می‌کند، حتی هنگام هدف‌یابی زیرحساب.
    • مثال: یک حساب مدیریت خرده‌فروشی (شناسه حساب پیشرفته: ۱۲۳۴۵) یک حساب فرعی فروشگاه پوشاک ب (شناسه حساب: ۱۱۱۱۱) را مدیریت می‌کند. نمایندگی بااستفاده از اعتبارنامه‌های خودش اصالت‌سنجی می‌کند و products.insert را با هدف قرار دادن فروشگاه پوشاک ب (accounts/11111) فراخوانی می‌کند. سهمیه از استخر نمایندگی اصلی (شناسه حساب پیشرفته: ۱۲۳۴۵) مصرف می‌شود، نه از استخر حساب فرعی.
  • حساب‌های فرعی: وقتی فراخوانی‌های میانای برنامه‌سازی کاربردی بااستفاده از اعتبارنامه‌های حساب فرعی اصالت‌سنجی می‌شوند، سهمیه از استخر فردی آن حساب فرعی کسر می‌شود. این حساب همانند حساب مستقل عمل می‌کند، هرچند که توسط حساب پیشرفته ولی مدیریت می‌شود.
    • مثال: بااستفاده از همان راه‌اندازی قبلی، اگر فروشگاه پوشاک ب (شناسه حساب: ۱۱۱۱۱) بااستفاده از اعتبارنامه‌هایی که به‌طور خاص برای حساب فرعی‌اش راه‌اندازی شده است اصالت‌سنجی کند تا products.insert را با هدف قرار دادن حساب خودش (accounts/11111) فراخوانی کند، سهمیه از مجموعه سهمیه فردی فروشگاه پوشاک ب مصرف می‌شود و مجموعه آژانس اصلی دست‌نخورده باقی می‌ماند.

استثنائات قوانین عمومی

چند استثنای خاص وجود دارد که برای قوانین کلی تخصیص سهمیه اعمال می‌شود:

  • Accounts.list: سهمیه این روش از حساب کاربری یا حساب سرویس اصالت‌سنجی‌شده‌ای که تماس را برقرار می‌کند کسر می‌شود، نه از شناسه حساب Merchant Center. استفاده از سهمیه آن در صفحه عیب‌یابی Merchant Center API استاندارد قابل‌مشاهده نخواهد بود. اگر حساب پیشرفته دارید، توصیه می‌کنیم از روش accounts.listSubaccounts استفاده کنید که در سهمیه حساب‌های پیشرفته شما لحاظ می‌شود.
  • روش‌های حل مشکل: این روش‌ها همیشه از سهمیه حسابی که مشکلات آن درخواست می‌شود کسر می‌شوند، حتی اگر حساب دیگری درخواست را اصالت‌سنجی کند.

سلسله‌مراتب تخصیص

  • سرویس‌های مقایسه قیمت (CSS): CSS وب‌سایت‌هایی هستند که پیشنهادهای محصول را جمع‌آوری می‌کنند و کاربران را برای خرید به وب‌سایت‌های خرده‌فروشان هدایت می‌کنند. هنگام برقراری تماس‌های میانای برنامه‌سازی کاربردی، سهمیه‌ها برای گروه CSS، دامنه CSS، حساب، یا حساب فرعی خاصی که دربرابر آن اصالت‌سنجی می‌کنید اعمال می‌شود.

    نمونه:

    • یک «گروه CSS» به‌نام Europe Shopping Group (شناسه حساب: ۱۰۰۰۱) می‌خواهد دامنه‌های CSS مرتبط با خود را فهرست کند. با اصالت‌سنجی با اعتبارنامه خودش برای برقراری این تماس API، سهمیه مستقیماً از استخر سهمیه Europe Shopping Group مصرف می‌شود.
    • دامنه CSS TopDeals CSS (شناسه حساب: ۲۰۰۰۲) برای فراخوانی روشی که یکی از حساب‌های فروشنده مرتبط با آن (accounts/30003) را برای اختصاص برچسب هدف قرار می‌دهد، اصالت‌سنجی می‌کند. سهمیه از مجموعه سهمیه TopDeals CSS مصرف می‌شود، نه از مجموعه حساب فروشنده.

  • بازارگاه‌ها: بازارگاه‌ها پلاتفرم‌های آنلاینی هستند که میزبان چندین فروشنده مجزا هستند. این حساب‌ها به‌عنوان حساب‌های پیشرفته ویژه عمل می‌کنند که به شما امکان می‌دهند برای هریک از فروشندگان خود حساب‌های فرعی جداگانه ایجاد کنید.

نمودار زیر سلسله‌مراتب گروه‌های CSS،‏ CSS، بازارگاه‌ها، حساب‌های پیشرفته، حساب‌های مستقل، و حساب‌های فرعی را نشان می‌دهد.

گروه CSS سطح اصالت‌سنجی فراگیر است، با امکان CSS فردی در آن، حساب‌های درون آن‌ها و حساب‌های فرعی به‌عنوان فردی‌ترین سطح.

تعدیل خودکار سهمیه

Merchant API سیستم مدیریت سهمیه خودکاری برای سرویس‌های خاص دارد که محدودیت‌های سهمیه را برای فروشندگان درحال رشد براساس میزان استفاده، پیشنهاد، و اندازه حساب شما تنظیم می‌کند. ‫Merchant API این سهمیه‌ها را روزانه بازمحاسبه می‌کند.

گروه‌های سهمیه موجود در تنظیمات خودکار سهمیه عبارتند از:

خدمات محصولات

  • همه گروه‌های سهمیه روش‌های مربوط به منابع products و productInputs.
  • سهمیه تماس روزانه معمولاً ۲ برابر سهمیه پیشنهاد ویژه‌ای است که فروشنده دارد. این فرض می‌کند که فروشنده ممکن است نیاز داشته باشد هریک از محصولات خود را تا دو بار در روز به‌روز کند.
  • محصولات تکی را می‌توان بیش‌از دو بار به‌روز کرد، اما مجموع تماس‌های API روزانه شما نمی‌تواند از سهمیه تماس روزانه کل فراتر رود.

خدمات حساب‌ها

  • همه گروه‌های سهمیه روش‌های مربوط به منابع مختلف جزئی مرتبط با حساب در Merchant API.
  • سهمیه تماس روزانه روی حداکثر تعداد حساب‌های فرعی مجاز برای آن حساب تنظیم شده است. این کار امکان حداکثر دو بار فراخوانی خواندن در روز را برای هر حساب فرعی فراهم می‌کند.

خدمات منابع داده‌ها

  • همه گروه‌های سهمیه روش‌های مربوط به منابع مرتبط با منبع داده در Merchant API، مثل list یا create، که حساب پیشرفته در حساب‌های فرعی خود انجام می‌دهد.
  • سهمیه تماس روزانه معمولاً ۲ برابر تعداد حساب‌های فرعی حساب پیشرفته تنظیم می‌شود. این فرض می‌کند که فروشنده می‌تواند هریک از منابع داده‌های حساب‌های فرعی خود را حداکثر دو بار در روز به‌روز کند.

فقط سرویس‌هایی که قبلاً شرح داده شد تنظیمات سهمیه خودکار دارند. سرویس‌های دیگر سهمیه پیش‌فرضی دارند و هرگونه افزایش باید به‌صورت دستی درخواست شود. برای اطلاعات بیشتر، به بخش فرایند افزایش سهمیه مراجعه کنید.

وقتی از سهمیه فراتر رفته باشید چه اتفاقی می‌افتد

پس‌از فراتر رفتن از سهمیه، خطاهایی در پاسخ‌های میانای برنامه‌سازی کاربردی و در صفحه عیب‌یابی در حساب Merchant Center شما ظاهر خواهد شد:

  • در دقیقه: 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"
                }
            }
        ]
    }
}
  • در روز: 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"
                }
            }
        ]
    }
}

خطاهای زیر مربوط به محدودیت‌های Merchant Center است و به سهمیه‌های Merchant API مربوط نمی‌شود. می‌توانید درخواست سهمیه اضافی برای موارد، فیدها، یا حساب‌های فرعی کنید:

  • too_many_items: از سهمیه فروشنده فراتر رفته‌اید
  • too_many_subaccounts: به حداکثر تعداد حساب‌های فرعی رسیده‌اید

پایش و رؤیت‌پذیری

برای بررسی سهمیه‌های تماس فعلی و استفاده از حساب، با quotas.list با نام حساب تماس بگیرید.

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

موارد زیر را جایگزین کنید:

  • ACCOUNT_ID: شناسه Merchant Center شما
  • ‫ACCESS_TOKEN: کد مجوز برای برقراری تماس API

پس‌از درخواست موفق، میانای برنامه‌سازی کاربردی فهرستی از منابع quotaGroups را برمی‌گرداند که حاوی منبع name گروه سهمیه، سهمیه‌های مختلف، و روش‌هایی است که سهمیه گروه برای آن‌ها اعمال می‌شود.

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

فرایند افزایش سهمیه

برای درخواست سهمیه بیشتر، فرم تماس با پشتیبانی را باز کنید، «درخواست افزایش سهمیه» را برای فیلد الزامی «مشکل/ پرسش چیست» انتخاب کنید، و همه فیلدهای الزامی را تکمیل کنید، ازجمله شناسه Merchant Center، روش‌های هدف، و توجیه کسب‌وکار.

  • برای منابعی که سهمیه خودکار دارند (products، accounts، و datasources برای حساب‌های پیشرفته): فقط برای سناریوهای خاص مثل راه‌اندازی در بازار جدید یا درطول فصل‌های خرید با ترافیک بالا می‌توانید درخواست افزایش موقت بدهید. افزایش دائمی سهمیه را برای این نوع منابع نمی‌پذیریم.
  • برای همه منابع دیگر بدون سهمیه خودکار: درصورت نیاز، درخواست افزایش سهمیه کنید.

توصیه می‌کنیم سهمیه‌هایتان را به‌طور دوره‌ای بررسی کنید تا مطمئن شوید سهمیه کافی برای پیاده‌سازی‌تان دارید و ببینید سهمیه‌تان چگونه به‌طور خودکار تنظیم می‌شود. از روش quotas.list برای دیدن حد سهمیه روزانه فعلی، حد دقیقه‌ای، و میزان استفاده روزانه فعلی برای هر گروه روش میانای برنامه‌سازی کاربردی استفاده کنید.

روال‌های مطلوب

اجرای این روال‌های مطلوب کمک می‌کند مطمئن شوید ادغام شما به‌خوبی اجرا می‌شود، از خطاهای غیرمنتظره سهمیه جلوگیری می‌کند، و از منابع Merchant Center به‌طور کارآمد استفاده می‌کند.

بهینه‌سازی توزیع درخواست

  • درخواست‌ها را به‌طور یکنواخت توزیع کنید: از ارسال رگباری درخواست‌ها خودداری کنید. فراخوانی‌های میانای برنامه‌سازی کاربردی روزانه‌تان را به‌طور یکنواخت درطول روز پخش کنید تا از حدود سهمیه دقیقه‌ای (quotaMinuteLimit) فراتر نروید.
  • محدود کردن شبکه پیش‌گیرانه: محدود کردن نرخ سمت کارخواه (محدود کردن شبکه) را در برنامه‌تان پیاده‌سازی کنید. برای رد کردن ترافیک اضافی، فقط به سرورهای Google متکی نباشید. میزان درخواست را در منبع کنترل کنید.

مدیریت کردن خطا به‌صورت ملایم

  • رسیدگی به HTTP 429: برنامه شما باید برای رسیدگی به خطاهای «429 درخواست‌های بسیار زیاد» (quota/request_rate_too_high) آماده باشد.
  • عقب‌گرد نمایی با لرزش: هنگام امتحان مجدد درخواست‌های ناموفق (به‌ویژه پس‌از خطای ۴۲۹)، از عقب‌گرد نمایی (افزایش زمان انتظار) استفاده کنید و «لرزش» (تأخیر تصادفی) اضافه کنید. لرزش از «طوفان‌های تکرار» جلوگیری می‌کند، جایی که چندین نمونه مشتری دقیقاً در یک زمان دوباره تلاش می‌کنند و دوباره سرور را بیش‌ازحد بارگذاری می‌کنند.
  • رعایت کردن نکات مربوط به امتحان مجدد: اگر پاسخ میانای برنامه‌سازی کاربردی حاوی جزئیات یا سرصفحه‌های امتحان مجدد است، از آن‌ها برای تعیین زمان ازسر گرفتن تماس‌ها استفاده کنید.

به‌حداقل رساندن تماس‌های تکراری

  • جلوگیری از تماس‌های کهنه (404 NOT_FOUND): از درخواست یا حذف منابعی که دیگر وجود ندارند خودداری کنید. حتی تماس‌های ناموفق هم سهمیه میانای برنامه‌سازی کاربردی را مصرف می‌کنند. خطاهای NOT_FOUND را در «عیب‌یابی Merchant Center API» پایش کنید تا ردیابی وضعیت کهنه یا نظرسنجی غیرضروری را شناسایی کنید.
  • درستی‌سنجی قبل‌از به‌روزرسانی: قبل‌از ارسال درخواست به‌روزرسانی، بررسی کنید که آیا داده‌ها واقعاً تغییر کرده‌اند یا نه. از ارسال به‌روزرسانی‌هایی که مقادیر یکسانی را می‌نویسند خودداری کنید.
  • استفاده از حافظه پنهان: پاسخ‌های خوانده‌شده (مثلاً جزئیات محصول، تنظیمات) را درصورت لزوم به‌صورت محلی در حافظه پنهان ذخیره کنید تا از فراخوانی‌های تکراری get یا list برای داده‌های تغییرنکرده جلوگیری شود.
  • حساب‌های پیشرفته و حساب‌های فرعی: اگر حساب پیشرفته دارید، اگر می‌خواهید تماس‌ها در مقابل مجموعه مشترک حساب‌های پیشرفته محاسبه شود، در سطح حساب پیشرفته اصالت‌سنجی کنید.
  • استفاده از listSubaccounts: برای حساب‌های پیشرفته، از accounts.listSubaccounts به‌جای accounts.list استفاده کنید. سهمیه accounts.list از کاربر تماس‌گیرنده (نه شناسه MC) کسر می‌شود و در عیب‌یابی استاندارد قابل‌مشاهده نیست. listSubaccounts جزو سهمیه MCA شما حساب می‌شود.
قبلی
Overview
بعدی
Merchant Center limits