Captions: insert

یک تراک شرح آپلود می کند.

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

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

تاثیر سهمیه ای: فراخوانی به این روش هزینه سهمیه ای 400 واحدی دارد.

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

درخواست کنید

درخواست 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 را که پاسخ API شامل می شود را مشخص می کند. مقدار پارامتر را روی snippet تنظیم کنید.

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

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

پارامتر onBehalfOfContentOwner نشان می دهد که اعتبارنامه مجوز درخواست، کاربر YouTube CMS را شناسایی می کند که از طرف مالک محتوا مشخص شده در مقدار پارامتر عمل می کند. این پارامتر برای شرکای محتوای YouTube در نظر گرفته شده است که کانال‌های مختلف YouTube را مالک و مدیریت می‌کنند. این به صاحبان محتوا امکان می‌دهد یک بار احراز هویت کنند و به تمام داده‌های ویدیویی و کانال خود دسترسی داشته باشند، بدون اینکه نیازی به ارائه اعتبارنامه احراز هویت برای هر کانال جداگانه داشته باشند. حساب CMS واقعی که کاربر با آن احراز هویت می‌کند باید به مالک محتوای 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 مشخص شده در درخواست خیلی طولانی است. حداکثر طول پشتیبانی شده 150 کاراکتر است.

آن را امتحان کنید!

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

،

یک تراک شرح آپلود می کند.

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

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

تاثیر سهمیه ای: فراخوانی به این روش هزینه سهمیه ای 400 واحدی دارد.

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

درخواست کنید

درخواست 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 را که پاسخ API شامل می شود را مشخص می کند. مقدار پارامتر را روی snippet تنظیم کنید.

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

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

پارامتر onBehalfOfContentOwner نشان می دهد که اعتبارنامه مجوز درخواست، کاربر YouTube CMS را شناسایی می کند که از طرف مالک محتوا مشخص شده در مقدار پارامتر عمل می کند. این پارامتر برای شرکای محتوای YouTube در نظر گرفته شده است که کانال‌های مختلف YouTube را مالک و مدیریت می‌کنند. این به صاحبان محتوا امکان می‌دهد یک بار احراز هویت کنند و به تمام داده‌های ویدیویی و کانال خود دسترسی داشته باشند، بدون اینکه نیازی به ارائه اعتبارنامه احراز هویت برای هر کانال جداگانه داشته باشند. حساب CMS واقعی که کاربر با آن احراز هویت می‌کند باید به مالک محتوای 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 مشخص شده در درخواست خیلی طولانی است. حداکثر طول پشتیبانی شده 150 کاراکتر است.

آن را امتحان کنید!

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