الحصص

يسرد هذا المستند الحصص التي تنطبق على Merchant API.

تستخدم Merchant API حصصًا للمساعدة في ضمان توفير بيئة مستقرة وعادلة لجميع المستخدمين. تمنع الحصص أي مستخدم فردي لواجهة برمجة التطبيقات من فرض حِمل مفرط على النظام، ما يضمن تحقيق أداء عالٍ. إنّ فهم هذه الحصص هو المفتاح لإدارة بيانات منتجاتك وتوسيع نطاق مؤسستك على Google.

المفاهيم العامة

تتم إدارة حصص Merchant API من خلال مجموعات الحصص.

يتم ربط طرق واجهة برمجة التطبيقات بمجموعات الحصص. يمكن أن يختلف هيكل عملية الربط هذه:

  • طريقة واحدة لكل مجموعة: تنطبق بعض مجموعات الحصص على طريقة واحدة من طرق واجهة برمجة التطبيقات. على سبيل المثال، تتضمّن طريقة عرض مصادر بيانات البطاقات accounts.dataSources.list مجموعة حصص مخصّصة.
  • طُرق متعددة لكل مجموعة (تجميع): غالبًا ما يتم تجميع الطُرق ذات الصلة معًا في مجموعة حصص واحدة. تتشارك جميع الطرق ضمن هذه المجموعة الحدود نفسها لكل من اليوم والدقيقة. تشمل الأمثلة الشائعة ما يلي:
    • تجميع جميع عمليات القراءة للطُرق والموارد ذات الصلة، مثل merchant-accounts-read-methods
    • تجميع جميع عمليات الكتابة للطُرق والموارد ذات الصلة، مثل merchant-accounts-write-methods

يتم احتساب كل طلب إجراء مرة واحدة، بغض النظر عن نوعه. يتم احتساب طلب list يتضمّن 250 عنصرًا مرة واحدة فقط، وليس على أنّه 250 طلب get.

لا يؤثر تجميع طلبات HTTP المضمّن في الحصة. يُحتسب كل طلب فردي ضمن مجموعة من الطلبات كطلب واحد ضمن الحصة المخصّصة. على سبيل المثال، يتم تحصيل رسوم مقابل طلب مجمّع يحتوي على 500 طلب insert على أنّه 500 طلب فردي لطريقة insert.

استثناء للتجميع المخصّص للمناطق: تُحتسب طرق التجميع المخصّصة للمناطق (batchCreate وbatchUpdate وbatchDelete) كطلب بيانات من واجهة برمجة التطبيقات واحد ضمن مجموعة الحصص merchant_regions، بغض النظر عن عدد عمليات المناطق المضمّنة في الحمولة.

لإدارة عملية الدمج بفعالية، عليك مراجعة مجموعة الحصص المحدّدة المرتبطة بكل طريقة من طرق واجهة برمجة التطبيقات التي تنوي استخدامها. يمكنك العثور على هذه التفاصيل في طريقة عرض قائمة الحصص. لمزيد من المعلومات، يُرجى الاطّلاع على المراقبة وإمكانية الاطّلاع.

تعديل السياسة

تفرض واجهة برمجة التطبيقات Merchant API السياسات التالية في ما يتعلق بالتعديلات:

  • يمكنك تعديل منتجاتك مرّتين في اليوم كحدّ أقصى. يجب توزيع المكالمات بالتساوي على مدار اليوم للالتزام بحصة الدقيقة الواحدة.
  • بشكلٍ تلقائي، يمكنك تعديل حساباتك الفرعية مرّتين في اليوم كحدّ أقصى. إنّ حصة التعديل اليومية للحساب الفرعي هي حدّ إجمالي يستند إلى إجمالي عدد الحسابات الفرعية المسموح بها.
  • بشكلٍ تلقائي، يمكنك استدعاء طرق مصدر البيانات لحساباتك الفرعية، مثل list أو create، مرّتين كحدّ أقصى لكل حساب فرعي في اليوم.

حصص الأسعار

