نظرة عامة على YouTube Data API

 bookmark_border

المقدّمة

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

قبل البدء

1. يجب أن يكون لديك حساب Google للوصول إلى وحدة التحكم في Google API، وطلب مفتاح واجهة برمجة التطبيقات، وتسجيل تطبيقك.
2. أنشئ مشروعًا في Google Developers Console واحصل على بيانات اعتماد التفويض حتى يتمكن تطبيقك من إرسال طلبات واجهة برمجة التطبيقات.
3. بعد إنشاء مشروعك، تأكّد من أنّ YouTube Data API هي إحدى الخدمات التي تمّ تسجيل تطبيقك لاستخدامها:
   1. انتقِل إلى وحدة تحكُّم واجهة برمجة التطبيقات واختَر المشروع الذي سجَّلته للتو.
   2. انتقِل إلى صفحة واجهات برمجة التطبيقات التي تم تفعيلها. في قائمة واجهات برمجة التطبيقات، تأكَّد من أنّ الحالة مفعَّلة للالإصدار الثالث من YouTube Data API.
4. إذا كان تطبيقك سيستخدم أيًا من أساليب واجهة برمجة التطبيقات التي تتطلب ترخيص المستخدم، فاقرأ دليل المصادقة للتعرف على كيفية تطبيق ترخيص OAuth 2.0.
5. حدد مكتبة عميل لتبسيط عملية تطبيق واجهة برمجة التطبيقات.
6. تعرَّف على المفاهيم الأساسية لتنسيق بيانات JSON (JavaScript Object Notation). JSON هو تنسيق بيانات شائع ومستقل عن اللغة يوفّر تمثيلاً نصيًا بسيطًا لهياكل البيانات العشوائية. لمزيد من المعلومات، راجع json.org.

الموارد وأنواع الموارد

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

المراجِع
activity	يتضمن معلومات حول إجراء اتخذه مستخدم معين على موقع YouTube. وتشمل إجراءات المستخدم التي يتم الإبلاغ عنها في خلاصات الأنشطة تقييم الفيديو، ومشاركة فيديو، ووضع علامة على أحد الفيديوهات كمفضل، ونشر نشرة قناة، بالإضافة إلى إجراءات أخرى.
channel	تحتوي على معلومات حول قناة واحدة على YouTube.
channelBanner	يحدد عنوان URL الذي تريد استخدامه لضبط صورة تم تحميلها حديثًا كصورة بانر للقناة.
channelSection	يتضمن معلومات حول مجموعة فيديوهات اختارت القناة إبرازها. على سبيل المثال، قد يعرض القسم الفيديوهات التي حمّلتها مؤخرًا أو تلك الأكثر رواجًا أو فيديوهات من قائمة تشغيل واحدة أو أكثر.
guideCategory	يحدّد فئة تربطها منصة YouTube بالقنوات استنادًا إلى محتواها أو مؤشرات أخرى، مثل مدى الرواج. تسعى فئات الأدلة إلى تنظيم القنوات بطريقة تسهّل على مستخدمي YouTube العثور على المحتوى الذي يبحثون عنه. قد تكون القنوات مرتبطة بفئة أدلة واحدة أو أكثر، ولكن لا نضمن لك أن تكون ضمن أي فئة أدلة.
i18nLanguage	يحدّد لغة تطبيق متوافقة مع موقع YouTube الإلكتروني. يمكن أيضًا الإشارة إلى لغة التطبيق على أنها لغة واجهة المستخدم.
i18nRegion	تحدد منطقة جغرافية يمكن لمستخدم YouTube اختيارها كمنطقة المحتوى المفضلة. ويمكن أيضًا الإشارة إلى منطقة المحتوى على أنها لغة محتوى.
playlist	يمثّل هذا النوع قائمة تشغيل واحدة على YouTube. قائمة التشغيل هي مجموعة من الفيديوهات التي يمكن مشاهدتها بشكل تسلسلي ومشاركتها مع مستخدمين آخرين.
playlistItem	تحدد موردًا، مثل فيديو، يشكّل جزءًا من قائمة تشغيل. يحتوي مورد playlistItem أيضًا على تفاصيل تشرح كيفية استخدام المورد المضمّن في قائمة التشغيل.
search result	يحتوي على معلومات حول فيديو أو قناة أو قائمة تشغيل على YouTube تتطابق مع معلمات البحث المحدّدة في طلب من واجهة برمجة التطبيقات. تشير نتيجة البحث إلى مورد يمكن التعرّف عليه بشكل فريد، مثل فيديو، ولكنّها لا تحتوي على بيانات ثابتة خاصة بها.
subscription	تحتوي على معلومات حول اشتراك مستخدم YouTube. من خلال الاشتراك، يتم إرسال إشعار إلى المستخدم عند إضافة فيديوهات جديدة إلى القناة، أو عندما يتّخذ مستخدم آخر أحد الإجراءات المتعددة على YouTube، مثل تحميل فيديو أو تقييم فيديو أو التعليق على فيديو.
thumbnail	يحدد الصور المصغّرة المرتبطة بأحد الموارد.
video	يمثّل هذا العرض فيديو YouTube واحدًا.
videoCategory	يحدد فئة مرتبطة بفيديوهات تم تحميلها أو يمكن ربطها.
watermark	لتحديد صورة يتم عرضها أثناء تشغيل فيديوهات قناة محددة. يمكن لمالك القناة أيضًا تحديد قناة مستهدفة ترتبط بها الصورة، بالإضافة إلى تفاصيل التوقيت التي تحدد وقت ظهور العلامة المائية أثناء تشغيل الفيديوهات ومدة ظهورها.

