این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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 استفاده کنید.