پیاده‌سازی: زیرنویس ناشنوایان

نمونه‌های زیر نحوه استفاده از YouTube Data API (نسخه ۳) را برای انجام عملکردهای مربوط به زیرنویس ناشنوایان نشان می‌دهد.

بازیابی فهرست قطعه‌های زیرنویس ناشنوایان برای ویدیو

برای بازیابی فهرستی از قطعه‌های زیرنویس ناشنوایان که برای یک ویدیو خاص دردسترس هستند، روش captions.list را فراخوانی کنید. مقدار پارامتر videoId را روی شناسه ویدیو YouTube تنظیم کنید که به‌طور منحصربه‌فرد ویدیویی را که زیرنویس ناشنوایان آن را بازیابی می‌کنید شناسایی می‌کند. درخواست شما باید بااستفاده از OAuth 2.0 مجاز شود.

درخواست زیر فهرستی از زیرنویس‌های ناشنوایان را برای ویدیویی در کانال YouTube «داستان‌های Google» بازیابی می‌کند:

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

برای نمونه‌های کد، مستندات روش captions.list را ببینید.

ساختن قطعه زیرنویس ناشنوایان

این پُرسمان را نمی‌توان بااستفاده از APIs Explorer آزمایش کرد زیرا APIs Explorer از قابلیت بارگذاری فایل پشتیبانی نمی‌کند، که این قابلیت برای این روش الزامی است.

می‌توانید از روش captions.insert API برای بارگذاری یک قطعه زیرنویس ناشنوایان جدید برای یک ویدیو استفاده کنید. هنگام بارگذاری قطعه، باید مقداری برای ویژگی‌های منبع caption زیر مشخص کنید:

  • ‫snippet.videoId - این ویدیو را که قطعه زیرنویس ناشنوایان به آن اضافه می‌شود شناسایی می‌کند.
  • snippet.language - زبان قطعه زیرنویس ناشنوایان.
  • snippet.name - نام قطعه زیرنویس ناشنوایان.

هنگام بارگذاری قطعه زیرنویس ناشنوایان، گزینه‌های اضافی زیر دردسترس هستند:

  • اگر پارامتر sync را روی true تنظیم کنید، YouTube هرگونه کد زمانی موجود در فایل زیرنویس ناشنوایان بارگذاری‌شده را نادیده می‌گیرد و کدهای زمانی جدیدی برای زیرنویس ناشنوایان تولید می‌کند.

    اگر درحال بارگذاری ترانویسی هستید که کد زمانی ندارد، یا اگر فکر می‌کنید کدهای زمانی در فایل شما نادرست است و می‌خواهید YouTube سعی کند آن‌ها را اصلاح کند، باید پارامتر sync را روی true تنظیم کنید.

  • اگر دارایی caption را روی snippet.isDrafttrue تنظیم کنید، قطعه به‌صورت عمومی قابل‌مشاهده نخواهد بود.

برای نمونه‌های کد، مستندات روش captions.insert را ببینید.

بارگیری قطعه زیرنویس ناشنوایان

این پُرسمان را نمی‌توان بااستفاده از «کاوشگر میاناهای برنامه‌سازی کاربردی» آزمایش کرد زیرا «کاوشگر میاناهای برنامه‌سازی کاربردی» از قابلیت بارگیری فایل‌ها پشتیبانی نمی‌کند.

برای بارگیری یک قطعه زیرنویس ناشنوایان خاص، روش captions.download را فراخوانی کنید. مقدار پارامتر id را روی شناسه قطعه زیرنویس ناشنوایان YouTube تنظیم کنید که قطعه زیرنویس ناشنوایان درحال بارگیری را به‌طور منحصربه‌فرد شناسایی می‌کند. درخواست شما باید بااستفاده از OAuth 2.0 مجاز شود.

میانای برنامه‌سازی کاربردی نسخه ۳ از گزینه‌های زیر پشتیبانی می‌کند:

  • برای مشخص کردن اینکه یک قطعه زیرنویس ناشنوایان باید در یک قالب خاص برگردانده شود، مقدار پارامتر tfmt را برای شناسایی قالب موردنظر تنظیم کنید. تعریف پارامتر مقادیر پشتیبانی‌شده را فهرست می‌کند.

  • برای بازیابی ترجمه قطعه زیرنویس ناشنوایان، مقدار پارامتر tlang را روی کد زبان دو حرفی ISO 639-1 تنظیم کنید که زبان زیرنویس ناشنوایان موردنظر را مشخص می‌کند. ترجمه بااستفاده از ترجمه ماشینی، مثل «ترجمه Google»، تولید شده است.

برای نمونه‌های کد، به مستندات روش captions.download مراجعه کنید.

به‌روزرسانی قطعه زیرنویس ناشنوایان

این API از توانایی تغییر وضعیت پیش‌نویس قطعه زیرنویس ناشنوایان، بارگذاری قطعه زیرنویس ناشنوایان جدید برای یک فایل، یا هر دو پشتیبانی می‌کند.

می‌توانید از «کاوشگر میاناهای برنامه‌سازی کاربردی» برای آزمایش کردن قابلیت تغییر وضعیت پیش‌نویس دسته هدف استفاده کنید. بااین‌حال، نمی‌توانید از «کاوشگر میاناهای برنامه‌سازی کاربردی» برای به‌روزرسانی قطعه زیرنویس ناشنوایان واقعی استفاده کنید زیرا این ابزار از قابلیت بارگذاری فایل پشتیبانی نمی‌کند.

درخواست زیر فهرستی از زیرنویس‌های ناشنوایان را برای ویدیویی در کانال YouTube «داستان‌های Google» بازیابی می‌کند:

این درخواست وضعیت پیش‌نویس یک قطعه زیرنویس ناشنوایان را به true به‌روز می‌کند، به این معنی که قطعه به‌صورت عمومی قابل مشاهده نخواهد بود. برای تکمیل درخواست در APIs Explorer، باید مقدار ویژگی id را برای شناسایی قطعه زیرنویس ناشنوایان تنظیم کنید.

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

برای نمونه‌های کد، به مستندات روش captions.update مراجعه کنید.

حذف قطعه زیرنویس ناشنوایان

این مثال نشان می‌دهد که چگونه یک قطعه زیرنویس ناشنوایان را حذف کنید. مثال شامل مراحل زیر است:

  • مرحله ۱: بازیابی شناسه قطعه زیرنویس ناشنوایان

    مراحل بالا را برای بازیابی فهرست قطعه‌های زیرنویس ناشنوایان برای یک ویدیو دنبال کنید. از این فهرست می‌توان برای نمایش فهرستی از قطعه‌های زیرنویس ناشنوایان استفاده کرد، به‌طوری‌که شناسه هر قطعه به‌عنوان کلید استفاده شود.

  • مرحله ۲: حذف قطعه

    برای حذف کردن یک ویدیو خاص، روش captions.delete را فراخوانی کنید. در درخواست، پارامتر id شناسه قطعه زیرنویس ناشنوایان قطعه‌ای را که حذف می‌کنید مشخص می‌کند. درخواست باید بااستفاده از OAuth 2.0 مجاز شود. اگر این پُرسمان را در «کاوشگر میاناهای برنامه‌سازی کاربردی» آزمایش می‌کنید، باید شناسه قطعه زیرنویس ناشنوایان معتبری را جایگزین مقدار پارامتر id کنید.

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