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

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

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

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

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

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

يمكنك عرض الرسوم البيانية لنشاط تقييد معدلات الاستدعاء لتطبيقك في لوحة معلومات التطبيق.

الحدود

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

يمكن أن يجري تطبيقك 200 استدعاء في الساعة لكل مستخدم بشكل مجمع. على سبيل المثال، إذا كان هناك 100 مستخدم لتطبيقك، فإن ذلك يعني أنه يمكن أن يجري تطبيقك 20000 استدعاء. وهذا ليس حدًا لكل مستخدم، وبالتالي يمكن لمستخدم واحد إجراء 19000 استدعاء من هذه الاستدعاءات ويمكن للآخرين إجراء 1000 استدعاء. يتم حساب هذا الحد استنادًا إلى عدد الاستدعاءات التي تم إجراؤها في الساعة الماضية.

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

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

تنبيهات:

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

التوصيات

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

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

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

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

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

عنوان تقييد معدلات الاستدعاء عبارة عن سلسلة بتنسيق 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، ما الذي يجب علي القيام به؟

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

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

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