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

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

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

نظرة عامة

لتوضيح طريقة العرض، تُظهر النماذج في هذه الصفحة العناصر المميزة لكل طلب وتختصر عنوان URL الأساسي للمضيف الذي يعالج طلبات Data API (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 APIs الحق في تنفيذ طلبات YouTube Data API بالنيابة عنه. (راجع تنفيذ مصادقة OAuth 2.0 للحصول على تفاصيل حول تفويض الوصول إلى بيانات القناة الخاصة). بعد الربط بمستكشف واجهات برمجة التطبيقات، انقر على الزر تفويض الطلبات باستخدام OAuth 2.0. تسمح هذه الخطوة لـ "مستكشف واجهات برمجة التطبيقات" بتقديم طلبات نيابةً عن المالك. كما يمكنك تحديد نطاق التفويض، الذي يحدد أنواع الطلبات التي يمكن لمستكشف واجهات برمجة التطبيقات تنفيذها.

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

• مقتطف
• contentDetails
• اللاعب
• علم الإحصاء
• status

وجميع هذه الأجزاء هي كائنات تحتوي على خصائص متداخلة، ويمكنك اعتبار هذه الكائنات مجموعات من حقول البيانات الوصفية التي قد يستردها خادم واجهة برمجة التطبيقات (أو لا يستردها). وبناءً على ذلك، تتطلب منك المَعلمة 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" لكل عنصر تم إرجاعه هي معرّف عنصر قائمة التشغيل الخاص به. معرّف الفيديو لعنصر قائمة التشغيل هو videoId في الجزء contentDetails.

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

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

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

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

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

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

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".

بحث

تتيح لك الطريقة 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 والتي تتضمّن ترجمة.

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 API. يعرض هذا الطلب الفيديوهات المرتبطة بموضوع 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 أيضًا طرقًا تستخدم HTTP POST لإنشاء أو تحديث موارد YouTube مثل مقاطع الفيديو أو قوائم التشغيل أو القنوات. تقدم الطلبات التالية أمثلة.

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

إنشاء اشتراك

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

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
      }
   }