oEmbed في فيسبوك

تسمح لك نقاط النهاية oEmbed في Facebook بالحصول على ملف HTML مضمّن وبيانات التعريف الأساسية للصفحات والمنشورات ومقاطع الفيديو من أجل عرضها في موقع ويب أو تطبيق آخر.

تم استبدال منتج oEmbed بميزة قراءة oEmbed. وإذا تم تنفيذ منتج oEmbed قبل 8 يونيو 2021، فستتاح لك فرصة إكمال عملية مراجعة التطبيقات لميزة قراءة oEmbed حتى 7 سبتمبر 2021. وإذا لم يتم اعتمادك لميزة قراءة oEmbed بحلول 7 سبتمبر 2021، فسيفشل تحميل عمليات تنفيذ oEmbed.

الاستخدامات الشائعة

عرض الصفحات والمنشورات ومقاطع الفيديو من Facebook في تطبيقات المراسلة.
تضمين الصفحات والمنشورات ومقاطع الفيديو من Facebook في مواقع الويب والمدونات.
عرض الصفحات والمنشورات ومقاطع الفيديو من Facebook في نظام إدارة المحتوى.

نقاط النهاية

نقطة النهاية	الوصف
`GET /oembed_page`	يمكنك الحصول على بيانات التعريف الأساسية وملف HTML مضمّن لصفحة Facebook.
`GET /oembed_post`	يمكنك الحصول على بيانات التعريف الأساسية وملف HTML مضمّن لمنشور فيسبوك.
`GET /oembed_video`	يمكنك الحصول على بيانات التعريف الأساسية وملف HTML مضمّن لفيديو فيسبوك.

المتطلبات

حساب مطوّر في فيسبوك
تطبيق فيسبوك في وضع البث المباشر
رمز وصول
عملية مراجعة التطبيقات لميزة قراءة oEmbed

التقييدات

من المفترض استخدام نقطة النهاية oEmbed في Facebook فقط لتضمين محتوى Facebook في مواقع الويب والتطبيقات. ولا تُستخدم لأي أغراض أخرى. ويُحظر تمامًا استخدام بيانات التعريف والصفحة أو المنشور أو محتوى الفيديو (أو الاشتقاقات الخاصة بها) من نقاط النهاية لأي غرض آخر بخلاف توفير عرض واجهة المستخدم للصفحة أو المنشور أو الفيديو. يشمل هذا الحظر استهلاك بيانات التعريف والمحتوى أو معالجتها أو استخراجها أو الاحتفاظ بها، فعلى سبيل المثال لا الحصر، اشتقاق معلومات حول الصفحات والمنشورات ومقاطع الفيديو من بيانات التعريف لأغراض التحليلات.

مراجعة التطبيقات

حتى تتمكن من استخدام oEmbed، يجب أن يخضع تطبيقك لعملية مراجعة التطبيقات لميزة قراءة oEmbed.

بالنسبة لحقل النموذج توفير عنوان URL حيث يمكننا اختبار قراءة Oembed، استخدم نقاط نهاية oEmbed للحصول على ملف HTML مضمَّن لأي منشور عام أو فيديو على صفحة فيسبوك الرسمية أو صفحة Instagram (أو الحصول على ملف HTML مضمَّن لكلتا الصفحتين). أضف ملف HTML المضمَّن الذي تم إرجاعه إلى صفحتك الخاصة حيث ستعرض محتوى oEmbed وأدخل عنوان URL لتلك الصفحة في حقل النموذج.

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

رموز الوصول

تتطلب نقاط النهاية oEmbed في Facebook رمز وصول التطبيق (موصى به) أو رمز وصول البرنامج.

رموز وصول التطبيق

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

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

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

رموز وصول البرنامج

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

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

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

{app-id}|{client-token}

على سبيل المثال:

access_token=1234|5678

تقييدات معدلات الاستدعاء

تعتمد تقييدات معدلات الاستدعاء على نوع رمز الوصول الذي يتضمنه تطبيقك في كل طلب.