لاحظ أنه في كثير من الحالات، يحتوي المورد على إشارات إلى موارد أخرى. على سبيل المثال، تحدد السمة snippet.resourceId.videoId لمورد playlistItem مورد فيديو يحتوي بدوره على معلومات كاملة عن الفيديو. كمثال آخر، تحتوي نتيجة البحث على السمة videoId أو playlistId أو channelId التي تحدّد فيديو أو قائمة تشغيل أو مورد قناة معيّنًا.

العمليات المتوافقة

يعرض الجدول التالي الطرق الأكثر شيوعًا التي تتيحها واجهة برمجة التطبيقات. تدعم بعض الموارد أيضًا طرقًا أخرى تؤدي وظائف أكثر تحديدًا لتلك الموارد. على سبيل المثال، تربط الطريقة videos.rate تقييم المستخدم بفيديو، وتحمّل الطريقة thumbnails.set صورة مصغّرة للفيديو إلى YouTube وتربطها بفيديو.

العمليات
list	استرداد (GET) قائمة تضم صفرًا أو أكثر من الموارد.
insert	ينشئ (POST) موردًا جديدًا.
update	تعديل (PUT) مورد حالي لإظهار البيانات في طلبك
delete	إزالة (DELETE) مورد محدَّد

توفر واجهة برمجة التطبيقات حاليًا طرقًا لسرد كل نوع من أنواع الموارد المتوافقة، كما توفر عمليات الكتابة للعديد من الموارد أيضًا.

يحدد الجدول أدناه العمليات المتاحة لأنواع مختلفة من الموارد. إنّ العمليات التي تُدرِج الموارد أو تحدّثها أو تحذفها تتطلّب دائمًا تفويض المستخدم. في بعض الحالات، تدعم طُرق list كلاً من الطلبات المُصرَّح بها وغير المصرَّح بها، حيث تسترد الطلبات غير المصرَّح بها البيانات العلنية فقط، بينما يمكن للطلبات التي تمت مصادقتها أيضًا استرداد معلومات حول المستخدم الذي تمت مصادقته حاليًا أو الخاصة به.

العمليات المتوافقة
	list	insert	update	delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

استخدام الحصة

تستخدم “YouTube Data API” حصة لضمان استخدام المطوّرين للخدمة على النحو المنشود، وعدم إنشاء تطبيقات تقلل بشكل غير عادل من جودة الخدمة أو تفرض قيودًا على وصول الآخرين. يتم تحصيل حصة من نقطة واحدة على الأقل في جميع طلبات البيانات من واجهة برمجة التطبيقات، بما في ذلك الطلبات غير الصالحة. يمكنك الاطّلاع على الحصة المتاحة لتطبيقك في API Console.

