نماذج طلبات واجهة برمجة التطبيقات

تعرض هذه الصفحة نماذج طلبات إلى YouTube Data API. يمكنك استخدام واجهة برمجة تطبيقات البيانات في YouTube لاسترداد موارد YouTube ومعالجتها مثل مقاطع الفيديو والقنوات وقوائم التشغيل. يرتبط كل نموذج بمستكشف Google APIs ويعبئه بحيث يمكنك تنفيذ النموذج والاطلاع على الاستجابة.

للحصول على معلومات حول تحميل المحتوى باستخدام YouTube Data API، يمكنك الاطّلاع على التحميلات القابلة للاستئناف.

نظرة عامة

لتوضيح العرض التقديمي، تعرض النماذج في هذه الصفحة العناصر المميزة لكل طلب واختصار عنوان URL الأساسي للمضيف الذي يعالج طلبات واجهة برمجة التطبيقات للبيانات (https://www.googleapis.com/youtube/v3). ولتنفيذ الطلب خارج سياق النماذج، يجب تضمين عنوان URL الكامل.

على سبيل المثال، في ما يلي نموذج لطلب كما يظهر في هذه الصفحة:

GET {base-URL}/channels?part=contentDetails
                       &mine=true

عنوان URL الكامل لهذا الطلب هو:

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails
                                                  &mine=true

تسترد العديد من الطلبات البيانات التي لا يمكن الوصول إليها إلا لمالك قناة YouTube، مثل قائمة المشتركين. تتطلب هذه الطلبات من مالك القناة منح مستكشف واجهات برمجة تطبيقات Google الحق في تنفيذ طلبات بيانات YouTube API نيابةً عنه. (اطلع على تنفيذ مصادقة OAuth 2.0 للحصول على تفاصيل حول التصريح بالدخول إلى بيانات القناة الخاصة). بعد الربط بمستكشف واجهات برمجة التطبيقات، انقر على الزر تفويض الطلبات باستخدام OAuth 2.0. تخوِّل هذه الخطوة مستكشف واجهات برمجة التطبيقات لإجراء الطلبات نيابةً عن المالك. ويمكنك أيضًا اختيار نطاق التفويض الذي يحدِّد أنواع الطلبات التي يمكن لأداة "مستكشف واجهات برمجة التطبيقات" تنفيذها.

تمثل الاستجابة لكل طلب تمثيل JSON لأحد موارد YouTube. تحدد المعلمة part في الطلب أجزاء المورد التي يتم تضمينها في الاستجابة. تحدد المعلمة واحدة أو أكثر من خصائص المورد ذات المستوى الأعلى (غير متداخلة) التي يجب تضمينها في الاستجابة. على سبيل المثال، في ما يلي بعض أجزاء مورد الفيديو:

• مقتطف
• تفاصيل المحتوى
• اللاعب
• علم الإحصاء
• الحالة

كل هذه الأجزاء هي كائنات تحتوي على خصائص متداخلة، ويمكنك اعتبار هذه الكائنات كمجموعات من حقول البيانات الوصفية التي قد (أو لا) يستردها خادم واجهة برمجة التطبيقات. وبالتالي، تتطلّب المعلمة part اختيار مكوّنات الموارد التي يستخدمها تطبيقك فعلاً.يُرجى الاطّلاع على المقالة بدء استخدام YouTube Data API للحصول على المزيد من المعلومات.

استرداد معلومات القناة

يستخدم هذا الطلب طريقة channels.list لاسترداد تفاصيل حول القنوات التابعة للمستخدم الذي تمت المصادقة عليه.

GET {base_URL}/channels?part=contentDetails
                       &mine=true

تتضمن الاستجابة لهذا الطلب معرّف القناة وcontentDetails لقناة المستخدم الذي تمت المصادقة عليه. يتضمن contentDetails قوائم التشغيل المتعددة التي أنشأها النظام المرتبطة بالقناة. تتطلب العديد من الطلبات اللاحقة معرّف القناة أو معرّف قائمة التشغيل، لذا من المهمّ تسجيله.

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

الفيديوهات المحمّلة وقوائم التشغيل التي أنشأها النظام

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

قبل تنفيذ نموذج الطلب التالي في "مستكشف واجهات برمجة تطبيقات Google"، استبدل {UPLOADS_PLAYLIST_ID} بمعرّف قائمة التشغيل من الطلب السابق.

GET {base_URL}/playlistItems?part=contentDetails
                            &playlistId={UPLOADS_PLAYLIST_ID}

ملاحظة: إنّ قيمة "id" لكل سلعة تم إرجاعها هي معرّف قائمة التشغيل itemitem الخاص بها. معرّف الفيديو لعنصر قائمة التشغيل هو videoId في الجزء contentDetails.

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

قوائم التشغيل التي أنشأها المستخدمون

يستخدم هذا الطلب طريقة playlists.list لاسترداد قوائم التشغيل المرتبطة بالقناة التي تمت مصادقتها. يُرجى العِلم أنّ هذا الطلب لا يستردّ قوائم التشغيل التي أنشأها النظام والمضمّنة في معلومات القناة (الفيديوهات المحمَّلة وسجلّ المشاهدة وغير ذلك). ولا تسترد سوى قوائم التشغيل التي أنشأها المستخدمون.

GET {base_URL}/playlists?part=snippet
                        &mine=true

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

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

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

استرداد الاشتراكات

يحدد مورد subscription العلاقة بين مستخدم YouTube (المشترك) والقناة. تستردّ طريقة subscriptions.list المشتركين في قناة معيّنة أو الاشتراكات لمستخدم معيّن، استنادًا إلى المعلّمات التي تضمّنها في الطلب.

المشتركون في القناة

يسترد هذا الطلب قائمة المشتركين في القناة التي تمت مصادقتها.

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

اشتراكات المستخدمين

يمكن استخدام الطريقة نفسها التي تسرد المشتركين (subscriptions.list) لإدراج القنوات التي اشترك فيها المستخدم. يستخدم هذا الطلب المعلمة mine لاسترداد قائمة بقنوات YouTube التي اشترك فيها المستخدم الذي تمت مصادقته.

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

استرداد نشاط المستخدم

يحتوي مورد activity على معلومات حول إجراء اتخذته قناة معيّنة أو مستخدم معيّن على YouTube، مثل تحميل فيديو أو الاشتراك في قناة أو غير ذلك. تسترد طريقة activities.list الإجراءات المرتبطة بقناة أو مستخدم يطابق معايير الطلب. على سبيل المثال، يمكنك استرداد الإجراءات المرتبطة بقناة معينة أو باشتراكات المستخدم أو بصفحة YouTube الرئيسية المخصصة.

النشاط خلال فترة زمنية

يسترد هذا الطلب جميع الإجراءات التي اتخذها المستخدم الذي تمت مصادقته خلال نيسان (أبريل) 2013.

GET {base_URL}/activities?part=snippet,contentDetails
                         &mine=true
                         &publishedAfter=2013-04-01T00%3A00%3A00Z
                         &publishedBefore=2013-05-01T00%3A00%3A00Z

نشاط الصفحة الرئيسية

يسترد هذا الطلب خلاصة الأنشطة المخصصة التي يتم عرضها على صفحة YouTube الرئيسية للمستخدم الذي تمت المصادقة عليه. 

GET {base_URL}/activities?part=snippet,contentDetails
                         &home=true

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

بحث

تتيح لك طريقة search.list البحث عن فيديوهات أو قنوات أو قوائم تشغيل على YouTube تتطابق مع معايير محدّدة. ويمكنك البحث استنادًا إلى خصائص الفيديو أو الكلمات الرئيسية أو الموضوعات (أو مزيج من هذه العوامل)، ويمكنك ترتيب النتائج استنادًا إلى عوامل مثل تاريخ الإنشاء أو عدد المشاهدات أو التقييم.

مثل طلبات YouTube Data API الأخرى، تعرض طريقة search.list تمثيل JSON لمورد YouTube. وعلى عكس موارد YouTube الأخرى، لا تعد نتيجة البحث كائنًا ثابتًا له رقم تعريف فريد.

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

الفيديوهات الأكثر مشاهدة

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

GET {base_URL}/search?part=snippet
                     &forMine=true
                     &order=viewCount
                     &type=video

مقاطع فيديو عالية الدقة يمكن تضمينها

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

GET {base_URL}/search?part=snippet
                     &order=rating
                     &type=video
                     &videoDefinition=high
                     &videoEmbeddable=true
                     &key={YOUR_API_KEY}

مقاطع فيديو حول موضوع معين

يُجري هذا الطلب عملية بحث باستخدام كلمات رئيسية عن الفيديوهات حول YouTube Data API التي تتضمّن ترجمة.

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

البحث حسب الموضوع

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

للبحث باستخدام موضوع Freebase، يلزمك أولاً استرداد معرّف الموضوع باستخدام واجهة برمجة تطبيقات Freebase. يعرض هذا الطلب فيديوهات مرتبطة بموضوع Freebase للغة Python، ومعرّف الموضوع /m/05z1_.

GET {base_URL}/search?part=snippet
                     &topicId=/m/05z1_
                     &type=video
                     &key={YOUR_API_KEY}

البحث عن قوائم تشغيل أو قنوات

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

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

إذا كنت تفضل العثور على قنوات كرة القدم، فما عليك سوى تغيير المعلمة type.

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

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

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

إنشاء الموارد وتحديثها

وتستخدم الطلبات التي استعرضناها حتى الآن طريقة HTTP GET لاسترداد بيانات YouTube. تقدّم YouTube Data API أيضًا طرقًا تستخدم طريقة POST لبروتوكول HTTP لإنشاء موارد YouTube أو تعديلها، مثل الفيديوهات أو قوائم التشغيل أو القنوات. تقدم الطلبات التالية أمثلة على ذلك.

تتضمن طرق POST Request body، وهو تمثيل JSON للمورد الذي يتم إنشاؤه أو تحديثه. يمكنك إنشاء تمثيلات JSON في مستكشف Google APIs باستخدام أداة تفاعلية.

إنشاء اشتراك

ويشترك هذا الطلب المستخدم الذي تمت مصادقته في قناة GoogleDevelopers. بمعنى آخر، فإنه ينشئ موردًا للاشتراك.

POST {base_URL}/subscriptions?part=snippet
 Request body:
  {
    'snippet': {
      'resourceId': {
        'kind': 'youtube#channel',
        'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' 
       }
     }
  }

إنشاء قائمة تشغيل

ينشئ هذا الطلب قائمة تشغيل علنية جديدة.

POST {base_URL}/playlists?part=snippet
 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

إضافة مقطع فيديو إلى قائمة تشغيل

بعد أن أنشأنا قائمة تشغيل، لنضيف فيديو إليها. يضيف هذا الطلب فيديو إلى بداية قائمة التشغيل ('position': 0).

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }