استخدام واجهة Graph API

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

HTTP/1.1

تتوافق كل عمليات نقل البيانات مع HTTP/1.1 وتتطلب كل نقاط النهاية توفر HTTPS. وقمنا أيضًا بتمكين التوجيه includeSubdomains HSTS على facebook.com، ولكن يجب ألا يكون لذلك تأثير سلبي على استدعاءات واجهة Graph API لديك.

عنوان URL للمضيف

غالبًا يتم تمرير كل الطلبات تقريبًا إلى عنوان URL للمضيف graph.facebook.com. ويتمثل الاستثناء الوحيد لذلك في تحميلات الفيديو والتي تستخدم graph-video.facebook.com.

رموز الوصول

تتيح رموز الوصول لتطبيقك إمكانية الوصول إلى واجهة Graph API. وعادة ما تُستخدم للقيام بوظيفتين:

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

تتطلب كل نقاط النهاية في واجهة Graph API توفُّر رمز وصول من نوع ما، ولذلك في كل مرة تقوم فيها بالوصول إلى نقطة نهاية، يجب أن يتضمن طلبك رمز وصول.

طريقة عمل رموز الوصول

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

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

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

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

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

تسجيل دخول فيسبوك

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

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

القراءة

العُقد

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

GET https://graph.facebook.com/820882001277849

سيعرض هذا الطلب الحقول التالية (خصائص العقدة) بشكل افتراضي، ويتم تنسيقها باستخدام JSON:

{
  "name": "Coca-Cola",
  "id": "820882001277849"
}

عناصر الربط

تحتوي العُقد على عناصر الربط، والتي عادة ما تعرض مجموعات من عُقد أخرى مرتبطة معها. لقراءة أحد عناصر الربط، يجب تضمين كل من معرف العقدة واسم عنصر الربط في المسار. فعلى سبيل المثال، تحتوي العُقد /page على عنصر ربط /feed والذي يمكن أن يعرض كل عُقد المنشور في الصفحة. فيما يلي طريقة استخدام عنصر الربط للحصول على كل المنشورات الموجودة بصفحة كوكاكولا:

GET https://graph.facebook.com/820882001277849/feed

ستكون استجابة JSON مشابهة لما يلي:

{
  "data": [
    {
      "created_time": "2017-12-08T01:08:57+0000",
      "message": "Love this puzzle. One of my four coke puzzles",
      "id": "820882001277849_1805191182846921"
    },
    {
      "created_time": "2017-12-07T20:06:14+0000",
      "message": "You need to add grape as a flavor for Coke in your freestyle machines.",
      "id": "820882001277849_1804966026202770"
    },
    {
      "created_time": "2017-12-07T01:29:12+0000",
      "message": "Plz play the old commercial’s with the polar bears. Would be nice to see them this holiday",
      "id": "820882001277849_1804168469615859"
    }
  ]
}

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

الحقول

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

على سبيل المثال، يشير مرجع عقدة الصفحة إلى الحقول التي يمكنك أن تطلبها عند قراءة عُقدة الصفحة. إذا كنت تريد الحصول على الحقول about وfan_count وwebsite لصفحة كوكاكولا، فيجب عليك إجراء ما يلي:

GET https://graph.facebook.com/820882001277849
    ?fields=about,fan_count,website

سيؤدي ذلك الإجراء إلى عرض الاستجابة التالية:

{
  "about": "Welcome to the happiest Facebook page on, um, Facebook.",
  "fan_count": 106714402,
  "website": "http://coca-cola.com",
  "id": "820882001277849"
}

ستقوم عناصر الربط أيضًا، والتي عادة ما تقوم بعرض مجموعات من الكائنات، بعرض حقول مرتبطة بكل كائن في مجموعة الكائنات. لنفترض أنك استخدمت عنصر الربط /photos للحصول على كل عُقد الصور الموجودة بصفحة كوكاكولا:

GET https://graph.facebook.com/820882001277849/photos

سيؤدي ذلك الإجراء إلى إنشاء استجابة تشبه ما يلي:

{
  "data": [
    {
      "created_time": "2016-08-23T13:12:10+0000",
      "id": "1308573619175349"
    },
    {
      "created_time": "2016-08-05T22:34:19+0000",
      "id": "1294456907253687"
    },
    {
      "created_time": "2016-04-29T16:17:02+0000",
      "id": "1228552183844160"
    }
  ]
}

وكما ترى، سيعرض عنصر الربط /photos افتراضيًا مجموعة من معرّفات عُقد الصور، بالإضافة إلى خاصية created_time لكل صورة. وكما هو الحال مع العُقد، يمكنك استخدام المعلمة fields لتحديد الحقول التي تريد عرضها لكل كائن معروض في مجموعة الكائنات.

لنفترض أنك أردت الحصول على الحقول height وwidth وlink (عنوان URL) لكل عقدة صورة يتم عرضها بواسطة عنصر الربط /photos:

GET https://graph.facebook.com/820882001277849/photos
      ?fields=height,width,link

