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

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

الأساسيات

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

القراءة

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

GET /v2.5/me HTTP/1.1
Host: graph.facebook.com

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

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

GET graph.facebook.com
  /me/photos

تتباين الاستجابة التي تتلقاها تبعًا للعقدة أو عنصر الربط الذي تقرأه، لكنها ستتخذ الشكل العام التالي:

{
   "fieldname": {field-value},
   ....
}

اختيار الحقول

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

على سبيل المثال، لن يعرض استدعاء واجهة Graph API التالي الذي يستخدم رمز وصول المستخدم الذي توفره https://graph.facebook.com/me?fields=id,name,picture سوى المعرف والاسم والصورة الموجودة في ملفك الشخصي:

GET graph.facebook.com/me?fields=id,name,picture

الترتيب

يمكنك ترتيب مجموعات بيانات معينة ترتيبًا زمنيًا. على سبيل المثال، يمكنك ترتيب تعليقات إحدى الصور بترتيب زمني معكوس باستخدام مفتاح reverse_chronological:

GET graph.facebook.com
  /{photo-id}?
    fields=comments.order(reverse_chronological)

يجب أن يكون order بإحدى القيم التالية:

  • chronological
  • reverse_chronological

بحث عنوان URL

يمكن اكتشاف معظم الكائنات باستخدام معرفاتها، لكن في بعض الأحيان لا يكون ذلك ممكنًا ولا يتوفر لديك للتعرف على الشيء سوى عنوان URL.

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

تعرف على المزيد عن العثور على بيانات رابط التطبيق باستخدام Index API في وثائقنا حول روابط التطبيقات.

تعديل طلبات API

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

الاسم الوصف النوع

return_ssl_resources

يتم استخدامها عندما تطلب عرض صورة عبر اتصال آمن (HTTPS) لتجنب تحذيرات المحتوى المختلطة في المتصفحات.

bool

locale

يتم استخدامها عندما يحتاج تطبيقك إمكانية استرجاع محتوى مترجم بلغة بلد معين (حال توفر ذلك).

Locale

نعرض فيما يلي أدوات تعديل أخرى تخص تقسيم الصفحات والتحليل الذاتي.

تقديم طلبات متداخلة

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

على سبيل المثال، في استدعاء واحد، يمكنك طلب أول N من الصور في أول K من الألبومات. تحافظ الاستجابة على تسلسل هيكل البيانات بحيث لا يضطر المطورون لنسج البيانات معًا في العميل.

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

هذا هو التنسيق العام لتوسيع الحقول:

GET graph.facebook.com
  /{node-id}?
    fields=<first-level>{<second-level>}

سيكون <first-level> في هذه الحالة حقل أو أكثر (مفصولة بفاصلة) أو عنصر ربط من العقدة الأم أو أكثر. سيكون <second-level> عبارة عن حقل أو أكثر (مفصولة بفاصلة) أو عنصر ربط من عقدة المستوى الأول أو أكثر .

لا توجد حدود لمقدار تداخل المستويات الذي يمكن حدوثه هنا. يمكنك أيضًا استخدام وسيطة .limit(n) بكل حقل أو عنصر ربط لتقييد عدد الكائنات التي تريد الحصول عليها.

يسهل فهم ذلك عند رؤيته عمليًا، ولذلك نورد مثال استعلام سيتم فيه استرجاع حتى خمس ألبومات من إنشاء أحد الأشخاص، وآخر خمس منشورات في الأخبار لديه.

GET graph.facebook.com
  /me?
    fields=albums.limit(5),posts.limit(5)

يمكنك توسيع نطاق ذلك أكثر ونسترجع مع كل كائن ألبوم أول صورتين والأشخاص المشار إليهم في كل صورة:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2)},posts.limit(5)

الآن يمكننا توسيع النطاق مجددًا باسترجاع اسم كل صورة، وعنوان URL لها، والأشخاص المشار إليهم فيها:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)

دعنا نلقي نظرة على مثال يستخدم تقسيم الصفحات استنادًا إلى المؤشر:

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

يمكنك رؤية طريقة عمل توسيع الحقول مع العُقَد وعناصر الربط والحقول لعرض بيانات مركبة في طلب واحد.

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

عند تقديم طلب 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. للحصول على نتائج متسقة، نوصي بتقسيم الصفحات باستخدام روابط السابق/التالي التي نعيدها في الاستجابة.

تقديم طلبات كبيرة

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

من أفضل الممارسات التي يمكن اتباعها استخدام طلب POST مع الطلبات الكبيرة بدلاً من طلب GET وإضافة معلمة method=GET. عند إجراء ذلك، سيتم تفسير طلب POST كما لو كان GET.

