Captions: list

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

تأثیر سهمیه: فراخوانی این روش هزینه سهمیه ۵۰ واحدی دارد.

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

درخواست

درخواست 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 را که پاسخ میانای برنامه‌سازی کاربردی شامل خواهد شد مشخص می‌کند.

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

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

متن درخواست

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

پاسخ

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

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

مشخصات

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

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

خطاها

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

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

امتحان کنید!

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