Instagram oEmbed

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

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

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

نقاط النهاية

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

المتطلبات

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

التقييدات

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

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

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

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

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

رموز الوصول

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

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

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

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

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

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

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

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

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

{app-id}|{client-token}

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

access_token=1234|5678

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

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

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

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

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

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

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

للحصول على ملف HTML مضمّن لمنشور Intagram، أرسل طلبًا إلى:

GET /instagram_oembed?url={url}&access_token={access-token}

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

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

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

عينة من الطلب

curl -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

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

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

{
  "version": "1.0",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/",
  "type": "rich",
  "width": 658,
  "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...",
  "thumbnail_width": 640,
  "thumbnail_height": 640
}

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

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

https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/https://www.instagram.com/{username}/guide/{slug}/{guide_id}

لغة JS مضمّنة

يحتوي ملف HTML المضمّن على مرجع إلى مكتبة JavaScript ‏embed.js في Instagram. عند تحميل المكتبة، فإنها تفحص الصفحة بحثًا عن ملف HTML للمنشور وتنشئ المنشور المعروض بالكامل. وإذا كنت تريد تحميل المكتبة بشكل منفصل، فيمكنك تضمين معلمة سلسلة الاستعلام omitscript=true في طلبك. ولتهيئة ملف HTML المضمّن يدويًا، يمكنك استدعاء الوظيفة instgrm.Embeds.process() بعد تحميل المكتبة.

حجم المنشور

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

الحصول على صور مصغرة

نوصيك بعرض كل ملفات HTML المضمّنة للمنشور إن أمكن. وإذا كان يتعذر عليك القيام بذلك، يمكنك الحصول على عنوان URL لصورة مصغرة للمنشور وعرضه بدلًا من ذلك. ولكن إذا قمت بذلك، فيجب عليك توفير إسناد واضح بجانب الصورة، بما في ذلك الإسناد إلى المؤلف الأصلي وإلى Instagram ورابط إلى منشور Instagram الذي تستعلم عنه.

وللحصول على عنوان URL لصورة مصغرة للمنشور ومعلومات الإسناد، أرسل طلبًا إلى:

GET /instagram_oembed
  ?url={url}
  &maxwidth={maxwidth}
  &fields=thumbnail_url,author_name,provider_name,provider_url
  &access_token={access-token}

واستبدل عنوان {url} بعنوان URL لمنشور Instagram الذي تريد الاستعلام عنه، وقيمة {maxwidth} بالحد الأقصى لحجم الصورة المصغرة التي تريد عرضها، ورمز {access-token} برمز وصول التطبيق أو رمز الوصول البرنامج.

عينة من الطلب

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."

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

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

{
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/"
}

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

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

Authorization: Bearer {access-token}

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

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