سهمیه‌ها

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

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

مفاهیم کلی

سهمیه‌های «میانای برنامه‌سازی کاربردی فروشنده» ازطریق گروه‌های سهمیه مدیریت می‌شوند.

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

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

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

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

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

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

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

«میانای برنامه‌سازی کاربردی فروشنده» خط‌مشی‌های زیر را ازنظر به‌روزرسانی‌ها اجرا می‌کند:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    نمونه:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

پس‌از اینکه از سهمیه فراتر رفتید، خطاها در پاسخ‌های API و در صفحه تشخیص خرابی در حساب 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 برای دیدن حد سهمیه روزانه فعلی، حد دقیقه‌ای، و میزان استفاده روزانه فعلی برای هر گروه روش API استفاده کنید.

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

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

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

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

مدیریت خطای محترمانه

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

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

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