وسائط IG

تمثل ألبوم أو صورة أو فيديو (فيديو تم تحميله أو فيديو بث مباشر أو مقطع ريلز أو قصة) في Instagram.

If you are migrating from Marketing API Instagram Ads endpoints to Instagram Platform endpoints, be aware that some field names are different.

نقدم الحقل التالي:

legacy_instagram_media_id

لا يتم دعم حقول نقاط النهاية التالية لإعلانات Instagram في API التسويق:

filter_name
location
location_name
latitude
longitude

الإنشاء

هذه العملية غير مدعومة.

القراءة

GET /<IG_MEDIA_ID>

يتم الحصول على الحقول وعناصر الربط في وسائط Instagram.

المتطلبات

	Instagram API مع تسجيل دخول Instagram	واجهة Instagram API مع تسجيل الدخول إلى فيسبوك
رموز الوصول	رموز وصول مستخدم Instagram	رمز وصول مستخدم فيسبوك
عنوان URL المضيف	`graph.instagram.com`	`graph.facebook.com`
نوع تسجيل الدخول	تسجيل دخول النشاط التجاري في Instagram	تسجيل دخول فيسبوك للأعمال
الأذونات	`instagram_business_basic`	`instagram_basic` `pages_read_engagement` إذا تم منح مستخدم التطبيق دورًا عبر مدير الأعمال في الصفحة المرتبطة بحساب Instagram الاحترافي لمستخدم التطبيق، فسيحتاج التطبيق أيضًا إلى أحد الأذونات التالية: `ads_management` `ads_read`

التقييدات

تُرجع الحقول مثل comments_count وlike_count التفاعل على وسائط Instagram المستهدفة فقط ولا تتضمن بيانات من أدوات أخرى. على سبيل المثال، سيُرجع comments_count عدد التعليقات على صورة، وليس عدد التعليقات على إعلانات تحتوي على هذه الصورة. استخدم total_comments_count وtotal_like_count للحصول على أعداد مجمعة تتضمن التفاعل من الوسائط التي تم الترويج/التعزيز/الإعلان عنها. يمكن تضمين عدد منشورات فيسبوك التي تم نشرها في منشورات متعددة إذا كان يمكن لمستخدم الجلسة الوصول إلى هذا المنشور.
لا تتضمن الشروحات التوضيحية الرمز @ ما لم يكن مستخدم التطبيق قادرًا أيضًا على تنفيذ مهام مكافئة لدور المسؤول داخل التطبيق.
لا يمكن استخدام بعض الحقول، مثل permalink، في الصور داخل الألبومات (الصور الفرعية).
لا يمكن قراءة وسائط Instagram لفيديو البث المباشر إلا أثناء البث.
تُرجع API هذه بيانات الوسائط المملوكة بواسطة حسابات Instagram الاحترافية فقط. لا يمكن استخدامها للحصول على بيانات الوسائط المملوكة بواسطة حسابات Instagram الشخصية.
لا تتوفر الحقول reposts_count وsaved_count وshares_count وtotal_like_count وtotal_comments_count وtotal_views_count للوسائط التابعة في الإعلان الدوّار ويتم إرجاعها فقط لكائنات الوسائط ذات المستوى الأعلى. يمكن لمالك الوسائط تعطيل عرض تسجيلات الإعجاب والتعليقات والمشاهدات وعمليات إعادة النشر والمشاركات، وفي هذه الحالات، لن يتم إرجاع الحقول ذات الصلة.

بنية الطلب

GET https://<HOST_URL>/<API_VERSION>/<IG_MEDIA_ID> \
  ?fields=<LIST_OF_FIELDS> \
  &access_token=<ACCESS_TOKEN>

معلمات المسار

العنصر النائب	القيمة
`<API_VERSION>` أحدث إصدار هو: `v26.0`	إصدار API الذي يستخدمه تطبيقك. إذا لم يكن محددًا في استدعاءات API، فسيكون هذا هو الإصدار الأحدث في وقت إنشاء تطبيق Meta، أو إذا لم يعد هذا الإصدار متوفرًا، فسيتم تعيين أقدم إصدار متوفر. تعرف على المزيد حول تعيين الإصدارات.
`<HOST_URL>`	عنوان URL المضيف الذي يستخدمه التطبيق للاستعلام عن نقطة النهاية.
`<IG_MEDIA_ID>`	مطلوب. معرف الوسائط التي سيتم نشرها.

