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

مقدمة

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

قبل البدء

1. يجب أن يكون لديك حساب Google للوصول إلى Google Cloud Console وطلب مفتاح واجهة برمجة التطبيقات وتسجيل تطبيقك.

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

3. بعد إنشاء مشروعك، تأكَّد من أنّ YouTube Data API هي إحدى الخدمات التي تم تسجيل تطبيقك لاستخدامها:

   1. انتقِل إلى Cloud Console واختَر المشروع الذي سجّلته للتو.
   2. انتقِل إلى صفحة واجهات برمجة التطبيقات المفعَّلة. تأكَّد من أنّ YouTube Data API مدرَجة في قائمة واجهات برمجة التطبيقات المفعَّلة. وإذا لم تكن مفعَّلة، افتح مكتبة واجهة برمجة التطبيقات وفعِّل واجهة برمجة التطبيقات.

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

5. حدد مكتبة عميل لتبسيط عملية تطبيق واجهة برمجة التطبيقات.

6. التعرّف على المفاهيم الأساسية لتنسيق بيانات JSON (JavaScript Object Notation) ‫JSON هو تنسيق بيانات شائع مستقل عن اللغة يقدّم تمثيلاً نصيًا بسيطًا عن بنى عشوائية للبيانات. لمزيد من المعلومات، راجع json.org‎‏.

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

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

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

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

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

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

يوضّح الجدول أدناه العمليات المتاحة لأنواع مختلفة من الموارد. تتطلّب العمليات التي تُدرج الموارد أو تعدّلها أو تحذفها دائمًا تفويضًا من المستخدم. In some cases, list methods support both authorized and unauthorized requests, where unauthorized requests only retrieve public data while authorized requests can also retrieve information about or private to the currently authenticated user.

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

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

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

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

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

تحتسب Google نسبة استهلاكك من الحصة عن طريق تخصيص تكلفة لكل طلب. تختلف تكلفة الحصة باختلاف أنواع العمليات. على سبيل المثال:

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

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

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

تسمح واجهة برمجة التطبيقات باسترداد الموارد الجزئية، بل وتتطلب ذلك، حتى تتجنب التطبيقات نقل البيانات غير الضرورية وتحليلها وتخزينها. يضمن هذا النهج أيضًا أن تستخدم واجهة برمجة التطبيقات موارد الشبكة و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 الخاص بالمرجع.

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

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

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the 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"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:

{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "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"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:

{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

تحسين الأداء

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