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

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

للحصول على معلومات حول تحميل المحتوى باستخدام 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 في الطلب أجزاء المورد التي يتم تضمينها في الاستجابة. تحدّد المَعلمة سمة واحدة أو أكثر من سمات الموارد ذات المستوى الأعلى (غير المدمجة) التي يجب تضمينها في الاستجابة. على سبيل المثال، في ما يلي بعض أجزاء مورد video:

• مقتطف
• 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 APIs Explorer، استبدِل {UPLOADS_PLAYLIST_ID} برقم تعريف قائمة التشغيل من الطلب السابق.

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

يُرجى العِلم أنّ قيمة "id" لكل عنصر يتم عرضه هي معرّف playlistItem. معرّف الفيديو لعنصر قائمة التشغيل هو 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، يمكنك استخدام YouTube Analytics API. تعرض صفحة نموذج طلبات البيانات من واجهة برمجة التطبيقات كيفية استرداد التقارير الشائعة من "إحصاءات 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 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 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 APIs Explorer باستخدام أداة تفاعلية.

إنشاء اشتراك

يؤدي هذا الطلب إلى اشتراك المستخدم الذي تمت المصادقة عليه في قناة 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
      }
   }