التنفيذ: التسميات التوضيحية

توضح الأمثلة التالية كيفية استخدام واجهة برمجة تطبيقات البيانات في YouTube (الإصدار 3) لتنفيذ وظائف مرتبطة بالتسميات التوضيحية.

استرداد قائمة مسارات التسميات التوضيحية لمقطع فيديو

لاسترداد قائمة مسارات التسميات التوضيحية المتوفرة لمقطع فيديو معين، يمكنك استدعاء طريقة captions.list. اضبط قيمة المَعلمة videoId على معرّف فيديو YouTube الذي يحدّد بشكلٍ فريد الفيديو الذي تستردّ له ترجمة. يجب أن تتم الموافقة على طلبك باستخدام OAuth 2.0.

يسترد الطلب التالي قائمة تسميات توضيحية لمقطع فيديو على قناة قصص Google على YouTube:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.list?
part=snippet
&videoId=PRU2ShMzQRg

يمكنك الاطّلاع على وثائق طريقة captions.list للحصول على نماذج رموز.

إنشاء مسار تسمية توضيحية

لا يمكن اختبار طلب البحث هذا باستخدام مستكشف واجهات برمجة التطبيقات نظرًا لأن مستكشف واجهات برمجة التطبيقات لا يتيح إمكانية تحميل الملفات، وهو أحد متطلبات هذه الطريقة.

يمكنك استخدام طريقة واجهة برمجة التطبيقات captions.insert لتحميل مسار ترجمة جديد لفيديو. عند تحميل مقطع صوتي، يجب عليك تحديد قيمة لمواقع الموارد caption التالية:

  • snippet.videoId - يحدد هذا العمود الفيديو الذي تتم إضافة مسار التسمية التوضيحية إليه.
  • snippet.language - لغة مسار الترجمة.
  • snippet.name - اسم مسار الترجمة.

تتوفر الخيارات الإضافية التالية عند تحميل مسار تسمية توضيحية:

  • في حال ضبط المَعلمة sync على true، سيتجاهل YouTube أي رموز زمنية مضمّنة في ملف الترجمة الذي تم تحميله وسينشئ رموزًا زمنية جديدة للشرح.

    ننصحك بضبط المَعلمة sync على true إذا كنت تحمّل نصًا لا يتضمّن رموزًا زمنية أو إذا كنت تظن أنّ الرموز الزمنية في ملفك غير صحيحة وأردت أن يحاول YouTube إصلاحها.

  • إذا عيّنت خاصية snippet.isDraft لمورد caption على true، فلن يكون المسار مرئيًا بشكل علني.

يمكنك الاطّلاع على وثائق طريقة captions.insert للحصول على نماذج رموز.

تنزيل مسار تسمية توضيحية

لا يمكن اختبار طلب البحث هذا باستخدام مستكشف واجهات برمجة التطبيقات نظرًا لأن مستكشف واجهات برمجة التطبيقات لا يتيح إمكانية تنزيل الملفات.

لتنزيل مسار ترجمة معيّن، يمكنك استدعاء طريقة captions.download. اضبط قيمة المَعلمة id على رقم تعريف مسار الترجمة في YouTube الذي يحدّد بشكلٍ فريد مسار الترجمة الذي يتمّ تنزيله. يجب أن تتم الموافقة على طلبك باستخدام OAuth 2.0.

تتيح واجهة برمجة التطبيقات الإصدار 3 استخدام الخيارات التالية:

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

  • لاسترداد ترجمة مسار ترجمة، اضبط قيمة المعلمة tlang على رمز لغة مؤلف من حرفين بتنسيق ISO 639-1 يحدد لغة الترجمة المطلوبة. ويتم إنشاء الترجمة باستخدام الترجمة الآلية مثل "ترجمة Google".

يمكنك الاطّلاع على وثائق طريقة captions.download للحصول على نماذج رموز.

تعديل مسار ترجمة

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

يمكنك استخدام مستكشف واجهات برمجة التطبيقات لاختبار إمكانية تغيير حالة مسودة مقطع صوتي. مع ذلك، لا يمكنك استخدام مستكشف واجهات برمجة التطبيقات لتحديث مسار الترجمة الفعلي لأن الأداة لا تتيح إمكانية تحميل الملفات.

يسترد الطلب التالي قائمة تسميات توضيحية لمقطع فيديو على قناة قصص Google على YouTube:

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

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.update?
part=snippet

يمكنك الاطّلاع على وثائق طريقة captions.update للحصول على نماذج رموز.

حذف مسار تسمية توضيحية

يوضح هذا المثال كيفية حذف مسار تسمية توضيحية. يحتوي المثال على الخطوات التالية:

  • الخطوة 1: استرداد رقم تعريف مسار الترجمة

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

  • الخطوة 2: حذف المقطع الصوتي

    ويمكنك استدعاء طريقة captions.delete لحذف فيديو معيّن. في الطلب، تحدد المعلمة id رقم تعريف مسار الترجمة للمقطع الصوتي الذي تريد حذفه. يجب تفويض الطلب باستخدام OAuth 2.0. إذا كنت تختبر هذا الطلب في "مستكشف واجهات برمجة التطبيقات"، ستحتاج إلى استبدال رقم تعريف صالح لمسار الترجمة إلى قيمة المعلَمة id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.delete?
id=CAPTION_TRACK_ID