تقديم طلبات متعددة

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

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

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

طلبات قراءة معرفات متعددة

يمكنك تقديم طلب GET فردي لاسترجاع عُقَد متعددة باستخدام نقطة نهاية ?ids مع معرفات الكائنات لتلك العُقَد. على سبيل المثال، للبحث عن صفحة المطورين على فيسبوك وجلسة المستخدم الحالي في طلب واحد، يمكنك استخدام استدعاء واجهة Graph API التالي:

GET graph.facebook.com
  /?ids=platform,me

وهو يعادل طلبات API الفردية التالية:

GET graph.facebook.com
  /platform
  
GET graph.facebook.com
  /me

ستبدو البيانات المعروضة على نحو مشابه لهذا:

{
  "me": {
    "id": "1234567890"
    ... // Other fields
  }, 
  "platform": {
    "id": "19292868552"
    ... // Other fields
  }
}

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

GET graph.facebook.com
  /photos?ids={user-id-a},{user-id-b}

معادل لطلبات API الفردية التالية:

GET graph.facebook.com
  /{user-id-a}/photos
  
GET graph.facebook.com
  /{user-id-b}/photos

ستبدو البيانات المعروضة على نحو مشابه لهذا:

{
  "{user-id-a}": {
    "data": [
      {
        "id": "12345", 
        "picture": "{photo-url}", 
        "created_time": "2014-07-15T15:11:25+0000"
      }
      ... // More photos
    ]
  },
  "{user-id-b}": {
    "data": [
      {
        "id": "56789", 
        "picture": "{photo-url}", 
        "created_time": "2014-01-15T12:24:47+0000"
      }
      ... // More photos
    ]
  }, 
}

لاحظ أنه أثناء استخدام ترشيح الحقول وتوسيع الحقول والتقييد لعمليات البحث عن معرفات متعددة، ستظهر رسالة خطأ في حالة عدم تضمن أحد هذه الكائنات على أي حقل من الحقول المطلوبة. على سبيل المثال، إذا كنت تبحث عن صفحة ومستخدم باستخدام هذه الطريقة، ثم قمت بترشيح fields=id,picture,gender سيفشل الطلب لأن الصفحات لا تحتوي على حقل gender.

التحليل الذاتي

تدعم واجهة Graph API التحليل الذاتي للعُقَد. يتيح لك ذلك رؤية كل عناصر الربط الخاصة بالعقدة دون معرفة نوعها مسبقًا. للحصول على هذه المعلومات، أضف metadata=1 إلى طلب واجهة Graph API:

GET graph.facebook.com
  /{node-id}?
    metadata=1

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

{
   "name": {node-name},
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/me/feed",
         "picture": "https://graph.facebook.com/me/picture",
         ....
      }
      "fields": [
        {
          "name": "id",
          "description": "The user's Facebook ID. No `access_token` required. `string`."
        },
        ....
      ],
      "type": "user"
   }
}

النشر

تحتوي معظم العُقَد في واجهة Graph API على عناصر ربط يمكن أن تصبح أهداف نشر مثل /{user-id}/feed أو /{album-id}/photos. تتم كل عمليات النشر في واجهة Graph API عبر تقديم طلب POST HTTP إلى عنصر الربط ذي الصلة مع تضمين أي معلمات ضرورية. على سبيل المثال، لنشر منشور نيابة عن شخص، فعليك تقديم طلب POST HTTP على النحو التالي:

POST graph.facebook.com
  /{user-id}/feed?
    message={message}&
    access_token={access-token}

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

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

يحتوي دليل سيناريوهات واجهة Graph API الشائعة على معلومات إضافية عن بعض سيناريوهات النشر الشائعة.

تقديم طلبات متعددة

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

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

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

التحديث

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

POST graph.facebook.com
  /{node-id}?
    {updated-field}={new-value}&
    access_token={access-token}

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

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

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

الحذف

يمكنك حذف العُقَد من الرسم البياني عن طريق إرسال طلبات DELETE HTTP لها:

DELETE graph.facebook.com
  /{node-id}?
    access_token=...

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

لدعم العملاء الذين لا يدعمون كل طرق HTTPS، يمكنك بدلاً من ذلك إصدار طلب POST لنقطة نهاية بالوسيطة الإضافية method=delete لتجاوز طريقة HTTP. على سبيل المثال، يمكنك حذف تعليق بإصدار الطلب التالي:

