Captions: list

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

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

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

درخواست

درخواست HTTP

GET https://www.googleapis.com/youtube/v3/captions

مجوز

این درخواست به مجوز حداقل با یکی از حوزه های زیر نیاز دارد ( در مورد احراز هویت و مجوز بیشتر بخوانید ).

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

مولفه های

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

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

لیست زیر شامل نام part است که می توانید در مقدار پارامتر بگنجانید:
  • id
  • snippet
videoId string
پارامتر videoId شناسه ویدیوی YouTube را مشخص می‌کند که API باید آهنگ‌های زیرنویس را برای آن برگرداند.
پارامترهای اختیاری
id string
پارامتر id فهرستی از شناسه‌های جدا شده با کاما را مشخص می‌کند که منابع caption را که باید بازیابی شوند، مشخص می‌کند. هر شناسه باید یک تراک شرح مرتبط با ویدیوی مشخص شده را شناسایی کند.
onBehalfOfContentOwner string
این پارامتر فقط در یک درخواست مجاز به درستی قابل استفاده است. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube در نظر گرفته شده است.

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

درخواست بدن

هنگام فراخوانی این روش، بدنه درخواست ارائه نکنید.

واکنش

در صورت موفقیت آمیز بودن، این روش یک بدنه پاسخ با ساختار زیر را برمی گرداند:

{
  "kind": "youtube#captionListResponse",
  "etag": etag,
  "items": [
    caption Resource
  ]
}

خواص

جدول زیر ویژگی های ظاهر شده در این منبع را تعریف می کند:

خواص
kind string
نوع منبع API را مشخص می کند. مقدار youtube#captionListResponse خواهد بود.
etag etag
Etag این منبع
items[] list
فهرستی از شرح‌ها که با معیارهای درخواست مطابقت دارند.

خطاها

جدول زیر پیام های خطایی را مشخص می کند که API می تواند در پاسخ به تماس با این روش بازگرداند. لطفاً برای جزئیات بیشتر به مستندات پیام خطا مراجعه کنید.

نوع خطا جزئیات خطا شرح
forbidden (403) forbidden یک یا چند تراک شرح بازیابی نشد زیرا مجوزهای مرتبط با درخواست برای بازیابی منابع درخواستی کافی نیست. ممکن است درخواست به درستی مجاز نباشد.
notFound (404) captionNotFound یک یا چند تراک شرح مشخص شده یافت نشد. اگر پارامتر videoId یک ویدیوی واقعی را شناسایی کند، این خطا رخ می‌دهد، اما پارامتر id یا شناسه‌های تراک شرح را شناسایی می‌کند که وجود ندارند یا شناسه‌های ردیابی را که با ویدیوهای دیگر مرتبط هستند. مقادیر پارامترهای id و videoId درخواست را بررسی کنید تا مطمئن شوید که درست هستند.
notFound (404) videoNotFound ویدیوی شناسایی شده توسط پارامتر videoId یافت نشد.

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

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