Captions: insert

قطعه زیرنویس ناشنوایان را بارگذاری می‌کند.

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

  • حداکثر اندازه فایل: ۱۰۰ مگابایت
  • انواع MIME رسانه پذیرفته‌شده: text/xml، application/octet-stream، */*

تأثیر سهمیه: تماس با این روش هزینه سهمیه ۴۰۰ واحدی دارد.

موارد استفاده رایج

درخواست

درخواست HTTP

POST https://www.googleapis.com/upload/youtube/v3/captions

صدور مجوز

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

حوزه
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

پارامترها

جدول زیر پارامترهایی را که این پُرسمان پشتیبانی می‌کند فهرست می‌کند. همه پارامترهای فهرست‌شده پارامترهای پُرسمان هستند.

پارامترها
پارامترهای الزامی
part string
پارامتر part بخش‌های منبع caption را که پاسخ میانای برنامه‌سازی کاربردی شامل خواهد شد مشخص می‌کند. مقدار پارامتر را روی snippet تنظیم کنید.

فهرست زیر شامل نام‌های part است که می‌توانید در مقدار پارامتر بگنجانید:
  • id
  • snippet
پارامترهای اختیاری
onBehalfOfContentOwner string
این پارامتر فقط در درخواست مجاز مناسب قابل استفاده است.

توجه: این پارامتر منحصراً برای شرکای محتوای YouTube درنظر گرفته شده است.

پارامتر onBehalfOfContentOwner نشان می‌دهد که اطلاعات اعتباری مجوز درخواست، کاربر YouTube CMS را که ازطرف مالک محتوای مشخص‌شده در مقدار پارامتر عمل می‌کند، شناسایی می‌کند. این پارامتر برای شرکای محتوای YouTube که مالک و مدیر بسیاری از کانال‌های مختلف YouTube هستند درنظر گرفته شده است. این ویژگی به مالکان محتوا اجازه می‌دهد یک‌بار اصالت‌سنجی کنند و به همه داده‌های ویدیو و کانال خود دسترسی پیدا کنند، بدون اینکه نیاز باشد برای هر کانال به‌طور جداگانه اعتبارنامه‌های اصالت‌سنجی ارائه دهند. حساب واقعی «سیستم مدیریت محتوا» که کاربر با آن اصالت‌سنجی می‌کند باید به مالک محتوای YouTube مشخص‌شده پیوند داده شود.
sync boolean
این پارامتر منسوخ شده است. پارامتر sync نشان می‌دهد که آیا YouTube باید به‌طور خودکار فایل زیرنویس ناشنوایان را با قطعه صوتی ویدیو همگام‌سازی کند یا نه. اگر مقدار را روی true تنظیم کنید، YouTube هر کد زمانی را که در فایل زیرنویس بارگذاری‌شده وجود دارد نادیده می‌گیرد و کدهای زمانی جدیدی برای زیرنویس‌ها تولید می‌کند.

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

متن درخواست

منبع caption را در متن درخواست ارائه دهید. برای آن منبع:

باید مقداری برای این دارایی‌ها مشخص کنید:

  • snippet.videoId
  • snippet.language
  • snippet.name

می‌توانید برای این مشخصات مقدار تنظیم کنید:

  • snippet.videoId
  • snippet.language
  • snippet.name
  • snippet.isDraft

پاسخ

اگر موفقیت‌آمیز باشد، این روش منبع caption را در بدنه پاسخ برمی‌گرداند.

خطاها

جدول زیر پیام‌های خطایی را که ممکن است API در پاسخ به فراخوانی این روش برگرداند، مشخص می‌کند. برای جزئیات بیشتر، YouTube Data API - Errors را ببینید.

نوع خطا جزئیات خطا شرح
badRequest (400) contentRequired درخواست حاوی محتوای قطعه زیرنویس ناشنوایان نیست.
conflict (409) captionExists ویدیو مشخص‌شده ازقبل دارای قطعه زیرنویس ناشنوایان با snippet.language و snippet.name داده‌شده است. یک ویدیو می‌تواند چندین قطعه برای یک زبان داشته باشد، اما هر قطعه باید نام متفاوتی داشته باشد.

چندین راه برای رفع این خطا وجود دارد. می‌توانید قطعه موجود را حذف کنید و سپس قطعه جدیدی درج کنید یا نام قطعه جدید را قبل‌از درج کردن تغییر دهید.
forbidden (403) forbidden اجازه‌های مرتبط با درخواست برای بارگذاری قطعه زیرنویس ناشنوایان کافی نیست. درخواست ممکن است به‌درستی مجاز نشده باشد.
invalidValue (400) invalidMetadata درخواست حاوی مقادیر فراداده نامعتبر است که مانع از ایجاد قطعه می‌شود. تأیید کنید که درخواست مقادیر معتبری را برای ویژگی‌های snippet.language، snippet.name، و snippet.videoId مشخص می‌کند. ویژگی snippet.isDraft را نیز می‌توان گنجاند، اما الزامی نیست.
notFound (404) videoNotFound ویدیو شناسایی‌شده با پارامتر videoId پیدا نشد.
invalidValue (400) nameTooLong ‫snippet.name مشخص‌شده در درخواست خیلی طولانی است. حداکثر طول پشتیبانی‌شده ۱۵۰ نویسه است.

امتحان کنید!

برای فراخوانی این API و دیدن درخواست و پاسخ API، از APIs Explorer استفاده کنید.