نظرة عامة على واجهة Graph API

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

الأساسيات

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

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

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

GET graph.facebook.com
  /facebook/picture?
    redirect=false

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

في هذه النظرة العامة، سيتم عرض كيفية قراءة واجهة Graph API للبيانات ونشرها بالرسم البياني الاجتماعي.

بنية Graph API

سنتناول هذا الجزء بشكل تفصيلي في دليل استخدام واجهة Graph API، ولكن بوجه عام يمكنك قراءة واجهات API بتقديم طلبات HTTP GET للعُقَد أو عناصر الربط الخاصة بتلك العُقَد.

يتم تمرير معظم الطلبات إلى واجهة API في graph.facebook.com - والاستثناء الوحيد هو تحميلات الفيديو التي تستخدم graph-video.facebook.com.

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

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

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

GET graph.facebook.com
  /{node-id}

أو عنصر ربط:

GET graph.facebook.com
  /{node-id}/{edge-name}

يمكنك بوجه عام النشر إلى واجهات API بتقديم طلبات HTTP POST باستخدام المعلمات إلى عقدة:

POST graph.facebook.com
  /{node-id}

أو عنصر ربط:

POST graph.facebook.com
  /{node-id}/{edge-name}

يتم الحذف من خلال واجهات API باستخدام طلبات HTTP DELETE (والتحديث عبر طلبات POSR) لنفس نقاط النهاية.

إصدارات واجهة API

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

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

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

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

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

GET graph.facebook.com
  /v2.2/me

يصلح ذلك مع كل الإصدارات، وفق هذا النموذج العام:

GET graph.facebook.com
  /vX.Y/{request-path}

حيث تشير X.Y إلى الإصدار المطلوب. ننشر قائمة كاملة بالإصدارات المتوفرة في سجل التغييرات. توفر كل وثائق واجهة Graph API المرجعية معلومات مقسمة حسب الإصدار، لذا يرجى التحقق للتأكد من الاطلاع على معلومات الإصدار الصحيح - تزيل بعض الإصدارات العُقَد وعناصر الربط، بينما تضيفها إصدارات أخرى.

لنحاول الآن تقديم طلب API، لتعلم مدى سهولة الأمر.

تحميل مستكشف واجهة Graph API

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

مستكشف واجهة Graph API

إنشاء رمز وصول أساسي للمستخدم

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

  1. انقر على زر Get Token في الجزء العلوي الأيمن للمستكشف.
  2. حدد الخيار Get User Access Token.
  3. في مربع الحوار التالي، لا تحدد أي مربع، وانقر فقط على زر Get Access Token أزرق اللون.
  4. سيظهر مربع حوار تسجيل دخول فيسبوك، انقر على OK للمتابعة.

تقديم أول طلب

الآن أصبحت جاهزًا لتقديم أول طلب واجهة Graph API لك، سنبدأ بطلب 'قراءة'. في الحقل النصي الموجود بجوار زر "GET" المنسدل (سنشير إلى ذلك باسم حقل المسار)، احذف النص الموجود واكتب 'me':

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

ما فعلته الآن في مستكشف واجهة Graph API يعادل طلب 'القراءة' التالي في واجهة Graph API:

GET graph.facebook.com
  /me

تشكل /me نقطة نهاية خاصة تتحول إلى معرف مستخدم للشخص الذي يُقدَم الطلب باستخدام رمز وصوله.

تهانينا، لقد انتهيت الآن من تقديم أول طلب واجهة Graph API لك!

الحصول على أذونات النشر

ما سنقوم به الآن هو محاولة نشر شيء على فيسبوك باستخدام واجهة Graph API. يمكنك تنفيذ ذلك في تطبيقك فقط في حالة إنشاء أداة composer مخصصة وعدم استخدام أحد مربعات حوار المشاركة على الويب أو iOS أو Android. لا تتطلب مربعات حوار المشاركة على فيسبوك أن تقوم بتنفيذ تسجيل دخول فيسبوك أو إنشاء واجهتك الخاصة التي تتيح المشاركة للأشخاص.

لاستكشاف النشر باستخدام واجهة Graph API، انقر على الزر Get Access Token "الحصول على رمز الوصول" مرة أخرى، واختر هذه المرة الإذن publish_actions:

انقر الآن على الزر Get Access Token "الحصول على رمز الوصول" أزرق اللون، وسيظهر لك مربع حوار تسجيل الدخول مرة أخرى. هنا ستتم مطالبتك بتحديد الإذن الذي يسمح لمستكشف واجهة Graph API بالنشر نيابة عنك. إذا أردت، يمكنك تغيير الجمهور هنا إلى "أنا فقط" بحيث يظهر المنشور لك وحدك، ولكن يجب عليك قبول مربع الحوار هذا والانتقال إلى الخطوة التالية.

نشر منشور

إذا كنت قد طلبت الإذن publish_actions، فانقر الآن على الزر الذي يحمل كلمة "GET" واختر "POST" من أداة التحديد المنسدلة التي تظهر. أدخل me/feed في حقل المسار، ثم انقر على Add a Field "إضافة حقل".

في الحقول الجديدة التي تظهر، ضع message في حقل "الاسم" وضع Hello, World في حقل "القيمة". يجب أن يكون الشكل كالتالي:

انقر الآن على زر Submit (تقديم) أزرق اللون، وبعد ثوانٍ معدودة، من المفترض أن تظهر لوحة الاستجابة على نحو مشابه للتالي:

{
  "id": "{new-post-id}"
}

يعني ذلك أنك نشرت أول منشور لك باستخدام واجهة Graph API! يمكنك الانتقال إلى صفحتك الشخصية، ويجب أن يظهر منشورك بها:

ما فعلته الآن في مستكشف واجهة Graph API يعادل طلب 'النشر' التالي في واجهة Graph API:

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

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

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