الحصص

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

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

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

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

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

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

  أمثلة:

  • تريد مجموعة CSS باسم مجموعة التسوّق في أوروبا (رقم تعريف الحساب: 10001) عرض نطاقات CSS المرتبطة بها. من خلال المصادقة باستخدام بيانات الاعتماد الخاصة بها لإجراء طلب بيانات من واجهة برمجة التطبيقات هذا، يتم استهلاك الحصة مباشرةً من مجموعة الحصص الخاصة بـ مجموعة التسوّق في أوروبا.
  • يُصادق نطاق CSS أفضل عروض CSS (رقم تعريف الحساب: 20002) لاستدعاء طريقة تستهدف أحد حسابات التجّار المرتبطة به (accounts/30003) لتعيين تصنيف. يتم استهلاك الحصة من أفضل عروض 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 من المستخدم الذي يجري الطلب (وليس رقم تعريف حساب Merchant Center)، ولا تظهر في بيانات التشخيص العادية. يتم احتساب listSubaccounts ضمن حصة حسابك المتعدّد العملاء.