تتضمّن كل مجموعة حصص نوعَين من الحدود (والاستخدام اليومي):

  • الحدّ الأقصى اليومي (quotaLimit): هو الحدّ الأقصى لعدد الطلبات المسموح بها في اليوم. تتم إعادة ضبط حدود الحصة اليومية عند الساعة 12:00 ظهرًا بالتوقيت العالمي المتفق عليه.
  • الحدّ الأقصى لكل دقيقة (quotaMinuteLimit): هو الحدّ الأقصى لعدد الطلبات المسموح به في الدقيقة الواحدة، ويتحكّم في معدّل الطلبات. تستخدم حصص الاستخدام المحدودة لكل دقيقة فترة متجددة، حيث تبدأ فترة التنفيذ من لحظة إجراء طلب البيانات الأول من واجهة برمجة التطبيقات لتلك الطريقة والمورد. على سبيل المثال، إذا أجريت طلبًا في الساعة 10:01:30 صباحًا، ستستمر فترة الحصة المحددة لكل دقيقة لهذا الأسلوب حتى الساعة 10:02:30 صباحًا.
  • الاستخدام اليومي (quotaUsage): هو عدد الطلبات التي تم إجراؤها واحتسابها ضمن الحد اليومي لليوم الحالي. إذا كان الحقل غير متوفّر، يعني ذلك أنّه لم يتم استهلاك أي حصة لهذه المجموعة حتى الآن.

يمكنك العثور على الحقول الثلاثة الموضّحة سابقًا (quotaLimit وquotaMinuteLimit وquotaUsage) في الردّ الخاص بالطريقة quotas.list.

تختلف الحدود اليومية والحدود المحدّدة لكل دقيقة بشكل كبير بين مجموعات الحصص المختلفة. عادةً ما تكون العمليات التي يُتوقّع أن يكون عددها أكبر أو التي تكون تكلفتها على النظام أقل، مثل قراءة بيانات المنتجات، لها حدود قصوى أعلى. في المقابل، قد تكون العمليات الأكثر حساسية أو تعقيدًا، مثل تعديلات الحساب، محدودة أكثر.

تخصيص الحصة والتسلسل الهرمي

يوضّح هذا القسم الجهة التي تتتبّع Merchant API استخدام الحصة وتطبّقها نيابةً عنها:

بشكل عام، يتم تحصيل الرسوم مقابل الحصة استنادًا إلى المستخدم الذي يرسل طلب البيانات من واجهة برمجة التطبيقات.

  • الحسابات المستقلة: بالنسبة إلى الحسابات المستقلة التي تصادق على طلب من واجهة برمجة التطبيقات، يتم احتساب هذا الطلب ضمن حصة هذا الحساب.
    • مثال: يصادق تاجر متجر الأحذية أ (رقم تعريف الحساب: 12345) على الطلب باستخدام حساب الخدمة الخاص به من أجل استدعاء products.insert الذي يستهدف حسابه (accounts/12345). يتم استهلاك الحصة من مجموعة حصص متجر الأحذية أ.
  • الحسابات بامتيازات متقدّمة: عند المصادقة كـ حساب بامتيازات متقدّمة، يتم استهلاك الحصة من مجموعة الحسابات بامتيازات متقدّمة، حتى عند استهداف حساب فرعي.
    • مثال: تدير وكالة حساب إدارة البيع بالتجزئة (رقم تعريف الحساب المتقدّم: 12345) حسابًا فرعيًا متجر الملابس ب (رقم تعريف الحساب: 11111). تتم المصادقة على الوكالة باستخدام بيانات الاعتماد الخاصة بها، وتُجري الوكالة طلباتproducts.insert تستهدف متجر الملابس B (accounts/11111). يتم استهلاك الحصة من مجمّع الوكالة الرئيسية (معرّف الحساب المتقدّم: 12345)، وليس من مجمّع الحساب الفرعي.
  • الحسابات الفرعية: عند مصادقة طلبات البيانات من واجهة برمجة التطبيقات باستخدام بيانات اعتماد حساب فرعي، يتم احتساب الحصة من مجمّع الحساب الفرعي الفردي. ويعمل هذا الحساب بالطريقة نفسها التي يعمل بها الحساب المستقل، على الرغم من أنّه تتم إدارته من خلال حساب بامتيازات متقدّمة رئيسي.
    • مثال: باستخدام الإعداد نفسه كما في المثال السابق، إذا كان متجر الملابس B (معرّف الحساب: 11111) يصادق على الطلب باستخدام بيانات الاعتماد التي تم إعدادها خصيصًا لحسابه الفرعي من أجل طلب products.insert الذي يستهدف حسابه (accounts/11111)، سيتم استهلاك الحصة من مجمّع الحصص الفردية لمتجر الملابس B، بدون التأثير في مجمّع الوكالة الرئيسية.

