تقييد معدلات الاستدعاء في Graph API

تضع عملية تقييد معدلات الاستدعاء حدود لعدد مرات الاستدعاء التي يمكن أن تجريها API خلال فترة زمنية معينة. يتم فرض حدود معدلات الاستدعاء على كل تطبيق.

قد يتم تعطيل التطبيقات التي تتجاوز معدلات الاستدعاء المحددة لها بشكل زائد أو بشكل دائم.

من المفترض ألا يتم التعرض لتقييد معدلات الاستدعاء في Facebook Graph API إلا في ظروف نادرة. ويتناول هذا المستند حالات تعيين حد لمعدلات الاستدعاء تلك وكيفية التعامل معها.

هناك نوعان أساسيان لتقييد معدلات الاستدعاء التي يمكن أن تواجهها التطبيقات: هما تقييد معدلات الاستدعاء على مستوى التطبيق وتقييد معدلات الاستدعاء على مستوى الصفحة.

تقييد معدلات الاستدعاء على مستوى التطبيق

تطبق حدود تقييد معدلات الاستدعاء هذه على الاستدعاءات التي تم إجراؤها باستخدام رمز وصول بخلاف رمز وصول صفحة.

يتم تقييد كل استدعاءات واجهة API التي تصدر عن التطبيق بعد تجاوز الحد الأقصى لمعدلات الاستدعاء وتفشل ويتم عرض رسالة الخطأ error code = 4, CodedException. ثم تبدأ الاستدعاءات في النجاح مرة أخرى بعد تراجع الاستخدام خلال الساعة الماضية إلى أقل من الحد الأقصى المسموح به. يتم حساب الحد الأقصى استنادًا إلى فترة ساعة دورية، ويمكن التعرف على النسبة المئوية للاستخدام الحالي في لوحة معلومات التطبيق.

لوحة معلومات تقييد معدلات الاستدعاء

توفر لك أداة تقييد معدلات الاستدعاء معلومات عن مدى اقتراب تطبيقك من التعرض للتقييد. يمكنك عرض معلومات عن الحد الأقصى لمعدلات الاستدعاء التي تؤثر في تطبيقاتك باستخدام اثنين من المخططات في لوحة معلومات التطبيق.

  • يعرض أحد المخططين الاستخدام الحالي الذي يؤثر على استجابات واجهة Graph API التي يتم عرضها. وتكون هذه بمثابة تمثيل بصري لقيمة العنوان التي يتم عرضها في طلبات واجهة Graph API.
مخطط لتطبيق بلغ الحد الأقصى لمعدلات الاستدعاء
  • يعرض المخطط الثاني سجل تقييد معدلات الاستدعاء. يمكنك اختيار عرض البيانات عن مدة 24 ساعة الماضية أو 7 أيام سابقة. يمكنك النقر على أي نموذج في مخطط السجل التاريخي لعرض مزيد من التفاصيل عن الاستخدام، بما في ذلك التقسيم حسب الشهور. لا يتوفر لكل التطبيقات بيانات سجل تاريخية، لأن وجود بيانات سجل يعتمد على كمية الاستدعاءات. تزيد احتمالية توفر بيانات سجل تاريخية للتطبيقات التي تحقق كمية كبيرة من الاستدعاءات.
مخطط السجل التاريخي لتطبيق يتجاوز الحد الأقصى لمعدلات الاستدعاء خلال مدة 24 ساعة الماضية

الحدود

يبلغ الحد الأقصى لعدد الاستدعاءات التي يتمكن تطبيقك من إجرائها في الساعة ضعف عدد المستخدمين 200 مرة. ولا يُعد هذا الحد مرتبطًا بكل مستخدم على حدة؛ حيث يتمكن أي مستخدم من إجراء أكثر من 200 استدعاء في الساعة، طالما كان إجمالي الاستدعاءات لكل المستخدمين لا يتجاوز الحد الأقصى المسموح به للتطبيق. على سبيل المثال، إذا كان هناك 100 مستخدم لتطبيقك، يمكن أن يجري التطبيق 20000 استدعاء في الساعة. إلا أن أفضل 10 مستخدمين من بين المستخدمين الأكثر تفاعلاً يمكنهم إجراء 19000 من هذه الاستدعاءات.

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

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