تقييدات معدلات استدعاء رمز التطبيق

يمكن للتطبيقات المعتمدة على رموز وصول التطبيق إجراء 5 مليون طلب كحد أقصى يوميًا.

تقييدات معدلات استدعاء رمز العميل

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

الحصول على ملف HTML مضمّن

للحصول على ملف HTML مضمّن لفيديو أو منشور أو صفحة، أرسل طلبًا إلى نقطة النهاية oEmbed المقابلة للصفحة أو المنشور أو الفيديو:

الهدف	بنية الاستعلام ونقطة النهاية
الصفحة	`GET /oembed_page?url={url}&access_token={access-token}`
المنشور	`GET /oembed_post?url={url}&access_token={access-token}`
الفيديو	`GET /oembed_video?url={url}&access_token={access-token}`

استبدل عنوان {url}بعنوان URL للصفحة أو المنشور أو الفيديو الذي تريد الاستعلام عنه، وكذلك رمز {access-token} برمز وصول التطبيق أو رمز وصول البرنامج (أو أرسله إلينا في عنوان HTTP). وإذا كنت تستخدم رمز وصول البرنامج، فتذكّر أنه يجب عليك دمجه مع معرف التطبيق لديك باستخدام رمز الأنبوب، وإلا فلن ينجح الطلب.

عند نجاح العملية، ستستجيب واجهة API مع كائن لغة JSON الذي يحتوي على ملف HTML مضمّن للصفحة أو المنشور أو الفيديو، وعلى بيانات إضافية حول الصفحة أو المنشور أو الفيديو. سيتم تعيين ملف HTML المُضمن على خاصية html.

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

عينة من طلب الصفحة

curl -i -X GET \
 "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC&access_token=96481..."

عينة من الاستجابة

يتم اقتطاع بعض القيم بعلامة الحذف (...) لإمكانية القراءة.

{
  "provider_url": "https://www.facebook.com",
  "provider_name": "Facebook",
  "height": 500,
  "html": "<div id=\"fb-root\"></div><script async=\"1\" defer=...",
  "type": "rich",
  "version": "1.0",
  "width": 340
}

تنسيقات عنوان URL

تقبل معلمة سلسلة الاستعلام url تنسيقات عنوان URL التالية:

الصفحات

https://www.facebook.com/{page-name}
https://www.facebook.com/{page-id}

المنشورات

https://www.facebook.com/{page-name}/posts/{post-id}
https://www.facebook.com/{username}/posts/{post-id}
https://www.facebook.com/{username}/activity/{activity-id}
https://www.facebook.com/photo.php?fbid={photo-id}
https://www.facebook.com/photos/{photo-id}
https://www.facebook.com/permalink.php?story_fbid={post-id}&id={page-or-user-id}
https://www.facebook.com/media/set?set={set-id}
https://www.facebook.com/questions/{question-id}
https://www.facebook.com/notes/{username}/{note-url}/{note-id}

مقاطع الفيديو

https://www.facebook.com/{page-name}/videos/{video-id}/
https://www.facebook.com/{username}/videos/{video-id}/
https://www.facebook.com/video.php?id={video-id}
https://www.facebook.com/video.php?v={video-id}

لغة JS لمجموعة SDK

يحتوي ملف HTML المُضمن افتراضيًا على مرجع إلى مكتبة JavaScript sdk.js. للحصول على ملف HTML مضمّن بدون توفر المرجع بحيث يمكنك تحميله بشكل منفصل، قم بتضمين معلمة سلسلة الاستعلام omitscript=true.

إدخال رموز الوصول في العنوان

إذا كنت لا تريد تضمين رمز الوصول في سلسلة استعلام الطلب، فيمكنك إرساله إلينا من خلال عنوان Authorization HTTP بدلاً من ذلك.

Authorization: Bearer {access-token}

على سبيل المثال:

curl -i -X GET \
  "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."