الحصص

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

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

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

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

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

• طريقة واحدة لكل مجموعة: تنطبق بعض مجموعات الحصص على طريقة واحدة من طرق واجهة برمجة التطبيقات. على سبيل المثال، يتضمّن الأسلوب accounts.dataSources.list listing data sources مجموعة حصص مخصّصة.
• طُرق متعددة لكل مجموعة (تجميع): غالبًا ما يتم تجميع الطُرق ذات الصلة معًا في مجموعة حصص واحدة. تتشارك جميع الطرق ضمن هذه المجموعة الحدود اليومية وحدود الدقيقة نفسها. تشمل الأمثلة الشائعة ما يلي:
  • تجميع جميع عمليات القراءة للطرق والموارد ذات الصلة، مثل 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 باسم مجموعة التسوّق في أوروبا (رقم تعريف الحساب: 10001) إدراج نطاقات CSS المرتبطة بها. من خلال المصادقة باستخدام بيانات الاعتماد الخاصة به لإجراء طلب البيانات من واجهة برمجة التطبيقات هذا، يتم استهلاك الحصة مباشرةً من مجموعة حصص مجموعة Shopping في أوروبا.
  • يتم التحقّق من صحة نطاق CSS TopDeals CSS (رقم تعريف الحساب: 20002) من أجل استدعاء طريقة تستهدف أحد حسابات التجّار المرتبطة (accounts/30003) لتعيين تصنيف. يتم استهلاك الحصة من مجمّع الحصص الخاص بخدمة TopDeals 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 ضِمن حصة حسابك المتعدّد العملاء.