فيما يلي الشكل الذي تظهر عليه الاستجابة:

{
  "data": [
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1308573619175349/?type=3",
      "id": "1308573619175349"
    },
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1294456907253687/?type=3",
      "id": "1294456907253687"
    },
    {
      "height": 180,
      "width": 180,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1228552183844160/?type=3",
      "id": "1228552183844160"
    }
  ]
}

لاحظ أنه يمكنك تحديد عنصر ربط باستخدام المعلمة fields أيضًا، والتي يمكن الاستفادة منها عند استخدام ميزة توسيع الحقل.

توسيع الحقل

إذا كنت تريد اختبار الاستعلام GET /page/photos أعلاه في مستكشف Graph API، فربما لاحظت أن الطلب قد عرض أكثر من ثلاثة كائنات وقام أيضًا بتقسيم النتائج إلى صفحات. ويُعد ذلك أمرًا شائعًا للغالية العظمى من عناصر الربط. سنتناول التنقل عبر النتائج قريبًا، ولكن دعنا نلقِ نظرة الآن على ميزة توسيع الحقول، والتي لا تتيح لك إمكانية إجراء استعلامات متداخلة فحسب، بل تتيح أيضًا إمكانية تقييد وترتيب النتائج.

تقييد النتائج

تتيح لك ميزة تقييد النتائج إمكانية التحكم في عدد الكائنات التي يتم عرضها في كل مجموعة من النتائج المقسمة. لتقييد النتائج، أضف الوسيطة .limit() إلى أي حقل أو عنصر ربط.

فعلى سبيل المثال، قد يؤدي إجراء طلب GET على عنصر الربط /feed بصفحة كوكاكولا إلى عرض مئات المنشورات. يمكنك تقييد هذا العدد من المنشورات التي يتم عرضها لكل صفحة من صفحات النتائج من خلال القيام بما يلي:

GET https://graph.facebook.com/820882001277849
    ?fields=feed.limit(3)

يؤدي ذلك الإجراء إلى عرض كل المنشورات الموجودة بصفحة كوكاكولا، ولكنه يؤدي إلى تقييد عدد الكائنات التي تظهر في كل صفحة من صفحات النتائج إلى ثلاثة كائنات. لاحظ أنه بدلاً من تحديد عنصر الربط Feed في عنوان URL للمسار (/page/feed)، فإنك تحدد ذلك في المعلمة fields (?fields=feed)، والتي تتيح لك إمكانية إلحاق الوسيطة .limit(3).

فيما يلي نتائج الاستعلام:

{
  "feed": {
    "data": [
      {
        "created_time": "2017-12-12T01:24:21+0000",
        "message": "This picture of my grandson with Santa screams Coca Cola",
        "id": "820882001277849_1809387339093972"
      },
      {
        "created_time": "2017-12-11T23:40:17+0000",
        "message": ":)",
        "id": "820882001277849_1809316002434439"
      },
      {
        "created_time": "2017-12-11T23:31:38+0000",
        "message": "Thought you might enjoy this.  My horse loves Coke!",
        "id": "820882001277849_1809310929101613"
      }
    ],
    "paging": {
      "cursors": {
        "before": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5UTRNakE0T0RJd01ERXlOemM0TkRrNkxUVXdPRE16TXpVM01EQXpNVFUwTkRRME5Ua1BER0ZA3YVY5emRHOXllVjlwWkE4ZA09ESXdPRGd5TURBeE1qYzNPRFE1WHpFNE1Ea3pPRGN6TXprd09UTTVOeklQQkhScGJXVUdXaTh2eFFFPQZDZD",
        "after": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5TTRNakE0T0RJd01ERXlOemM0TkRrNk1UTTJORE01T0RVNU1UZAzVPRGMyTnpFNE1BOE1ZAWEJwWDNOMGIzSjVYMmxrRHlBNE1qQTRPREl3TURFeU56YzRORGxmTVRnd09USXdOamsxTlRjM09EWTNOdzhFZAEdsdFpRWmFMdk9HQVE9PQZDZD"
      },
      "next": "https://graph.facebook.com/820882001277849/feed?access_token=valid_token_goes_here"
    }
  },
  "id": "820882001277849"
}

كما ترى، لا يظهر سوى ثلاثة كائنات في هذه الصفحة من النتائج المقسمة إلى صفحات، إلا أن الاستجابة تضمنت حقل next وعنوان URL الذي يمكنك استخدامه للحصول على الصفحة التالية.

ترتيب النتائج

يمكنك ترتيب النتائج استنادًا إلى وقت إنشاء الكائن. لإجراء ذلك، يمكنك استخدام وسيطة .order() التي تحتوي على إحدى القيم التالية في حقل أو عنصر ربط.

  • chronological - يمكن ترتيب النتائج مع عرض الكائنات الأقدم إنشاءً أولاً.
  • reverse_chronological - يمكن ترتيب النتائج مع عرض الكائنات الأحدث إنشاءً أولاً.

