سهمیه ها

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

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

مفاهیم کلی

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

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

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

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

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

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

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

سیاست به‌روزرسانی

رابط برنامه‌نویسی کاربردی فروشنده (Merchant API) سیاست‌های زیر را در رابطه با به‌روزرسانی‌ها اعمال می‌کند:

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

سهمیه نرخ

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

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

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

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

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

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

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

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

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

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

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

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

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

    مثال‌ها:

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

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

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

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

تنظیم خودکار سهمیه

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

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

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

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

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

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

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

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

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

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

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

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

خطاهای زیر محدودیت‌های مرکز پذیرندگان هستند و به سهمیه‌های 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 : شناسه مرکز فروش شما
  • ACCESS_TOKEN : توکن مجوز برای برقراری فراخوانی API

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

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

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

برای درخواست سهمیه اضافی، فرم تماس با پشتیبانی را باز کنید، درخواست افزایش سهمیه را برای فیلد مورد نیاز "مشکل/سوال چیست" انتخاب کنید و تمام فیلدهای مورد نیاز، از جمله شناسه مرکز پذیرندگان، روش‌های هدف و توجیه کسب و کار خود را پر کنید.

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

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

بهترین شیوه‌ها

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

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

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

مدیریت خطای دلپذیر

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

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

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