استثناءات من القواعد العامة

هناك بعض الاستثناءات المحدّدة التي تنطبق على القواعد العامة لتخصيص الحصة:

  • Accounts.list: يتم احتساب حصة هذا الإجراء من حساب المستخدم الذي تمّت المصادقة عليه أو حساب الخدمة الذي يجري الطلب، وليس من رقم تعريف حساب Merchant Center. لن يظهر استخدام الحصة في صفحة بيانات تشخيص Merchant Center API العادية. إذا كان لديك حساب بامتيازات متقدّمة، ننصحك باستخدام طريقة accounts.listSubaccounts التي يتم احتسابها ضمن حصة الحسابات بامتيازات متقدّمة.
  • طُرق حلّ المشاكل: يتم دائمًا احتساب هذه الطرق ضمن الحصة المخصّصة للحساب الذي يتم طلب حلّ مشاكله، حتى إذا كان حساب مختلف يصادق على الطلب.

التسلسل الهرمي للتخصيص

  • خدمات مقارنة الأسعار (CSS): هي مواقع إلكترونية تجمع عروض المنتجات وتوجّه المستخدمين إلى المواقع الإلكترونية الخاصة ببائعي التجزئة لإجراء عمليات الشراء. عند إجراء طلبات بيانات من واجهة برمجة التطبيقات، يتم تطبيق الحصص على مجموعة CSS أو نطاق CSS أو الحساب أو الحساب الفرعي المحدّد الذي تصادق عليه.

    أمثلة:

    • تريد مجموعة CSS باسم مجموعة Shopping في أوروبا (رقم تعريف الحساب: 10001) إدراج نطاقات CSS المرتبطة بها. من خلال المصادقة باستخدام بيانات الاعتماد الخاصة به لإجراء طلب البيانات من واجهة برمجة التطبيقات، يتم استهلاك الحصة مباشرةً من مجموعة حصص مجموعة Shopping في أوروبا.
    • يتم التحقّق من نطاق CSS TopDeals CSS (رقم تعريف الحساب: 20002) من أجل استدعاء طريقة تستهدف أحد حسابات التجّار المرتبطة به (accounts/30003) لتعيين تصنيف. يتم استهلاك الحصة من مجمّع الحصص الخاص بخدمة CSS في TopDeals، وليس من مجمّع حساب التاجر.

  • الأسواق: الأسواق هي منصات على الإنترنت تستضيف عدة تجار فرديين. وهي تعمل كحسابات متقدّمة خاصة تتيح لك إنشاء حسابات فرعية فردية لكل بائع من بائعي منتجاتك.

يوضّح الرسم البياني التالي التسلسل الهرمي لمجموعات CSS وخدمات CSS والأسواق والحسابات المتقدّمة والحسابات المستقلة والحسابات الفرعية.

مجموعة CSS هي مستوى المصادقة الشامل، مع إمكانية توفّر حسابات CSS فردية ضمنها، وحسابات ضمن تلك الحسابات، وحسابات فرعية كأكثر مستوى فردي.

تعديل الحصة تلقائيًا

تتضمّن واجهة برمجة التطبيقات Merchant API نظامًا تلقائيًا لإدارة الحصة المخصّصة لخدمات معيّنة، ما يؤدي إلى تعديل حدود الحصة المخصّصة للتجّار المتزايدين استنادًا إلى استخدامك وحجم العرض والحساب. تعيد Merchant API احتساب هذه الحصص يوميًا.