تنبيهات:

  • لا تخضع جميع استدعاءات API لحدود تقييد معدلات الاستدعاء، ولذلك قد لا يطابق عدد الاستدعاءات التي تقوم بإجرائها عدد الاستدعاءات التي تشاهدها في أداة تقييد معدلات الاستدعاء.
  • نقوم بالاستدعاءات أيضًا استنادًا إلى الوقت المستغرق في وحدة المعالجة المركزية والوقت الإجمالي. قد تتسبب نقاط النهاية التي تتطلب الكثير من المعالجة في بلوغ تطبيقك للحد الأقصى، على الرغم من عدم بلوغ الحد الأقصى لكمية الاستدعاءات. نادرًا ما تبلغ التطبيقات وقت وحدة المعالجة المركزية وإجمالي الحد الأقصى للوقت، باستثناء بعض نقاط النهاية المتخصصة. يمكنك التعرف على المعلومات المتعلقة بنقاط النهاية التي تستخدم كمية كبيرة من وقت وحدة المعالجة المركزية أو إجمالي الوقت في مخطط السجل التاريخي، إذا كان متوفرًا.
  • قد تستخدم API رؤى الإعلانات وAPI التسويق مجموعة مختلفة من حدود تقييد معدلات الاستدعاء. يرجى الاطلاع على مستند تقييد معدلات استدعاء API التسويق على الرابط https://developers.facebook.com/docs/marketing-api/api-rate-limiting لمزيد من المعلومات حول API التسويق.

التوصيات

لتجنب تقييد معدلات الاستدعاء، يجب:

  • توزيع الاستعلامات بالتساوي بين فترتين زمنيتين لتجنب إرسال حركة البيانات كارتفاعات مفاجئة.
  • استخدام مرشحات لتقييد حجم استجابة البيانات وتجنب الاستدعاءات التي تطلب بيانات متداخلة.
  • استخدام عنوان تقييد معدلات الاستدعاء لموازنة حجم الاستدعاءات ديناميكيًا.

عنوان تقييد معدلات الاستدعاء

تتضمن كل الاستجابات للاستدعاءات التي تتم إلى واجهة Graph API عنوان X-App-Usage HTTP. يحتوي هذا العنوان على النسبة المئوية الحالية لاستخدام تطبيقك. تكون هذه النسبة مساوية لنسبة الاستخدام المعروض في مخططات تقييد معدلات الاستدعاء. يمكن استخدام هذا الرقم في موازنة حمولة الاستدعاء تجنبًا للتعرض للتقييد.

عنوان تقييد معدلات الاستدعاء عبارة عن سلسلة بتنسيق JSON بالشكل التالي:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

قيم x وy وz عبارة عن أرقام صحيحة تمثل نسبة استخدام قيم أدوات القياس. عند تجاوز عدد أدوات القياس هذه 100، يتم تقييد معدلات الاستدعاء للتطبيق.

تقييد معدلات الاستدعاء على مستوى الصفحة

تطبق حدود تقييد معدلات الاستدعاء هذه على الاستدعاءات التي تم إجراؤها باستخدام رمز وصول صفحة. يتلقى تطبيقك رمز الخطأ 32 عند بلوغ هذه الحدود.

يوفر منشور المدونة على https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/ شرح تفصيلي لتقييد معدلات الاستدعاء على مستوى الصفحة.

لوحة معلومات تقييد معدلات الاستدعاء

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

الحدود

يتم فرض معدلات الاستدعاء على كل صفحة بدلاً من التطبيق. ستوفر أداة تقييد معدلات الاستدعاء معلومات عن عدد التطبيقات التي تستخدم رمز وصول الصفحة ومدى اقتراب الصفحة من التعرض للتقييد. اضغط على أي نموذج للحصول على مزيد من التفاصيل عن أنواع الاستخدام.

يمثل عدد الأشخاص الذين يتفاعلون يوميًا باستخدام الصفحة العدد الفريد للأشخاص الذين تفاعلوا مع الصفحة خلال فترة 24 ساعة. يتمثل التفاعل مع الصفحة في النقر عليها أو على محتوى الصفحة.

يتم استخدام عدد الأشخاص الذين قاموا بالتفاعل خلال فترة 24 ساعة الماضية في حساب حدود تقييد معدلات الاستدعاء لفترة 24 ساعة الحالية.

