تطبيقك تم تقييده. ماذا الآن؟
كل مطور Shopify مر بهذه التجربة. تطبيقك يعمل بسلاسة، يزامن المنتجات، يعالج الطلبات، يحدث المخزون، ثم يتوقف فجأة. يظهر كود الحالة 429 في سجلاتك. "طلبات كثيرة جدًا." تطبيقك وصل إلى حد معدل API في Shopify، وحتى تتعامل معه بشكل صحيح، مستخدموك عالقون في الانتظار. تحديد المعدل هو أحد أهم المفاهيم لأي مطور يبني على منصة Shopify، ومع ذلك يبقى من أقل المفاهيم فهمًا. الحدود تختلف بشكل كبير بين الخطط وبين أنواع API وبين أنماط العمليات — والخطأ في التفاصيل يمكن أن يعني الفرق بين تطبيق يتوسع بسلاسة وآخر ينهار تحت الحمل.
يفصّل هذا الدليل نظام تحديد المعدل في Shopify بشكل شامل. نغطي كل مستوى من مستويات الخطط، وآليات التقييد في كل من REST و GraphQL، والقواعد الخاصة بـ Storefront API، والتقنيات التي يستخدمها المطورون ذوو الخبرة لزيادة الإنتاجية مع البقاء ضمن الحدود، وأفضل الممارسات التي ستبقي تطبيقك يعمل بسلاسة مع نمو تجارك.
حدود المعدل حسب الخطة: الأرقام المهمة
حدود معدل Shopify ليست موحدة عبر جميع التجار. تختلف بشكل كبير بناءً على خطة اشتراك التاجر، وفهم هذه الاختلافات أمر حاسم لبناء تطبيقات تعمل جيدًا لجميع مستخدميك. بالنسبة لـ GraphQL Admin API، وهو الواجهة الرئيسية لمعظم تطوير تطبيقات Shopify، تتوزع الحدود كالتالي: تجار خطة Basic يحصلون على 50 نقطة في الثانية من سعة تكلفة الاستعلام. تجار الخطة Standard يحصلون على 100 نقطة في الثانية. تجار خطة Advanced يحصلون على 200 نقطة في الثانية. وتجار Shopify Plus — المستوى المؤسسي — يحصلون على 500 نقطة في الثانية، عشرة أضعاف تخصيص خطة Basic.
لهذه الاختلافات تداعيات عميقة على تصميم التطبيق. مزامنة مخزون تعمل بشكل مريح ضمن حدود المعدل لتاجر Plus قد تصطدم باستمرار بالتقييد لتاجر على خطة Basic. استيراد كتالوج منتجات يكتمل في دقائق على خطة Advanced قد يستغرق ساعات على خطة Basic إذا لم تُدار حدود المعدل بعناية. يحتاج تطبيقك إلى تكييف سلوكه بناءً على خطة التاجر.
REST API: خوارزمية الدلو المتسرب
يستخدم REST Admin API في Shopify خوارزمية الدلو المتسرب لتحديد المعدل. المفهوم بسيط: تخيل دلوًا يمكنه حمل عدد معين من الطلبات. كل استدعاء API تقوم به يضيف قطرة إلى الدلو. الدلو "يتسرب" بمعدل ثابت، يستنزف الطلبات بمرور الوقت. طالما تضيف قطرات أبطأ من تسرب الدلو، فلن يفيض دلوك أبدًا ولن يتم تقييدك. لكن إذا أرسلت طلبات أسرع مما يمكن للدلو أن يستنزف، سيمتلئ في النهاية وسيتم رفض الطلبات الجديدة بكود حالة 429.
لخطط Shopify القياسية، يحمل الدلو 40 طلبًا ويتسرب بمعدل 2 طلب في الثانية. هذا يعني أنه يمكنك إرسال حتى 40 طلبًا سريعًا دفعة واحدة، لكن إنتاجيتك المستدامة محدودة بـ 2 طلب في الثانية. لتجار Shopify Plus، الدلو أكبر بكثير — يحمل 400 طلب بمعدل تسرب 20 طلبًا في الثانية. هذه الزيادة بعشرة أضعاف في كل من حجم الدلو ومعدل التسرب هي أحد أهم الأسباب التقنية لترقية التجار إلى Plus.
كل استجابة REST API تتضمن ترويسات تخبرك بالحالة الحالية لدلوك. ترويسة X-Shopify-Shop-Api-Call-Limit تُظهر عدد الطلبات الموجودة حاليًا في دلوك مقابل السعة القصوى — على سبيل المثال، "32/40" تعني أنك استخدمت 32 من 40 فتحة متاحة. التطبيقات الذكية تراقب هذه الترويسات في كل استجابة وتعدل معدل طلباتها ديناميكيًا.
GraphQL Admin API: التقييد القائم على التكلفة
يستخدم GraphQL Admin API نهج تحديد معدل مختلف جذريًا: التقييد القائم على التكلفة. بدلًا من عد الطلبات الفردية، يحدد Shopify تكلفة لكل استعلام بناءً على تعقيد البيانات المطلوبة. الاستعلامات البسيطة التي تجلب كائنًا واحدًا قد تكلف 1-2 نقطة فقط. الاستعلامات المعقدة التي تطلب قوائم كائنات مع اتصالات متداخلة وحقول متعددة يمكن أن تكلف مئات النقاط. التكلفة الفعلية للاستعلام تُعاد في كل استجابة تحت حقل extensions.cost.
لهذا النهج القائم على التكلفة تداعيات مهمة على كيفية هيكلة استعلاماتك. استعلام يجلب 100 منتج مع متغيراتها وصورها وبياناتها الوصفية سيكلف أكثر بكثير من استعلام يجلب 10 منتجات بعناوينها وأسعارها فقط. المطورون الأذكياء يحسنون استعلاماتهم لطلب الحقول التي يحتاجونها فعليًا فقط، ويستخدمون ترقيم الصفحات للتحكم في حجم استعلامات القوائم. التكلفة القصوى للاستعلام الواحد هي 1,000 نقطة.
معدل الاستعادة — مدى سرعة تجدد سعتك — يتبع نفس مستويات الخطط. دلو تاجر خطة Basic يُعاد ملؤه بـ 50 نقطة في الثانية، بينما دلو تاجر Plus يُعاد ملؤه بـ 500 نقطة في الثانية. عندما يتم تقييد تطبيقك، تتضمن الاستجابة ترويسة Retry-After تشير إلى عدد الثواني التي يجب انتظارها قبل إعادة المحاولة. تنفيذ منطق إعادة محاولة صحيح مع تراجع أسي وعشوائية ضروري للتعامل مع التقييد بسلاسة.
Storefront API: عالم مختلف تمامًا
يعمل Storefront API تحت نموذج تحديد معدل مختلف تمامًا يفاجئ العديد من المطورين. على عكس Admin API، لا يملك Storefront API حدًا لمعدل يعتمد على عدد الطلبات. لن تتلقى خطأ 429 لأنك أرسلت طلبات كثيرة في الثانية. بدلًا من ذلك، يُحمى Storefront API بواسطة تقييد البنية التحتية العالمية لـ Shopify، الذي يركز على عرض النطاق الترددي الإجمالي وحمل الخادم بدلًا من العد لكل طلب. هذا منطقي بالنظر إلى غرض Storefront API — فهو يخدم حركة مرور العملاء حيث أنماط الوصول المتقطعة أثناء العروض والتخفيضات طبيعية ومتوقعة.
مع ذلك، هذا لا يعني أن Storefront API لديه سعة غير محدودة. أنماط الاستعلام العدوانية للغاية أو الحمولات الكبيرة جدًا أو الاستعلامات التي تطلق حسابات مكلفة على جانب الخادم قد يتم تقييدها على مستوى البنية التحتية. الخلاصة العملية هي أنه بينما لا تحتاج إلى تنفيذ نفس منطق ضبط الطلبات الدقيق الذي تحتاجه لـ Admin API، لا تزال بحاجة إلى كتابة استعلامات فعالة والتعامل مع احتمال التقييد في كود معالجة الأخطاء.
التعامل مع أخطاء 429: الطريقة الصحيحة
عندما يتلقى تطبيقك كود حالة 429، فإن طريقة استجابته تحدد ما إذا كان مستخدموك سيختبرون توقفًا قصيرًا أو فشلًا كارثيًا. القاعدة الأهم هي احترام ترويسة Retry-After. هذه الترويسة، المضمنة في كل استجابة 429، تخبرك بالضبط بعدد الثواني التي يجب انتظارها قبل إرسال طلب آخر. تجاهل هذه الترويسة وإعادة المحاولة فورًا سيزيد الأمر سوءًا فقط.
النهج الموصى به يجمع بين ترويسة Retry-After والتراجع الأسي مع العشوائية. التراجع الأسي يعني زيادة وقت الانتظار مع كل محاولة فاشلة متتالية — على سبيل المثال، الانتظار ثانية واحدة بعد أول 429، ثم ثانيتين، ثم 4 ثوانٍ، وهكذا. تضيف العشوائية مكونًا عشوائيًا لوقت الانتظار لمنع مشكلة "القطيع المزدحم"، حيث تعيد جميع نسخ تطبيقك المحاولة في نفس اللحظة بالضبط وتطلق جولة أخرى من التقييد.
إلى جانب التعامل التفاعلي مع 429، فإن إدارة حدود المعدل الاستباقية هي السمة المميزة لتطبيقات Shopify المبنية بإتقان. راقب ترويسات استجابة API باستمرار، وتتبع معدل استهلاكك مقابل سعتك المتاحة، وقيّد طلباتك قبل أن يفعل Shopify ذلك نيابةً عنك.
Bulk Operations API: تجاوز حدود المعدل للبيانات الكبيرة
للعمليات التي تتضمن مجموعات بيانات كبيرة — مزامنة الكتالوج الكاملة، تصدير الطلبات الشامل، تحديثات المخزون المجمعة — يقدم Shopify واجهة Bulk Operations API، التي تتجاوز فعليًا نظام تحديد المعدل القياسي. بدلًا من إجراء آلاف استدعاءات API الفردية لجلب أو تحديث السجلات واحدًا تلو الآخر، تقدم عملية مجمعة واحدة تصف البيانات التي تحتاجها. يعالج Shopify العملية بشكل غير متزامن على خوادمه ويوفر رابط ملف JSONL عندما تكون النتائج جاهزة للتنزيل.
اعتبارًا من أوائل عام 2026، يدعم Bulk Operations API حتى 5 عمليات متزامنة، بزيادة من الحد السابق البالغ عملية متزامنة واحدة. هذا تحسين كبير للتطبيقات التي تحتاج إلى تنفيذ أنواع متعددة من العمليات المجمعة في وقت واحد. المقايضة هي أن العمليات المجمعة ليست فورية؛ حسب حجم مجموعة البيانات، يمكن أن تستغرق من ثوانٍ إلى ساعات لإتمامها. لكن لعمليات البيانات واسعة النطاق، تحسين الإنتاجية هائل مقارنة بترقيم الصفحات عبر API القياسي ضمن حدود المعدل.
التطبيقات الذكية تستخدم Bulk Operations API كآلية جلب البيانات الأساسية للمزامنة الأولية والتحديثات الكاملة الدورية، بينما تستخدم API القياسي للتحديثات التدريجية في الوقت الفعلي المدفوعة بـ webhooks. هذا النهج المختلط يزيد الإنتاجية مع الحفاظ على الاستجابة الفورية.
Webhooks مقابل الاستطلاع: تقليل استهلاك API بنسبة 40-60%
واحدة من أكثر الاستراتيجيات فعالية للبقاء ضمن حدود المعدل هي تقليل عدد استدعاءات API التي يقوم بها تطبيقك في المقام الأول. Webhooks هي الأداة الأساسية لتحقيق ذلك. بدلًا من استطلاع API الخاص بـ Shopify على فترات منتظمة للتحقق من الطلبات الجديدة أو تغييرات المنتجات أو تحديثات المخزون، تسجل webhooks تخبر Shopify بإرسال إشعارات لتطبيقك عند حدوث أحداث. هذا يقضي على الغالبية العظمى من استدعاءات API "لم يتغير شيء" التي تولدها معماريات الاستطلاع.
عمليًا، التحول من معمارية قائمة على الاستطلاع إلى معمارية مدفوعة بـ webhooks يقلل استهلاك API بنسبة 40-60%، حسب حالة الاستخدام المحددة وتكرار التغييرات. مزامنة منتجات كانت تتطلب سابقًا استطلاعًا كل 5 دقائق — مما يعني 288 استدعاء API يوميًا لاكتشاف التغييرات فقط — يمكن استبدالها بـ webhooks تُطلق فقط عند حدوث تغييرات فعلية.
تجدر الإشارة إلى أن Shopify أوقفت تنسيق اشتراك webhook القائم على REST في أكتوبر 2024، ويجب إنشاء جميع اشتراكات webhook الجديدة باستخدام GraphQL API. تنسيق حمولة webhook وآلية التسليم تبقى كما هي، لكن واجهة الإدارة لإنشاء وتحديث وقائمة اشتراكات webhook أصبحت الآن عبر GraphQL فقط. تأكد من تحديث تطبيقك لاستخدام نقاط نهاية إدارة الاشتراكات عبر GraphQL.
أفضل الممارسات لتطبيقات Shopify في الإنتاج
بناء تطبيقات Shopify جاهزة للإنتاج تتعامل مع حدود المعدل بسلاسة يتطلب مزيجًا من القرارات المعمارية وتفاصيل التنفيذ. أولًا، استخدم دائمًا GraphQL بدلًا من REST عندما يكون ذلك ممكنًا. نموذج التقييد القائم على التكلفة يمنحك سلوكًا أكثر قابلية للتنبؤ وإنتاجية أفضل للعمليات المعقدة. ثانيًا، نفذ قائمة انتظار طلبات مع تحكم معدل تكيفي يراقب ترويسات الاستجابة ويعدل الإنتاجية في الوقت الفعلي. ثالثًا، استخدم webhooks كآلية اكتشاف التغيير الأساسية.
رابعًا، استفد من Bulk Operations API لأي عملية تتعامل مع أكثر من بضع مئات من السجلات. خامسًا، نفذ أنماط قاطع الدارة التي تخفض الوظائف بسلاسة عند الوصول المتكرر لحدود المعدل. سادسًا، خزّن استجابات API بقوة — بيانات المنتجات والمجموعات وتكوين المتجر نادرًا ما تتغير ويمكن تخزينها مؤقتًا لدقائق أو حتى ساعات. سابعًا، صمم نموذج بياناتك لتقليل الحاجة لاستدعاءات API عن طريق تخزين البيانات ذات الصلة محليًا والمزامنة تدريجيًا عبر webhooks.
كيف يمكن لـ ITX E-commerce Solutions مساعدتك
في ITX E-commerce Solutions، نبني تكاملات Shopify وتطبيقات مخصصة مصممة من الأساس للتعامل مع حدود المعدل بذكاء. سواء كنت تحتاج تطبيقًا مخصصًا يزامن المخزون عبر قنوات بيع متعددة، أو أداة ترحيل تنقل كتالوجك من منصة أخرى إلى Shopify، أو تكاملًا مع نظام ERP أو نظام إدارة المستودعات الخاص بك، يصمم فريقنا معماريات تزيد إنتاجية API مع البقاء بشكل مريح ضمن حدود معدل Shopify. ننفذ قوائم الانتظار المناسبة والتقييد التكيفي والتحديثات المدفوعة بـ webhooks والعمليات المجمعة لضمان أن تكاملاتك سريعة وموثوقة وقابلة للتوسع عبر كل مستوى من خطط Shopify. تواصل معنا لمناقشة متطلبات تكامل Shopify الخاصة بك.