معلمات سلسلة الاستعلام

المفتاح	العنصر النائب	القيمة
`access_token`	`<ACCESS_TOKEN>`	مطلوب. رمز وصول المستخدم الخاص بمستخدم التطبيق على فيسبوك أو Instagram.
`fields`	`<LIST_OF_FIELDS>`	يمثل قائمة مفصولة بفاصلة تتضمن الحقول التي تريد إرجاعها.

الحقول

يمكن قراءة الحقول العامة عبر توسيع الحقل.

الحقل الوصف

alt_text عام

نص وصفي للصور، مناسب لذوي الاحتياجات الخاصة.

boost_ads_list

يوفر نظرة عامة حول كل معلومات إعلانات Instagram المرتبطة بالوسائط العادية للإعلانات بالحالة ACTIVE. ويتضمن معرف الإعلان المرتبط وحالة عرض الإعلان. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.

boost_eligibility_info

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

caption عام

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

comments_count عام

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

copyright_check_information.status

يتم إرجاع الكائنين status وmatches_found

كائنات status الوصف

status

completed – تم إنهاء عملية الاكتشاف
error – حدث خطأ أثناء عملية الاكتشاف
in_progress – عملية الاكتشاف مستمرة
not_started – لم تبدأ عملية الاكتشاف

matches_found

يمكن التعيين على أحد ما يلي:

false إذا لم ينتهك الفيديو حقوق النشر،
وtrue إذا انتهك الفيديو حقوق النشر

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

كائنات copyright_matches	الوصف
`author`	مؤلف الفيديو المحمي بموجب حقوق النشر
`content_title`	اسم الفيديو المحمي بموجب حقوق النشر
`matched_segments`	مصفوفة من الكائنات التي تحتوي على أزواج القيمة والمفتاح التالية: `duration_in_seconds` – عدد الثواني التي ينتهك فيها المحتوى حقوق الطبع والنشر `segment_type` – إما `AUDIO` أو `VIDEO` `start_time_in_seconds` – يتم تعيينه على وقت بدء الفيديو
`owner_copyright_policy`	تتضمن الكائنات التي يتم إرجاعها ما يلي: `name` – اسم سياسة مالكي حقوق النشر `actions` – مصفوفة كائنات `action` تتضمن خطوات المعالجة المتخذة والتي تحددها سياسة مالك حقوق النشر. قد تتضمن خطوات معالجة مختلفة للمواقع المختلفة. `action` – إجراء المعالجة الذي تم اتخاذه ضد الفيديو المنتهك لحقوق النشر. يمكن اتخاذ خطوات معالجة مختلفة للبلدان المختلفة. يمكن أن تكون إحدى القيم التالية: `BLOCK` – يتم حظر الفيديو من الجماهير المدرجة في مصفوفة `geos` `MUTE` - يتم كتم صوت الفيديو للجماهير المدرجة في مصفوفة `geos`

id عام

معرف الوسائط.

is_ai_generated

يشير إلى ما إذا كانت الوسائط تحتوي على تصنيف ذكاء اصطناعي. ويمكن استبعاد الصور الفرعية في الألبوم.

is_comment_enabled

يمكن الإشارة إلى ما إذا تم تمكين التعليقات أو تعطيلها. ويمكن استبعاد الصور الفرعية في الألبوم.

is_shared_to_feed عام

لمقاطع ريلز فقط. عندما تكون القيمة true، يشير ذلك إلى إمكانية ظهور مقطع ريلز في علامتي التبويب الموجز وريلز. وعندما تكون القيمة false، هذا يشير إلى أن مقطع ريلز لا يمكنه الظهور سوى في علامة التبويب ريلز.

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

legacy_instagram_media_id

معرف وسائط Instagram التي تم إنشاؤها لنقاط نهاية API التسويق بالإصدار 21.0 والإصدارات الأقدم.

like_count

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

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

media_audio_type عام

نوع المقطع الصوتي المستخدم في الوسائط. يمكن أن يكون MUSIC أو ORIGINAL_SOUND. يتم إرجاعه فقط لوسائط الفيديو مثل ريلز؛ ولا يتم إرجاعه لأنواع الوسائط الأخرى (على سبيل المثال، الصور والإعلانات الدوّارة).

media_product_type عام

الواجهة التي يتم نشر الوسائط بها. يمكن أن تكون AD أو FEED أو STORY أو REELS. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.

media_type عام

