نظرة عامة

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

الأساسيات

تم اشتقاق تسمية واجهة Graph API من منطلق فكرة 'الرسم البياني للتواصل الاجتماعي' - وهو عبارة عن تمثيل للبيانات على فيسبوك. وهو يتألف من:

  • العُقَد - عادةً ما تكون كائنات فردية مثل "مستخدم" أو "صورة" أو "صفحة" أو "تعليق".
  • عناصر الربط - وهي روابط تجمع بين مجموعة من الكائنات وكائن واحد، مثل صور في صفحة أو تعليقات على صورة
  • الحقول - البيانات الخاصة بكائن ما، مثل تاريخ ميلاد مستخدم أو اسم صفحة

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

HTTP

تستند واجهة Graph API إلى بروتوكول HTTP، ولذا فهي تعمل مع أي لغة تحتوي على مكتبة HTTP، مثل cURL وurllib. وذلك يعني أنه يمكنك استخدام واجهة Graph API في متصفحك مباشرة. على سبيل المثال، يتساوى طلب عنوان URL هذا في متصفحك...

https://graph.facebook.com/facebook/picture?redirect=false

... مع إجراء طلب cURL التالي:

curl -i -X GET \
 "https://graph.facebook.com/facebook/picture?redirect=false&access_token={valid-access-token-goes-here}"

رموز الوصول

قد تكون لاحظت المعلمة access_token وقيمة العنصر النائب في طلب cURL أعلاه. تتطلب الغالبية العظمى من طلبات واجهة Graph API توفير رمز وصول. ينبغي عليك في النهاية التعرف على طريقة عمل رموز الوصول من خلال قراءة وثائق رموز الوصول التي نوفرها، ولكن في الوقت الحالي، كل ما يجب تحتاج إلى معرفته هو أن:

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

لن تقوم أمثلة طلب/استجابة رمز صوري التي نوفرها عبر وثائق واجهة Graph API بالإحالة بشكل صريح إلى رمز وصول، ولكن يجب عليك افتراض تضمين رمز وصول في الطلب حتى تتمكن من تلقي استجابة.

البنية

نتناول هذا الموضوع بشكل كامل في دليل استخدام واجهة Graph API، ولكن بوجه عام يمكنك:

  • استخدام العُقد للحصول على البيانات المرتبطة بالكائنات الفردية
  • استخدام عناصر الربط للحصول على مجموعات الكائنات المرتبطة بعقدة أو لنشر كائنات إلى تلك المجموعات
  • استخدام الحقول لتحديد البيانات التي تريد تضمينها في الاستجابات

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

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

معرفات الكائنات

العُقد هي كائنات فردية، تختص كل واحدة منها بمعرف فريد، فإذا أردت الحصول على معلومات تتعلق بعُقدة بعينها، فقم بالاستعلام عن المعرف الخاص بها. على سبيل المثال، معرف صفحة فيسبوك الرسمية هو 20531316728. يمكنك الاستعلام عنها مباشرة باستخدام المعرف الخاص بها:

GET graph.facebook.com
  /20531316728

إذا أردت الحصول على بيانات محددة (والتي تسمى الحقول) بشأن عُقدة معيّنة، يمكنك تضمين المعلمة fields وتحديد الحقول التي تريد عرضها في الاستجابة. وباستعراض سريع لمرجع عُقدة الصفحة نعرف أنه من الحقول التي يمكنك الحصول عليها عند قراءة كائن الصفحة هو حقل cover، والذي يحتوي على صورة غلاف الصفحة. فيما يلي الشكل الذي سيظهر به ذلك الاستعلام:

GET graph.facebook.com
  /20531316728?fields=cover

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

GET graph.facebook.com
  /20531316728/photos

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

POST graph.facebook.com
  /20531316728?description=The%20OFFICIAL%20Facebook%20Page

غالبًا ما تتيح لك عناصر الربط إمكانية نشر كائنات جديدة في مجموعات العُقدة من خلال تنفيذ عمليات POST. فيما يلي كيفية نشر صورة إلى مجموعة الصور التي تملكها صفحة فيسبوك:

POST graph.facebook.com
  /20531316728/photos

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

وفي النهاية، يمكنك عادةً حذف عقدة من خلال تنفيذ عملية DELETE على معرف الكائن:

DELETE graph.facebook.com
  /20531316728

الإصدارات

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

الأمر بمنتهى البساطة - فقط أضف الحرف v متبوعًا برقم الإصدار في بداية مسار الطلب. على سبيل المثال، ما يلي هو استدعاء للإصدار 2.9:

GET graph.facebook.com
  /v2.9/20531316728/photos

إذا لم تقم بتضمين رقم إصدار، يتم تعيين الإعداد الافتراضي على أقدم رقم إصدار متوفر، ولذلك يُفضل تضمين رقم الإصدار في طلباتك.

يحتوي سجل تغييرات واجهة Graph API على كل الإصدارات المتوفرة وتتيح لك الوثائق المرجعية إمكانية فلترة المحتوى حسب الإصدار.

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

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