النتائج المقسمة إلى صفحات

نتناول أساسيات مصطلحات واجهة Graph API وبنيتها في قسم نظرة عامة على واجهة Graph API. يتناول هذا المستند مزيدًا من التفاصيل حول النتائج من طلبات واجهة API.

التنقل عبر النتائج المقسمة إلى صفحات

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

تقسيم الصفحات استنادًا إلى المؤشر

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

عند قراءة عنصر ربط يدعم تقسيم الصفحات استنادًا إلى المؤشر، ستظهر لك استجابة JSON التالية:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

تدعم عناصر الربط التي تم تقسيم الصفحات بها استنادًا إلى المؤشر المعلمات التالية:

• before : هذا هو المؤشر الذي يشير إلى بداية صفحة البيانات التي تم إرجاعها.
• after : هذا هو المؤشر الذي يشير إلى نهاية صفحة البيانات التي تم إرجاعها.
• limit : هذا هو الحد الأدنى لعدد الكائنات التي يمكن إرجاعها. قد يُرجع الاستعلام قيمة أقل من قيمة limit بسبب الفلترة. لا تعتمد على انخفاض عدد النتائج عن قيمة limit عند الإشارة إلى أن استعلامك قد وصل إلى نهاية قائمة البيانات، وحاول الاستفادة من عدم وجود next كما هو موضح أدناه بدلاً من ذلك. فعلى سبيل المثال، إذا قمت بتعيين limit ليكون 10 وتم إرجاع 9 نتائج، فقد يكون هناك المزيد من البيانات المتوفرة ولكن تمت إزالة عنصر واحد بسبب فلترة الخصوصية. وقد يكون لبعض عناصر الربط أيضًا حد أقصى بالقيمة limit، وذلك لأسباب تتعلق بالأداء. في كل الحالات، تُرجع واجهة API روابط تقسيم الصفحات الصحيحة.
• next : نقطة نهاية واجهة Graph API التي ستُرجع صفحة البيانات التالية. إذا لم يتم تضمينها، فستكون تلك هي آخر صفحة بيانات. ونتيجة لطريقة عمل تقسيم الصفحات مع إمكانية الرؤية والخصوصية، من المحتمل أن تكون الصفحة فارغة إلا من رابط next الخاص بتقسيم الصفحات. كما يجب إيقاف تقسيم الصفحات عندما لا يظهر رابط next.
• previous : نقطة نهاية واجهة Graph API التي ستُرجع صفحة البيانات السابقة. إذا لم يتم تضمينها، فستكون تلك هي أول صفحة بيانات.

تقسيم الصفحات استنادًا إلى الوقت

يُستخدم تقسيم الصفحات استنادًا إلى الوقت للتنقل عبر بيانات النتائج باستخدام طوابع زمنية بتنسيق Unix تشير إلى أوقات محددة في قائمة البيانات.

عند استخدام نقطة نهاية تستخدم تقسيم الصفحات استنادًا إلى الوقت، ستظهر لك استجابة JSON التالية:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774"
  }
}

تدعم عناصر الربط التي تم تقسيم الصفحات بها استنادًا إلى الوقت المعلمات التالية:

• until : طابع زمني بتنسيق Unix أو قيمة بيانات strtotime تشير إلى نهاية نطاق البيانات المستندة إلى الوقت.
• since : طابع زمني بتنسيق Unix أو قيمة بيانات strtotime تشير إلى بداية نطاق البيانات المستندة إلى الوقت.
• limit : هذا هو الحد الأدنى لعدد الكائنات التي يمكن إرجاعها. قد يُرجع الاستعلام قيمة أقل من قيمة limit بسبب الفلترة. لا تعتمد على انخفاض عدد النتائج عن قيمة limit عند الإشارة إلى أن استعلامك قد وصل إلى نهاية قائمة البيانات، وحاول الاستفادة من عدم وجود next كما هو موضح أدناه بدلاً من ذلك. فعلى سبيل المثال، إذا قمت بتعيين limit ليكون 10 وتم إرجاع 9 نتائج، فقد يكون هناك المزيد من البيانات المتوفرة ولكن تمت إزالة عنصر واحد بسبب فلترة الخصوصية. وقد يكون لبعض عناصر الربط أيضًا حد أقصى بالقيمة limit، وذلك لأسباب تتعلق بالأداء. في كل الحالات، تُرجع واجهة API روابط تقسيم الصفحات الصحيحة.
• next : نقطة نهاية واجهة Graph API التي ستُرجع صفحة البيانات التالية.
• previous : نقطة نهاية واجهة Graph API التي ستُرجع صفحة البيانات السابقة.

تقسيم الصفحات استنادًا إلى التعويض

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

تدعم عناصر الربط التي تم تقسيم الصفحات بها استنادًا إلى التعويض المعلمات التالية:

• offset : تعوض هذه المعلمة بداية كل صفحة حسب العدد المحدد.
• limit : هذا هو الحد الأدنى لعدد الكائنات التي يمكن إرجاعها. قد يُرجع الاستعلام قيمة أقل من قيمة limit بسبب الفلترة. لا تعتمد على انخفاض عدد النتائج عن قيمة limit عند الإشارة إلى أن استعلامك قد وصل إلى نهاية قائمة البيانات، وحاول الاستفادة من عدم وجود next كما هو موضح أدناه بدلاً من ذلك. فعلى سبيل المثال، إذا قمت بتعيين limit ليكون 10 وتم إرجاع 9 نتائج، فقد يكون هناك المزيد من البيانات المتوفرة ولكن تمت إزالة عنصر واحد بسبب فلترة الخصوصية. وقد يكون لبعض عناصر الربط أيضًا حد أقصى بالقيمة limit، وذلك لأسباب تتعلق بالأداء. في كل الحالات، تُرجع واجهة API روابط تقسيم الصفحات الصحيحة.
• next : نقطة نهاية واجهة Graph API التي ستُرجع صفحة البيانات التالية. إذا لم يتم تضمينها، فستكون تلك هي آخر صفحة بيانات. ونتيجة لطريقة عمل تقسيم الصفحات مع إمكانية الرؤية والخصوصية، من المحتمل أن تكون الصفحة فارغة إلا من رابط next الخاص بتقسيم الصفحات. كما يجب إيقاف تقسيم الصفحات عندما لا يظهر رابط next.
• previous : نقطة نهاية واجهة Graph API التي ستُرجع صفحة البيانات السابقة. إذا لم يتم تضمينها، فستكون تلك هي أول صفحة بيانات.

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

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

{
  "error": {
    "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint",
    "type": "OAuthException",
    "code": 100
  }
}

الخطوات التالية

والآن بعد أن أصبحت على معرفة أكثر بواجهة Graph API، تفضل بزيارة دليل أداة مستكشف Graph لاستكشاف Graph دون كتابة رمز برمجي، والتعرف على الاستخدامات الشائعة لعرض المهام الأكثر شيوعًا التي يتم تنفيذها، ومجموعات SDK المتوفرة.