Playlists: list

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

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

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

درخواست

درخواست 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 نشان می‌دهد که اطلاعات کاربری مجوز درخواست، کاربر CMS YouTube را شناسایی می‌کند که از طرف مالک محتوای مشخص‌شده در مقدار پارامتر عمل می‌کند. این پارامتر برای شرکای محتوای 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
نوع منبع میانای برنامه‌سازی کاربردی را مشخص می‌کند. مقدار youtube#playlistListResponse خواهد بود.
etag etag
‫Etag این منبع.
nextPageToken string
نشانه‌ای که می‌تواند به‌عنوان مقدار پارامتر pageToken برای بازیابی صفحه بعدی در مجموعه نتایج استفاده شود.
prevPageToken string
رمزی که می‌تواند به‌عنوان مقدار پارامتر pageToken برای بازیابی صفحه قبلی در مجموعه نتایج استفاده شود.
pageInfo object
شیء pageInfo اطلاعات صفحه‌بندی را برای مجموعه نتایج کپسوله می‌کند.
pageInfo.totalResults integer
تعداد کل نتایج در مجموعه نتایج.
pageInfo.resultsPerPage integer
تعداد نتایج موجود در پاسخ میانای برنامه‌سازی کاربردی.
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 استفاده کنید.