يمثل نوع الوسائط. ويمكن أن يكون CAROUSEL_ALBUM أو IMAGE أو VIDEO.

media_url عام

عنوان URL الوسائط.

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

owner عام

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

permalink عام

عنوان URL ثابتًا للوسائط.

shortcode عام

الرمز القصير للوسائط.

thumbnail_url عام

عنوان URL للصورة المصغرة الخاصة بالوسائط. ولا يتوفر إلا على وسائط VIDEO.

timestamp عام

تاريخ إنشاء بتنسيق ISO 8601 وبتوقيت UTC (التوقيت الافتراضي هو UTC ±00:00).

username عام

اسم المستخدم الذي أنشأ الوسائط.

view_count عام

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

متوفر لواجهة API اكتشاف الأنشطة التجارية فقط.

reposts_count عام

عدد مرات إعادة نشر الوسائط. متوفر لوسائط FEED وREELS. لا يمكن الوصول من خلال نقاط نهاية واجهة API الهاشتاج. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.

saved_count

عدد مرات حفظ الوسائط. متوفر لوسائط FEED وREELS. لا يمكن الوصول إليه إلا بواسطة مالك الوسائط أو مساهم مقبول. لا يمكن الوصول من خلال استكشاف الأنشطة التجارية أو الوسائط التي تمت الإشارة إليها/ذِكرها أو نقاط نهاية واجهة API الهاشتاج. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.

shares_count

يمثل عدد مرات مشاركة الوسائط. متوفر لوسائط FEED وREELS. لا يمكن الوصول من خلال استكشاف الأنشطة التجارية أو نقاط نهاية واجهة API الهاشتاج. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.

total_comments_count عام

إجمالي عدد التعليقات على الوسائط عبر كل الواجهات، بما في ذلك التعليقات على الوسائط المُروَّجة/المُعزَّزة المرتبطة بها. لا يمكن الوصول من خلال نقاط نهاية واجهة API الهاشتاج. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.

total_like_count عام

إجمالي عدد تسجيلات الإعجاب على الوسائط عبر كل الواجهات، بما في ذلك تسجيلات الإعجاب على الوسائط المُروَّجة/المُعزَّزة المرتبطة بها. لا يمكن الوصول من خلال نقاط نهاية واجهة API الهاشتاج. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.

total_views_count

إجمالي عدد مرات مشاهدة محتوى الفيديو عبر جميع الواجهات، بما في ذلك المشاهدات من الوسائط المُروَّجة/المُعزَّزة وعمليات إعادة التشغيل. متوفر فقط لوسائط الفيديو. لا يمكن الوصول من خلال استكشاف الأنشطة التجارية أو نقاط نهاية واجهة API الهاشتاج. بالنسبة لاستكشاف الأنشطة التجارية، استخدم view_count بدلاً من ذلك. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.

عناصر الربط

يمكن إرجاع عناصر الربط العامة عبر توسيع الحقل.

عنصر الربط	الوصف
`children` عام.	يمثل مجموعة من كائنات وسائط Instagram الموجودة في وسائط Instagram للألبوم.
`collaborators`	يمثل قائمة بالمستخدمين الذين تمت إضافتهم كمتعاونين في كائن وسائط Instagram. لا يتوفر سوى لواجهة Instagram API مع تسجيل الدخول إلى فيسبوك فقط.
`comments`	يمكن أن تمثل مجموعة من تعليقات Instagram على كائن وسائط Instagram.
`insights`	يمكن أن تمثل أدوات قياس التفاعل على وسائل التواصل الاجتماعي في كائن وسائط Instagram.

مثال على cURL

مثال على الطلب

curl -X GET \
  'https://graph.instagram.com/v26.0/17895695668004550?fields=id,media_type,media_url,owner,timestamp&access_token=IGQVJ...'

مثال على الاستجابة

{
  "id": "17918920912340654",
  "media_type": "IMAGE",
  "media_url": "https://sconten...",
  "owner": {
    "id": "17841405309211844"
  },
  "timestamp": "2019-09-26T22:36:43+0000"
}

التحديث

POST /<IG_MEDIA_ID>

يتم تمكين التعليقات على وسائط Instagram أو تعطيلها.

Requirements

	Instagram API with Instagram Login	Instagram API with Facebook Login
