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

مقدمة

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

قبل البدء

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

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

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

   1. انتقِل إلى وحدة تحكم واجهة برمجة التطبيقات واختَر المشروع الذي سجّلته للتو.
   2. انتقِل إلى صفحة واجهات برمجة التطبيقات التي تم تفعيلها. في قائمة واجهات برمجة التطبيقات، تأكّد من أنّ الحالة مفعّلة للإصدار 3 من 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 وتربطها بفيديو.

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

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

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

تستخدم "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 للمورد.

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)