POST graph.facebook.com
  /{comment-id}?
    method=delete

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

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

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

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=created_time,from,id,message,permalink_url

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

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "Jay P Jeanne",
    "id": "126577551217199"
  },
  "id": "126577551217199_122842541590700",
  "message": "Hello",
  "permalink_url": "https://www.facebook.com/126577551217199/posts/122842541590700",
}

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

الأخطاء

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

على سبيل المثال، يحتوي هذا الطلب على حقل غير صالح:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=permalink_urls

وفيما يلي الاستجابة:

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (permalink_urls) on node type (Post)",
    "type": "FacebookApiException",
    "code": 100,
    "fbtrace_id": "AzMnKh6NRKY",
    "original_response": {
      "id": "126577551217199_122842541590700"
    }
  }
}

يمكنك البحث في العديد من الكائنات العامة ضمن مخطط التواصل الاجتماعي باستخدام نقطة نهاية /search. يكون بناء جملة البحث كالتالي:

GET graph.facebook.com
  /search?
    q={your-query}&
    type={object-type}

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

أنواع البحث المتاحة

ندعم البحث عن الأنواع التالية:

النوع الوصف قيمة `q`

user

البحث عن شخص (إذا سمح بالبحث عن اسمه).

الاسم

page

البحث عن صفحة.

الاسم

event

البحث عن حدث.

الاسم

group

البحث عن مجموعة.

الاسم

place

البحث عن مكان. يمكنك قصر نطاق البحث على موقع أو مسافة معينة بإضافة معلمة center (مع خطوط الطول ودوائر العرض) ومعلمة distance اختيارية (بالأمتار):

الاسم

placetopic

تعرض قائمة بموضوعات صفحات الأماكن مع معرفاتها. استخدم معلمة topic_filter=all للحصول على القائمة الكاملة.

لا شيء

ad_*

مجموعة من خيارات البحث المختلفة التي يمكن استخدامها للعثور على خيارات الاستهداف.

راجع خيارات الاستهداف

مثال:

GET graph.facebook.com
  /search?
    q=coffee&
    type=place&
    center=37.76,-122.427&
    distance=1000

معالجة الأخطاء

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

ظهور رموز الخطأ

ما يلي هو استجابة خطأ شائعة تنتج عن فشل طلب API:

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}
  • message: وصف للخطأ يمكن للأشخاص قراءته.
  • code: رمز الخطأ. القيم الشائعة موضحة أدناه، مع أساليب المعالجة الشائعة.
  • error_subcode: معلومات إضافية عن الخطأ. القيم الشائعة موضحة أدناه.
  • error_user_msg: رسالة يتم عرضها للمستخدم. تستند لغة الرسالة إلى لغة طلب API.
  • error_user_title: عنوان مربع الحوار، في حالة عرضه. تستند لغة الرسالة إلى لغة طلب API.
  • fbtrace_id: معرف الدعم الداخلي. عند الإبلاغ عن خطأ يتعلق باستدعاء واجهة Graph API، عليك تضمين fbtrace_id لمساعدتنا في العثور على بيانات السجل لاستخدامها في تصحيح الخطأ.

رموز الأخطاء

الرمز أو النوع الاسم الإجراء

OAuthException

في حالة عدم وجود رمز فرعي، فذلك يعني انتهاء صلاحية حالة تسجيل الدخول أو رمز الوصول أو تم إلغاؤها أو أصبحت غير صالحة لأي سبب آخر. يجب الحصول على رمز وصول جديد.

في حالة وجود رمز فرعي، قم بالرجوع إلى الرمز الفرعي.

102

جلسة API

في حالة عدم وجود رمز فرعي، فذلك يعني انتهاء صلاحية حالة تسجيل الدخول أو رمز الوصول أو تم إلغاؤها أو أصبحت غير صالحة لأي سبب آخر. يجب الحصول على رمز وصول جديد.

في حالة وجود رمز فرعي، قم بالرجوع إلى الرمز الفرعي.

1

API مجهول

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

2

خدمة API

مشكلة مؤقتة بسبب عطل ما. يرجى الانتظار بعض الوقت وإعادة العملية.

4

استدعاءات كثيرة للغاية لواجهة API

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

17

استدعاءات كثيرة للغاية لمستخدم واجهة API

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

10

تم رفض إذن واجهة API

لم يتم منح الإذن أو تمت إزالته. معالجة الأذونات غير الموجودة.

190

انتهت صلاحية رمز الوصول

يجب الحصول على رمز وصول جديد.

200-299

إذن API (قيم متعددة تبعًا للإذن)

لم يتم منح الإذن أو تمت إزالته. معالجة الأذونات غير الموجودة.

341

تم بلوغ حد التطبيق

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

368

