نظرة عامة

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

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

بروتوكول HTTP

تتوافق كل عمليات نقل البيانات مع HTTP/1.1 وتتطلب كل نقاط النهاية توفر HTTPS. ونظرًا لأن واجهة 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"

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

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

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

رموز الوصول

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

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

تفضل بزيارة وثائق رمز الوصول للتعرف على المزيد.

العُقد

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

مثال cURL التالي يمثل استدعاءً لعقدة المستخدم.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

سيُرجع هذا الطلب البيانات التالية بشكل افتراضي، ويتم تنسيقها باستخدام JSON:

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

بيانات تعريف العقدة

يمكنك الحصول على قائمة بكل الحقول، بما في ذلك اسم الحقل والوصف ونوع البيانات لدى كائن العقدة، مثل المستخدم أو الصفحة أو الصورة. أرسل طلب GET إلى معرف الكائن وقم بتضمين المعلمة metadata=1:

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

ستحتوي استجابة JSON الناتجة على خاصية metadata التي تضم كل الحقول المدعومة الخاصة بالعقدة المحددة:

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

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

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

عناصر الربط

عنصر الربط هو اتصال بين عقدتين. على سبيل المثال، يمكن لعقدة المستخدم أن تحتوي على الصور المرتبطة بها ويمكن لعقدة الصور أن تحتوي على تعليقات مرتبطة بها. وسيُرجع مثال cURL التالي قائمة بالصورة التي نشرها الشخص على Facebook.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

يمثل كل معرف يتم إرجاعه عقدة الصورة ومتى تم تحميلها على Facebook.

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

الحقول

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

يشتمل طلب cURL التالي على المعلمة fields واسم المستخدم والبريد الإلكتروني وصورة الملف الشخصي.

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

البيانات التي يتم إرجاعها

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

المعلمات المعقدة

تكون معظم أنواع المعلمات بديهية وواضحة مثل bool وstring وint، ولكن يوجد أيضًا النوعان list وobject اللذان يمكن تحديدهما في الطلب.

يتم تحديد النوع list في بناء جملة بلغة JSON، فعلى سبيل المثال: ["firstitem", "seconditem", "thirditem"]

يتم تحديد النوع object أيضًا في بناء جملة بلغة JSON، فعلى سبيل المثال: {"firstkey": "firstvalue", "secondKey": 123}

النشر والتحديث والحذف

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

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

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

القراءة بعد الكتابة

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

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

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"

سيعمل ذلك على إرجاع الحقول المحددة كاستجابة بتنسيق JSON على النحو التالي:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

ارجع إلى الوثائق المرجعية لنقطة النهاية لمعرفة ما إذا كانت تدعم ميزة القراءة بعد الكتابة والاطّلاع على الحقول المتوفرة.

الأخطاء

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

يمكنك عادةً حذف عقدة، مثل عقدة المنشور أو الصورة، من خلال تنفيذ عملية DELETE في معرف الكائن:

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

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

Webhooks

يمكنك الحصول على إشعارات بالتغييرات في العُقد أو التفاعلات مع العُقد عن طريق الاشتراك في أحداث webhooks. راجع أحداث Webhooks.

الإصدارات

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

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

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

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

واجهات API ومجموعات SDK والمنصات في Facebook

يمكنك ربط الواجهات والتطوير عبر المنصات باستخدام واجهات API ومجموعات SDK والمنصات المتعددة في Facebook.

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

بدء استخدام واجهة Graph API - لنستكشف مخطط التواصل الاجتماعي في Facebook باستخدام أداة مستكشف Graph ونُجري بعض من الطلبات للحصول على البيانات.