يتم تخصيص حصة تلقائية للمشاريع التي تفعّل YouTube Data API 10,000 وحدة في اليوم، وهو مبلغ كافٍ للغالبية الساحقة من مستخدمي واجهة برمجة التطبيقات. تساعدنا الحصة التلقائية، والتي تخضع للتغيير، على تحسين تخصيصات الحصص وتوسيع نطاق بنيتنا الأساسية بطريقة أكثر فائدة لمستخدمي واجهة برمجة التطبيقات. ويمكنك الاطّلاع على استخدام حصتك من خلال صفحة الحصص في وحدة تحكّم واجهة برمجة التطبيقات.

ملاحظة: إذا بلغت الحدّ الأقصى للحصة، يمكنك طلب حصة إضافية من خلال ملء نموذج طلب إضافة الحصة لخدمات YouTube API.

جارٍ احتساب استخدام الحصة

تحتسب Google استخدام حصتك من خلال تحديد تكلفة لكل طلب. وتختلف تكاليف الحصص باختلاف أنواع العمليات. مثلاً:

• إنّ عملية القراءة التي تسترد قائمة الموارد، مثل القنوات والفيديوهات وقوائم التشغيل، تكلف عادةً وحدة واحدة.
• عادةً ما تبلغ تكلفة عملية الكتابة التي تؤدي إلى إنشاء مورد أو تعديله أو حذفه 50 وحدة.
• يكلّف طلب البحث 100 وحدة.
• تبلغ تكلفة تحميل الفيديو 1600 وحدة.

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

الموارد الجزئية

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

تتيح واجهة برمجة التطبيقات استخدام مَعلمتَين لطلب البيانات، موضّحة في الأقسام التالية، تتيح لك تحديد خصائص الموارد التي يجب تضمينها في ردود واجهة برمجة التطبيقات.

• تحدد المعلمة part مجموعات من الخصائص التي يجب عرضها للمورد.
• تعمل المعلَمة fields على فلترة استجابة واجهة برمجة التطبيقات بحيث يتم عرض خصائص معيّنة فقط ضمن أجزاء الموارد المطلوبة.

كيفية استخدام المَعلمة part

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

• snippet
• contentDetails
• fileDetails
• player
• processingDetails
• recordingDetails
• statistics
• status
• suggestions
• topicDetails

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

• يقلل من وقت الاستجابة عن طريق منع خادم واجهة برمجة التطبيقات من قضاء وقت في استرداد حقول البيانات الوصفية التي لا يستخدمها تطبيقك.
• يقلل استخدام معدل نقل البيانات عن طريق تقليل (أو إزالة) كمية البيانات غير الضرورية التي قد يستردها تطبيقك.

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

كيفية استخدام المَعلمة fields

تعمل المَعلمة fields على فلترة استجابة واجهة برمجة التطبيقات التي تحتوي فقط على أجزاء الموارد المحدَّدة في قيمة المَعلمة part، بحيث لا يتضمّن الردّ سوى مجموعة محدّدة من الحقول. تتيح لك المَعلمة fields إزالة سمات مدمَجة من استجابة واجهة برمجة التطبيقات، ما يؤدي إلى تقليل استخدام معدل نقل البيانات بشكلٍ أكبر. (لا يمكن استخدام المَعلمة part لفلترة السمات المدمَجة من أحد الردود).

توضّح القواعد التالية البنية المتوافقة لقيمة المعلَمة fields، والتي تستند إلى بنية XPath بشكل غير دقيق:

• استخدِم قائمة مفصولة بفواصل (fields=a,b) لاختيار عدة حقول.
• يمكنك استخدام علامة النجمة (fields=*) كحرف بدل لتحديد جميع الحقول.
• استخدِم الأقواس (fields=a(b,c)) لتحديد مجموعة من السمات المدمَجة التي سيتم تضمينها في استجابة واجهة برمجة التطبيقات.
• استخدِم شرطة مائلة للأمام (fields=a/b) لتحديد سمة مدمجة.

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

• fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
• fields=items(id,snippet/title,snippet/position)
• fields=items(id,snippet(title,position))

ملاحظة: كما هو الحال في جميع قيم مَعلمات طلب البحث، يجب ترميز قيمة المَعلمة fields بعنوان URL. لتسهيل القراءة، لا تتضمن الأمثلة في هذا المستند الترميز.