تم الحظر مؤقتًا لانتهاك السياسات

يرجى الانتظار بعض الوقت وإعادة العملية.

506

منشور مكرر

لا يمكن نشر المنشورات المكرر بشكل متتالٍ. قم بتغيير محتوى المنشور وحاول مرة أخرى.

1609005

خطأ في نشر الرابط

ظهرت مشكلة أثناء استخلاص بيانات من الرابط المقدم. تحقق من عنوان URL وحاول مرة أخرى.

الرموز الفرعية لأخطاء المصادقة

الرمز الاسم الإجراء

458

لم يتم تثبيت التطبيق

لم يسجل المستخدم الدخول إلى تطبيقك. أعد مصادقة المستخدم.

459

المستخدم في نقطة تحقق

يجب أن يسجل المستخدم الدخول عبر موقع https://www.facebook.com أو https://m.facebook.com لحل المشكلة.

460

تم تغيير كلمة السر

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

463

انتهت صلاحيته

انتهت صلاحية رمز الوصول أو حالة تسجيل الدخول، أو تم إلغاؤها، أو أصبحت غير صالحة لأي سبب آخر. معالجة أذونات الوصول منتهية الصلاحية.

464

مستخدم غير مؤكد

يجب أن يسجل المستخدم الدخول عبر موقع https://www.facebook.com أو https://m.facebook.com لحل المشكلة.

467

رمز وصول غير صالح

انتهت صلاحية رمز الوصول أو تم إلغاؤها، أو أصبح غير صالح لأي سبب آخر. معالجة أذونات الوصول منتهية الصلاحية.

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

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

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

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

تصحيح أخطاء طلبات واجهة API

وضع تصحيح أخطاء واجهة Graph API

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

لتمكين وضع تصحيح الأخطاء، استخدم معلمة سلسلة استعلام debug. على سبيل المثال:

GET graph.facebook.com
  /v2.3/me/friends
    access_token=...&
    debug=all

في حالة عدم الحصول على الإذن user_friends، فسينتج عن ذلك الاستجابة التالية:

{
  "data": [
  ], 
  "__debug__": {
    "messages": [
      {
        "message": "Field friends is only accessible on User object, if user_friends permission is granted by the user", 
        "type": "warning"
      }, 
      {
        "link": "https://developers.facebook.com/docs/apps/changelog#v2_0", 
        "message": "Only friends who have installed the app are returned in versions greater or equal to v2.0.", 
        "type": "info"
      }
    ]
  }
}

يمكن تعيين قيمة معلمة debug إلى "all" أو إلى أقل مستوى أهمية مطلوب، والذي يقابل type للرسالة:

قيمة معلمة Debug النتيجة

all

كل رسائل تصحيح الأخطاء المتاحة.

info

رسائل تصحيح الأخطاء التي بالنوع info وwarning

warning

رسائل تصحيح الأخطاء التي بالنوع warning فقط.

يتم عرض معلومات تصحيح الأخطاء، حين توفرها، في صورة كائن JSON تحت مفتاح __debug__، في مصفوفة messages. يعتبر كل عنصر ضمن هذه المصفوفة أحد كائنات JSON التي تحتوي على الحقول التالية:

الحقل نوع البيانات الوصف

message

سلسلة (String)

الرسالة.

type

سلسلة (String)

أهمية الرسالة.

link

سلسلة (String)

[اختياري] عنوان URL يشير إلى المعلومات ذات الصلة.

يمكنك أيضًا استخدام وضع تصحيح الأخطاء مع مستكشف واجهة Graph API.

تحديد الإصدار الذي تستخدمه طلبات API

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

توفر واجهة Graph API عنوان طلب مع أي استجابة ويعرف باسم facebook-api-version ويشير إلى إصدار API الذي نتجت عنه الاستجابة. على سبيل المثال، سيكون لاستدعاء واجهة Graph API الذي ينتج عنه طلب بالإصدار 2.0 عنوان HTTP التالي:

facebook-api-version:v2.0

يتيح لك عنوان facebook-api-version هذا تحديد ما إذا كان يتم عرض استدعاءات API من الإصدار الذي تتوقعه أم لا.

معلومات تصحيح الأخطاء للإبلاغ عن الأخطاء

إذا كنت تريد الإبلاغ عن خطأ في واجهة Graph API، فقد قمنا بتضمين بعض عناوين الطلب الإضافية التي يجب عليك إرسالها مع بلاغك لتساعدنا على تحديد المشكلة وإعادة إنتاجها. وعناوين الطلبات هذه هي X-FB-Debug وx-fb-rev وX-FB-Trace-ID.