على سبيل المثال، دعنا نحصل على كل التعليقات التي تمت على أحد منشورات الفيديو التي تم نشرها بصفحة كوكاكولا (1809938745705498)، وترتيب النتائج حسب التاريخ (الأقدم أولاً)، وتقييد عدد الكائنات التي تظهر في صفحة النتائج المقسمة على ثلاثة كائنات:

GET https://graph.facebook.com/1809938745705498
    ?fields=comments.order(chronological).limit(3)

ومرة أخرى، لاحظ أنه حتى تتمكّن من استخدام وسيطة في عنصر ربط، يجب تحديد عنصر الربط في المعلمة fields. وكما ترى، يمكنك تجميع الوسيطتين .limit() و.order() في حقل واحد أو عنصر ربط واحد.

فيما يلي النتائج:

{
  "comments": {
    "data": [
      {
        "created_time": "2017-12-12T14:12:20+0000",
        "message": ":) :) :)",
        "id": "1809938745705498_1809939942372045"
      },
      {
        "created_time": "2017-12-12T14:14:03+0000",
        "message": "seasons greetings!",
        "id": "1809938745705498_1809941802371859"
      },
      {
        "created_time": "2017-12-12T14:14:11+0000",
        "message": "My bestie <3",
        "id": "1809938745705498_1809941879038518"
      }
    ],
    "paging": {
      "cursors": {
        "before": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd3T1Rrek9UZAzROVGN3TlRNNE5Eb3hOVEV6TURnM09UTTIZD",
        "after": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd4TURBd09UazROVFk1T0RNM05Eb3hOVEV6TURreU5qQXoZD"
      },
      "next": "https://graph.facebook.com/1809938745705498/comments?access_token=valid_token_goes_here"
    }
  },
  "id": "1809938745705498"
}

النشر

تتيح لك الغالبية العظمى من عناصر الربط إمكانية نشر الكائنات إلى مجموعة كائنات في عُقدة. ويمكنك القيام بذلك من خلال إجراء طلب POST إلى عنصر ربط العُقدة. فعلى سبيل المثال، يمكنك نشر تعليق على صورة باستخدام عنصر الربط /comments في عقدة الصورة:

POST https://graph.facebook.com
  /1809938745705498
    /comments
      ?message=Awesome!

إذا نجحت العملية، فستقوم معظم عناصر الربط بعرض معرف الكائن الذي قمت بنشره للتو، والذي غالبًا ما يكون عبارة عن توليفة مكونة من المعرف الذي تم نشر الكائن عليه وسلسلة معرف جديد:

{
  "id": "1809938745705498_1810399758992730"
}

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

قد يؤثر رمز الوصول المستخدَم لنشر الكائن في مظهر الكائن. ففي حالة استخدام رمز وصول الصفحة، فسيظهر وكأن الصفحة هي التي قامت بنشر الكائن، وأما في حالة استخدام رمز وصول مستخدم فسيظهر الكائن وكأنه قام أحد الأشخاص بنشره.

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

التحديث

يمكنك إجراء عمليات التحديث في عقدة موجودة باستخدام طلبات POST. فعلى سبيل المثال، لتحديث الحقل message في تعليق موجود، يمكنك إجراء ما يلي:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?message=Happy%20Holidays!

إذا نجحت العملية، فستعرض العقدة حقل success وقيمة true:

{
  "success": true
}

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

الحذف

يمكنك حذف عقدة باستخدام عملية DELETE:

DELETE https://graph.facebook.com
  /1809938745705498_1810399758992730

إذا نجحت العملية، فستعرض العقدة حقل success وقيمة true:

{
  "success": true
}

يمكنك عادةً حذف العُقد التي قمت بإنشائها فقط، ولكن يمكنك الرجوع إلى الدليل المرجعي لكل عُقدة للتعرف على متطلبات عمليات الحذف.

لدعم العملاء الذين لا يدعمون كل أساليب HTTP، يمكنك إرسال طلب POST إلى العقدة وتضمين المعلمة method=delete وقيمة لتجاوز أسلوب HTTP:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?method=delete

التنقل عبر النتائج المقسمة

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

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

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

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

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

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

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

يجب عدم تخزين المؤشرات. تنتهي صلاحية المؤشرات سريعًا عند إضافة عناصر أو إزالتها.

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

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

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

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/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 التي تعرض صفحة البيانات السابقة.

للحصول على نتائج متسقة، يرجى تحديد المعلمتين since وuntil. ويوصى أيضًا أن يكون الحد الأقصى لفارق الوقت هو 6 أشهر.

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

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

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

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

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

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

بالنسبة للكائنات التي تتضمن عددًا كبيرًا من العناصر التي تم إرجاعها مثل [comments](/docs/graph-api/reference/object/comments) والتي قد يصل عددها إلى عشرات الآلاف، قد تواجه قيودًا أثناء تقسيم الصفحات. وستؤدي واجهة API إلى إرجاع خطأ عندما يصل تطبيقك إلى حد المؤشر:

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