Playlists: list

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

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

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

درخواست

درخواست HTTP

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

مولفه های

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

مولفه های
پارامترهای مورد نیاز
part string
پارامتر part یک لیست جدا شده با کاما از یک یا چند ویژگی منبع playlist را مشخص می کند که پاسخ API شامل آن خواهد شد.

اگر پارامتر خاصیتی را مشخص کند که حاوی ویژگی های فرزند است، ویژگی های فرزند در پاسخ گنجانده می شود. به عنوان مثال، در یک منبع playlist ، ویژگی snippet حاوی ویژگی هایی مانند author ، title ، description و timeCreated است. به این ترتیب، اگر part=snippet تنظیم کنید، پاسخ API حاوی تمام آن ویژگی ها خواهد بود.

لیست زیر شامل نام part است که می توانید در مقدار پارامتر بگنجانید:
  • contentDetails
  • id
  • localizations
  • player
  • snippet
  • status
فیلترها (دقیقا یکی از پارامترهای زیر را مشخص کنید)
channelId string
این مقدار نشان می دهد که API فقط باید لیست های پخش کانال مشخص شده را برگرداند.
id string
پارامتر id فهرستی از شناسه(های) لیست پخش YouTube را برای منبع(های) بازیابی شده با کاما مشخص می کند. در یک منبع playlist ، ویژگی id شناسه لیست پخش YouTube لیست پخش را مشخص می کند.
mine boolean
این پارامتر فقط در یک درخواست مجاز به درستی قابل استفاده است. مقدار این پارامتر را روی true تنظیم کنید تا به API دستور دهید فقط لیست های پخش متعلق به کاربر تأیید شده را برگرداند.
پارامترهای اختیاری
hl string
پارامتر hl به API دستور می دهد که ابرداده های منبع محلی را برای یک زبان برنامه خاص که وب سایت YouTube پشتیبانی می کند، بازیابی کند. مقدار پارامتر باید کد زبانی باشد که در لیستی که با روش i18nLanguages.list برگردانده شده است.

اگر جزئیات منبع محلی شده در آن زبان موجود باشد، شی snippet.localized منبع حاوی مقادیر محلی خواهد بود. با این حال، اگر جزئیات محلی در دسترس نباشد، شی snippet.localized حاوی جزئیات منبع در زبان پیش‌فرض منبع خواهد بود.
maxResults unsigned integer
پارامتر maxResults حداکثر تعداد مواردی را که باید در مجموعه نتایج برگردانده شوند را مشخص می کند. مقادیر قابل قبول شامل 0 تا 50 است. مقدار پیش فرض 5 است.
onBehalfOfContentOwner string
این پارامتر فقط در یک درخواست مجاز به درستی قابل استفاده است. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube در نظر گرفته شده است.

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

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

این پارامتر برای شرکای محتوای YouTube در نظر گرفته شده است که کانال‌های مختلف YouTube را مالک و مدیریت می‌کنند. این به صاحبان محتوا اجازه می‌دهد تا یک بار احراز هویت کنند و اقداماتی را از طرف کانال مشخص‌شده در مقدار پارامتر انجام دهند، بدون اینکه نیازی به ارائه اعتبارنامه احراز هویت برای هر کانال جداگانه باشد.
pageToken string
پارامتر pageToken صفحه خاصی را در مجموعه نتایج مشخص می کند که باید برگردانده شود. در یک پاسخ API، ویژگی های nextPageToken و prevPageToken صفحات دیگری را شناسایی می کنند که می توانند بازیابی شوند.

درخواست بدن

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

واکنش

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

{
  "kind": "youtube#playlistListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    playlist Resource
  ]
}

خواص

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

خواص
kind string
نوع منبع API را مشخص می کند. مقدار youtube#playlistListResponse خواهد بود.
etag etag
Etag این منبع
nextPageToken string
نشانه ای که می تواند به عنوان مقدار پارامتر pageToken برای بازیابی صفحه بعدی در مجموعه نتایج استفاده شود.
prevPageToken string
نشانه ای که می تواند به عنوان مقدار پارامتر pageToken برای بازیابی صفحه قبلی در مجموعه نتایج استفاده شود.
pageInfo object
شی pageInfo اطلاعات صفحه‌بندی را برای مجموعه نتایج کپسوله می‌کند.
pageInfo. totalResults integer
تعداد کل نتایج در مجموعه نتایج.
pageInfo. resultsPerPage integer
تعداد نتایج موجود در پاسخ API.
items[] list
فهرستی از لیست های پخش که با معیارهای درخواست مطابقت دارند.

خطاها

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

نوع خطا جزئیات خطا شرح
forbidden (403) channelClosed کانال مشخص شده در پارامتر channelId بسته شده است.
forbidden (403) channelSuspended کانال مشخص شده در پارامتر channelId به حالت تعلیق درآمده است.
forbidden (403) playlistForbidden لیست پخش شناسایی شده با پارامتر id درخواست، درخواست را پشتیبانی نمی کند یا درخواست به درستی مجاز نیست.
notFound (404) channelNotFound کانال مشخص شده در پارامتر channelId یافت نمی شود.
notFound (404) playlistNotFound لیست پخش شناسایی شده با پارامتر id درخواست یافت نمی شود.
invalidValue (400) playlistOperationUnsupported API از قابلیت فهرست کردن لیست پخش مشخص شده پشتیبانی نمی کند. به عنوان مثال، نمی‌توانید فهرست پخش تماشای خود را بعداً فهرست کنید.

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

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