Access Tokens	Instagram User access token	Facebook User access token
Host URL	`graph.instagram.com`	`graph.facebook.com`
Login Type	Business Login for Instagram	Facebook Login for Business
Permissions	`instagram_business_basic` `instagram_business_manage_comments`	`instagram_basic` `instagram_manage_comments` `pages_read_engagement` If the app user was granted a role via the Business Manager on the Page connected to the targeted IG User, you will also need one of: `ads_management` `ads_read`

التقييدات

لا يتم دعم وسائط Instagram في فيديو البث المباشر

بنية الطلب

POST https://<HOST_URL>/<API_VERSION>/<IG_MEDIA_ID>
  ?comment_enabled=<BOOL>
  &access_token=<ACCESS_TOKEN>

معلمات المسار

العنصر النائب	القيمة
`<API_VERSION>` أحدث إصدار هو: `v26.0`	إصدار API الذي يستخدمه تطبيقك. إذا لم يكن محددًا في استدعاءات API، فسيكون هذا هو الإصدار الأحدث في وقت إنشاء تطبيق Meta، أو إذا لم يعد هذا الإصدار متوفرًا، فسيتم تعيين أقدم إصدار متوفر. تعرف على المزيد حول تعيين الإصدارات.
`<HOST_URL>`	عنوان URL المضيف الذي يستخدمه التطبيق للاستعلام عن نقطة النهاية.
`<IG_MEDIA_ID>`	مطلوب. معرف الوسائط التي سيتم نشرها.

معلمات سلسلة الاستعلام

المفتاح	العنصر النائب	القيمة
`access_token`	`<ACCESS_TOKEN>`	مطلوب. يمثل رمز وصول المستخدم الخاص بمستخدم التطبيق.
`comment_enabled`	`<BOOL>`	مطلوب. قم بالتعيين على `true` لتمكين التعليقات أو على `false` لتعطيل التعليقات.

مثال على cURL

مثال على الطلب

curl -i -X POST \
 "https://graph.instagram.com/v26.0/17918920912340654?comment_enabled=true&access_token=EAAOc..."

مثال على الاستجابة

{
  "success": true
}

الحذف

DELETE /<IG_MEDIA_ID>

يمكن حذف وسائط Instagram.

المتطلبات

	واجهة Instagram API مع تسجيل الدخول إلى فيسبوك
رموز الوصول	رمز وصول مستخدم فيسبوك
عنوان URL المضيف	`graph.facebook.com`
نوع تسجيل الدخول	تسجيل دخول فيسبوك للأعمال
الأذونات	`instagram_basic` `instagram_manage_contents`

التقييدات

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

بنية الطلب

POST https://graph.facebook.com/<API_VERSION>/<IG_MEDIA_ID>
  ?access_token=<ACCESS_TOKEN>

معلمات المسار

العنصر النائب القيمة

العنصر النائب	القيمة
`<API_VERSION>` أحدث إصدار هو: `v26.0`	إصدار API الذي يستخدمه تطبيقك. إذا لم يكن محددًا في استدعاءات واجهة API، فسيكون هذا هو الإصدار الأحدث في وقت إنشاء تطبيق Meta، أو إذا لم يعد هذا الإصدار متوفرًا، فسيتم تعيين أقدم إصدار متوفر. تعرف على المزيد حول تعيين الإصدارات.
`<IG_MEDIA_ID>`	مطلوب. معرف الوسائط التي سيتم نشرها.

<API_VERSION>

أحدث إصدار هو:

v26.0

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

<IG_MEDIA_ID>

مطلوب. معرف الوسائط التي سيتم نشرها.

معلمات سلسلة الاستعلام

المفتاح	العنصر النائب	القيمة
`access_token`	`<ACCESS_TOKEN>`	مطلوب.رمز وصول المستخدم الخاص بمستخدم التطبيق.

مثال على cURL

مثال على الطلب

curl -i -X DELETE \
 "https://graph.facebook.com/v26.0/17918920912340654?comment_enabled=true&access_token=EAAOc..."

مثال على الاستجابة (نجاح)

{
  "success": true,
  "deleted_id": "17918920912340654"
}

مثال على الاستجابة (فشل، نوع الوسائط غير مدعوم)

{
  "error": {
   "message": "Fatal",
   "type": "OAuthException",
   "code": -1,
   "error_subcode": 2207073,
   "is_transient": false,
   "error_user_title": "Media Type Not Supported",
   "error_user_msg": "The media type is not supported for this endpoint",
   "fbtrace_id": "Api-OlNdfcpOwIu6hNaT5Kw"
  },
}