مجموعات الحصص المضمّنة في تعديلات الحصص التلقائية هي:

خدمات المنتجات

  • جميع مجموعات الحصص للطُرق ذات الصلة بموارد products وproductInputs
  • يتم بشكل عام ضبط حصة المكالمات اليومية على ضعف حصة العروض التي يملكها التاجر. ويفترض ذلك أنّ التاجر قد يحتاج إلى تعديل كل منتج من منتجاته مرتين في اليوم كحدّ أقصى.
  • يمكن تعديل المنتجات الفردية أكثر من مرتين، ولكن يجب ألا يتجاوز إجمالي عدد طلبات البيانات من واجهة برمجة التطبيقات اليومية حصة الطلبات اليومية المجمّعة.

خدمات الحسابات

  • جميع مجموعات الحصص لطُرق مرتبطة بمختلف الموارد الدقيقة ذات الصلة بالحساب في 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: رمز التفويض لإجراء طلب البيانات من واجهة برمجة التطبيقات

عند نجاح الطلب، تعرض واجهة برمجة التطبيقات قائمة بموارد 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 Too Many Requests (quota/request_rate_too_high).
  • الرقود الأسي الثنائي مع التشويش: عند إعادة محاولة إرسال الطلبات التي تعذّر تنفيذها (خاصةً بعد ظهور الخطأ 429)، استخدِم الرقود الأسي الثنائي (زيادة أوقات الانتظار) وأضِف "تشويشًا" (تأخيرًا عشوائيًا). يمنع التذبذب حدوث "عواصف إعادة المحاولة"، حيث تحاول عدة مثيلات من العميل إعادة المحاولة في الوقت نفسه بالضبط، ما يؤدي إلى زيادة الحمل على الخادم مرة أخرى.
  • الالتزام بتلميحات إعادة المحاولة: إذا كانت استجابة واجهة برمجة التطبيقات تتضمّن تفاصيل أو عناوين لإعادة المحاولة، استخدِمها لتحديد وقت استئناف الطلبات.

تقليل المكالمات المكرّرة

  • منع المكالمات القديمة (404 NOT_FOUND): تجنَّب طلب أو حذف موارد لم تعُد متاحة. حتى الطلبات التي تعذّر تنفيذها تستهلك حصة واجهة برمجة التطبيقات. تتبُّع أخطاء NOT_FOUND في "بيانات تشخيص واجهة برمجة التطبيقات" في Merchant Center لرصد تتبُّع الحالة القديمة أو عمليات الاقتراع غير الضرورية
  • التأكّد من التغييرات قبل إرسال طلب التعديل: قبل إرسال طلب تعديل، تحقَّق مما إذا كانت البيانات قد تغيّرت بالفعل. تجنَّب إرسال تعديلات تكتب القيم نفسها.
  • استخدام التخزين المؤقت: تخزين الردود التي تم قراءتها مؤقتًا (مثل تفاصيل المنتج والإعدادات) على الجهاز عند الحاجة لتجنُّب طلبات get أو list المتكررة للبيانات غير المتغيرة.
  • الحسابات بامتيازات متقدّمة والحسابات الفرعية: إذا كان لديك حساب بامتيازات متقدّمة، عليك المصادقة على مستوى الحساب بامتيازات متقدّمة إذا كنت تريد أن يتم احتساب المكالمات ضمن مجموعة الحسابات بامتيازات متقدّمة المشتركة.
  • استخدام listSubaccounts: بالنسبة إلى الحسابات بامتيازات متقدّمة، استخدِم accounts.listSubaccounts بدلاً من accounts.list. يتم تحصيل رسوم حصة accounts.list من المستخدم الذي يجري الاتصال (وليس من معرّف العميل في "مركز عملائي") ولا تظهر في بيانات التشخيص العادية. يتم احتساب listSubaccounts ضمن حصة حسابك الإداري (حساب متعدّد العملاء).
السابق
Overview
التالي
Merchant Center limits