يمكن بشكل إجمالي إجراء 4800 استدعاءً للمستخدمين الذين يتفاعلون يوميًا نيابةً عن الصفحة في كل 24 ساعة بشكل مجمع. على سبيل المثال، إذا كان لدى الصفحة 100 مستخدم يتفاعلون يوميًا، يمكن إجراء 480000 استدعاء نيابة عن الصفحة في فترة 24 ساعة. وفترة 24 ساعة هذه هي فترة متغيرة يتم تحديثها كل بضعة دقائق. وتقييد معدلات الاستدعاء يتم على مستوى كل صفحة، وبالتالي يمكن لمستخدم واحد إجراء 400000 استدعاء من هذه الاستدعاءات ويمكن للمستخدمين الآخرين إجراء 80000 استدعاء. إذا وصلت صفحتك لحد تقييد معدلات الاستدعاء، فلا يتم تقييد إلا الاستدعاءات الصادرة من تطبيقك باستخدام رمز وصول هذه الصفحة. وهذا يعني أن يمكن أن يستمر تطبيقك في العمل بشكل طبيعي في الاستدعاءات الأخرى.

يتم حساب عدد الاستدعاءات إلى صفحتك كعدد تقديري للاستدعاءات باستخدام رمز الوصول إلى صفحتك عن كل يوم. ويمكن إجراء تقييد معدلات استدعاء في الصفحات التي تحتوي على عدد أكبر من الاستدعاءات في اليوم على نحو أكثر دقة من الصفحات التي تحتوي على أعداد قليلة من الاستدعاءات في اليوم. وقد تواجه الصفحات التي تحتوي على أعداد استدعاءات قليلة في اليوم مشكلات عند تقييد معدل الاستدعاء.

تنبيهات:

  • لا تخضع جميع استدعاءات API لحدود تقييد معدلات الاستدعاء، ولذلك قد لا يطابق عدد الاستدعاءات التي تقوم بإجرائها عدد الاستدعاءات التي تشاهدها في أداة تقييد معدلات الاستدعاء.
  • يقيد فيسبوك الاستدعاءات أيضًا استنادًا إلى الوقت المستغرق في وحدة المعالجة المركزية والوقت الإجمالي. انقر على الرسم البياني في أداة تقييد معدلات الاستدعاء في لوحة المعلومات الخاصة بك للحصول على التفاصيل.
  • قد تستخدم API رؤى الإعلانات وAPI التسويق مجموعة مختلفة من حدود تقييد معدلات الاستدعاء. يرجى الاطلاع على مستند تقييد معدلات استدعاء API التسويق لمزيد من المعلومات حول API التسويق.

التوصيات

وبمجرد تقييد الصفحة، يظهر خطأ للمستدعي عند إجراء عمليات استدعاء لاحقة بالرمز error code = 32, CodedException. قد يستغرق الأمر مدة تصل إلى ساعة ليتم قبول الطلبات لهذه الصفحة مرة أخرى.

لتجنب تقييد معدلات الاستدعاء، يجب:

  • توزيع الاستعلامات بالتساوي بين فترتين زمنيتين لتجنب إرسال حركة البيانات كارتفاعات مفاجئة.
  • استخدام مرشحات لتقييد حجم استجابة البيانات وتجنب الاستدعاءات التي تطلب بيانات متداخلة.
  • استخدام عنوان تقييد معدلات الاستدعاء لموازنة حجم الاستدعاءات ديناميكيًا.

عنوان تقييد معدلات الاستدعاء

إذا كان يتم إجراء عمليات استدعاء نيابة عن الصفحة تكفي لأن يتم من خلال نظامنا تقييد معدلات الاستدعاء لها، فإننا نعرض عنوان HTTP X-Page-Usage. يحتوي هذا العنوان على النسبة المئوية الحالية لاستخدام الصفحة. إذا كنت تقوم بإجراء عمليات استدعاء باستخدام رمز وصول الصفحة، فإنك ستحصل على القيمة X-Page-Usage لهذه الصفحة فقط. تكون هذه النسبة المئوية مساوية للاستخدام المعروض على الرسم البياني لهذه الصفحة. يمكن استخدام هذا الرقم في موازنة حمولة الاستدعاء تجنبًا للتعرض للتقييد.

عنوان تقييد معدلات الاستدعاء عبارة عن سلسلة بتنسيق JSON بالشكل التالي:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

