الحصص

يسرد هذا المستند الحصص التي تنطبق على 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 API العادية. إذا كان لديك حساب بامتيازات متقدّمة، ننصحك باستخدام طريقة accounts.listSubaccounts التي يتم احتسابها ضمن حصة حساباتك بامتيازات متقدّمة.
• طرق Issueresolution: يتم احتساب هذه الطرق دائمًا ضمن الحصة المخصّصة للحساب الذي يتم طلب حلّ مشاكله، حتى إذا كان حساب مختلف يصادق على الطلب.

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

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

  أمثلة:

  • تريد مجموعة CSS باسم Europe Shopping Group (رقم تعريف الحساب: 10001) إدراج نطاقات CSS المرتبطة بها. من خلال المصادقة باستخدام بيانات الاعتماد الخاصة بها لإجراء طلب البيانات من واجهة برمجة التطبيقات هذا، يتم استهلاك الحصة مباشرةً من مجموعة حصص Europe Shopping Group.
  • يصادق نطاق 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)، استخدِم التراجع الأسي (زيادة أوقات الانتظار) وأضِف "تذبذبًا" (تأخير عشوائي). يمنع Jitter "عواصف إعادة المحاولة"، حيث تحاول عدة مثيلات للعميل إعادة المحاولة في الوقت نفسه، ما يؤدي إلى زيادة التحميل على الخادم مرة أخرى.
• الالتزام بتلميحات إعادة المحاولة: إذا كان الردّ من واجهة برمجة التطبيقات يتضمّن تفاصيل أو عناوين لإعادة المحاولة، استخدِمها لتحديد وقت استئناف الطلبات.

تقليل الطلبات المتكررة

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

التعرّف على التسلسل الهرمي للحصص والاستثناءات

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