نماذج من الطلبات الجزئية

توضّح الأمثلة أدناه كيفية استخدام المعلّمتَين part وfields لضمان أنّ ردود واجهة برمجة التطبيقات لا تتضمّن سوى البيانات التي يستخدمها تطبيقك:

1. يعرض المثال 1 مورد فيديو يتضمن أربعة أجزاء، بالإضافة إلى الخاصيتين kind وetag.
2. يعرض المثال 2 مورد فيديو يتضمن جزأين، بالإضافة إلى خاصيتين kind وetag.
3. يعرض المثال 3 مورد فيديو يتضمن جزأين، ولكنه يستثني الخاصيتين kind وetag.
4. يعرض المثال 4 مورد فيديو يتضمن جزأين، لكنه يستثني kind وetag بالإضافة إلى بعض الخصائص المدمجة في كائن snippet للمورد.

مثال 1المثال 2المثال 3مثال 4

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:

{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}

تحسين الأداء

استخدام علامات ETag

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

• التخزين المؤقت والاسترداد المشروط: يمكن للتطبيق أن يخزّن موارد واجهة برمجة التطبيقات وعلامات ETag الخاصة بها مؤقتًا. وبعد ذلك، عندما يطلب التطبيق موردًا مخزَّنًا مرة أخرى، يتم تحديد علامة ETag المرتبطة بهذا المورد. في حال تم تغيير المورد، ستعرض واجهة برمجة التطبيقات المورد المعدّل وعلامة ETag المرتبطة بهذا الإصدار من المورد. إذا لم يتم تغيير المورد، ستعرض واجهة برمجة التطبيقات استجابة HTTP 304 (Not Modified)، ما يشير إلى أنّ المورد لم يتغيّر. يمكن للتطبيق تقليل وقت الاستجابة واستخدام معدل نقل البيانات من خلال عرض الموارد المخزَّنة مؤقتًا بهذه الطريقة.تختلف مكتبات برامج Google APIs في دعمها لـ ETags. على سبيل المثال، تتيح مكتبة برامج JavaScript علامات ETag من خلال قائمة بيضاء لعناوين الطلبات المسموح بها التي تتضمن If-Match وIf-None-Match. وتسمح القائمة البيضاء بحدوث التخزين المؤقت العادي للمتصفح بحيث إذا لم يتم تغيير علامة ETag للمورد، يمكن عرض المورد من ذاكرة التخزين المؤقت للمتصفح. من ناحية أخرى، لا يتيح برنامج Obj-C استخدام علامات ETag.
• الحماية من استبدال التغييرات بشكل غير مقصود: تساعد علامات ETag في ضمان عدم استبدال التغييرات التي يجريها العديد من برامج واجهة برمجة التطبيقات عن غير قصد. عند تعديل مورد أو حذفه، يمكن لتطبيقك تحديد علامة ETag للمورد. وفي حال عدم تطابق علامة ETag مع أحدث إصدار من ذلك المورد، سيتعذّر تنفيذ طلب البيانات من واجهة برمجة التطبيقات.

يوفّر استخدام علامات ETag في تطبيقك العديد من المزايا:

• وتستجيب واجهة برمجة التطبيقات بشكل أسرع لطلبات الموارد المخزَّنة مؤقتًا ولكن التي لم يتم تغييرها، ما يؤدي إلى تقليل وقت الاستجابة واستخدام معدل نقل بيانات أقل.
• لن يستبدل تطبيقك بدون قصد التغييرات في مورد تم إجراؤه من برنامج واجهة برمجة تطبيقات آخر.

تتوافق Google APIs Client Library for JavaScript مع عناوين طلبات HTTP التي تتضمّن If-Match وIf-None-Match، ما يؤدي إلى تفعيل علامات ETag داخل سياق التخزين المؤقت العادي للمتصفح.

استخدام برنامج gzip

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

لتلقي استجابة بترميز gzip، يجب عليك القيام بأمرين:

• اضبط عنوان طلب HTTP Accept-Encoding على gzip.
• عليك تعديل وكيل المستخدم ليتضمن السلسلة gzip.

يوضح نموذج رؤوس HTTP أدناه هذه المتطلبات لتفعيل ضغط gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)