قيم x وy وz عبارة عن أرقام صحيحة تمثل نسبة استخدام قيم أدوات القياس. عند تجاوز عدد أدوات القياس هذه 100، يتم تقييد معدلات الاستدعاء للتطبيق.

تقييد معدلات الاستدعاء على مستوى الحساب

تطبق حدود تقييد معدلات الاستدعاء هذه على الاستدعاءات التي يتم إجراؤها باستخدام رموز وصول المستخدم. يتلقى تطبيقك رمز رسالة الخطأ 17 إذا تم بلوغ هذا الحد. يحدث ذلك في حالة قيام حساب مستخدم محدد بإجراء عدد كبير جدًا من عمليات الاستدعاء إلى واجهة API.

ملاحظة:

وقد يتضمن ذلك عمليات استدعاء المستخدم التي قام بها عبر العديد من التطبيقات وليس تطبيقك فقط.

عندما يخضع المستخدم لتقييد معدلات الاستدعاء، يتم تقييد استدعاءات واجهة API التي يقوم بها المستخدم.

لتجنب تقييد معدلات الاستدعاء، يجب:

لا يوجد أي شيء يمكنك القيام به لتجنب حدوث ذلك. يقوم المستخدم بإجراء عدد كبير جدًا من الاستدعاءات (ربما من خلال تطبيقات أخرى) وبالتالي يخضع لتقييد معدلات الاستدعاء. وعلى الرغم من ذلك، إذا كان ذلك يحدث لعدد كبير من مستخدمي تطبيق محدد، فغالبًا ما يكون السبب في ذلك استدعاءات واجهة API التي تتم من خلال ذلك التطبيق. في هذه الحالة، يجب عليك الحد من استدعاءاتهم أو توزيعها بالتساوي بشكل أفضل.

الأسئلة المتكررة

ما الذي نعتبره استدعاء API؟

تسهم كل الاستدعاءات في بلوغ حد تقييد معدلات الاستدعاء، وليس فقط طلبات HTTPS API الفردية. على سبيل المثال، يمكنك إجراء استدعاء API واحد وتحديد عدة معرفات، لكن سيتم احتساب كل معرف كاستدعاء API منفصل، حتى إذا كنت تجري طلب HTTPS API واحد فقط.

لشرح هذا المفهوم، اطلع على الأمثلة التالية:

نماذج الطلب (الطلبات) عدد استدعاءات API

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

إذا كنت تريد معالجة عدة كائنات باستخدام المعرف، نوصي بشدة باستخدام الأسلوب الثاني لأنه يحسِّن أداء استجابات API دون زيادة عدد الاستدعاءات وذلك تجنبًا لبلوغ حد تقييد معدلات الاستدعاء.

يمكنك أيضًا استخدام API التجميع لتقديم طلبات مجمعة، ولكن لاحظ أن كل طلب فرعي يشكل استدعاء API منفصل، أو ربما استدعاءات API متعددة في حالة تحديد العديد من المعرفات.

إذا تم تقييد معدلات الاستدعاء من تطبيقك أو صفحتك، ستضاف استدعاءات API التي تواجه أخطاءً متعلقة بتجاوز الحد إلى العدد المحتسب ضمن حد تقييد معدلات الاستدعاء.


ما الخطأ الذي سيواجهه تطبيقي؟
نوع التقييد على الأقل رمز الخطأ

تقييد على مستوى التطبيق

200 استدعاء/لكل شخص/كل ساعة

4

تقييد على مستوى الحساب

غير متوفر

17

تقييد على مستوى الصفحة

4800 استدعاء/لكل شخص/كل 24 ساعة

32

تقييد على مستوى مخصص

غير متوفر

613


يظهر لي رمز الخطأ 613، ما الذي يجب علي القيام به؟

إذا كانت استجابة الخطأ تحتوي على error_subcode 1996، فذلك يعني أن فيسبوك قد لاحظ سلوكًا غير ثابت في كمية الطلبات إلى API التي يقوم بها تطبيقك. إذا كنت أجريت أي تغييرات مؤخرًا لها تأثير على عدد طلبات واجهة API، فقد يظهر لك هذا الخطأ.

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


أقوم بإنشاء خدمة لاستخلاص البيانات، هل هناك شيء آخر يسترعي القلق بشأنه؟

إذا كنت تعمل على إنشاء خدمة تستخلص البيانات، يمكنك الاطلاع على شروط استخلاص البيانات.