Channels: list

توجه: مقدار دارایی channel منبع statistics.subscriberCount به‌روز شده است تا تغییر خط‌مشی YouTube را که بر نحوه نمایش تعداد مشترکان تأثیر می‌گذارد منعکس کند. برای اطلاعات بیشتر، به سابقه بازبینی یا مرکز راهنمایی YouTube مراجعه کنید.

مجموعه‌ای از صفر یا چند منبع channel را برمی‌گرداند که با معیارهای درخواست مطابقت دارند.

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

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

درخواست

درخواست HTTP

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

صدور مجوز

درخواستی که بخش auditDetails را برای منبع channel بازیابی می‌کند باید یک کد مجوز ارائه دهد که حاوی دامنه https://www.googleapis.com/auth/youtubepartner-channel-audit باشد. علاوه‌براین، هر نشانه‌ای که از آن دامنه استفاده می‌کند باید زمانی که MCN تصمیم به پذیرش یا رد کانال می‌گیرد یا ظرف دو هفته از تاریخ صدور نشانه، لغو شود.

پارامترها

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

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

اگر پارامتر دارایی‌ای را شناسایی کند که حاوی دارایی‌های فرزند باشد، دارایی‌های فرزند در پاسخ گنجانده خواهد شد. برای مثال، در منبع channel، ویژگی contentDetails شامل ویژگی‌های دیگری مانند ویژگی‌های uploads است. بنابراین، اگر part=contentDetails را تنظیم کنید، پاسخ میانای برنامه‌سازی کاربردی نیز شامل همه آن ویژگی‌های تودرتو خواهد بود.

فهرست زیر شامل نام‌های part است که می‌توانید در مقدار پارامتر اضافه کنید:
  • auditDetails
  • brandingSettings
  • contentDetails
  • contentOwnerDetails
  • id
  • localizations
  • snippet
  • statistics
  • status
  • topicDetails
فیلترها (دقیقاً یکی از پارامترهای زیر را مشخص کنید)
categoryId string
این پارامتر منسوخ شده است. پارامتر categoryId یک دسته راهنمای YouTube را مشخص می‌کرد و می‌توانست برای درخواست کانال‌های YouTube مرتبط با آن دسته استفاده شود.
forHandle string
پارامتر forHandle نام کاربری YouTube را مشخص می‌کند و ازاین‌رو کانال مرتبط با آن نام کاربری را درخواست می‌کند. مقدار پارامتر می‌تواند با نماد @ پیش‌افزوده شود. برای مثال، برای بازیابی منبع کانال «Google for Developers»، مقدار پارامتر forHandle را روی GoogleDevelopers یا @GoogleDevelopers تنظیم کنید.
forUsername string
پارامتر forUsername یک نام کاربری YouTube را مشخص می‌کند و از این طریق کانال مرتبط با آن نام کاربری را درخواست می‌کند.
id string
پارامتر id فهرست جداشده با کامایی از شناسه(های) کانال YouTube را برای منبع(های) درحال بازیابی مشخص می‌کند. در منبع channel، ویژگی id شناسه کانال YouTube کانال را مشخص می‌کند.
managedByMe boolean
این پارامتر فقط در درخواست مجاز مناسب قابل استفاده است.

توجه: این پارامتر منحصراً برای شرکای محتوای YouTube درنظر گرفته شده است.

مقدار این پارامتر را روی true تنظیم کنید تا به API دستور دهید فقط کانال‌های مدیریت‌شده توسط مالک محتوایی را که پارامتر onBehalfOfContentOwner مشخص می‌کند برگرداند. کاربر باید به‌عنوان حساب CMS پیوندشده به مالک محتوای مشخص‌شده اصالت‌سنجی شود و onBehalfOfContentOwner باید ارائه شود.
mine boolean
از این پارامتر فقط می‌توان در درخواست مجاز مناسب استفاده کرد. برای اینکه به API دستور دهید فقط کانال‌های متعلق به کاربر اصالت‌سنجی‌شده را برگرداند، مقدار این پارامتر را روی true تنظیم کنید.
پارامترهای اختیاری
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 مشخص‌شده پیوند داده شود.
pageToken string
پارامتر pageToken صفحه خاصی را در مجموعه نتایج که باید برگردانده شود شناسایی می‌کند. در پاسخ API، ویژگی‌های nextPageToken و prevPageToken صفحات دیگری را که می‌توانند بازیابی شوند شناسایی می‌کنند.

متن درخواست

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

پاسخ

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

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

مشخصات

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

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

خطاها

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

نوع خطا جزئیات خطا شرح
badRequest (400) invalidCriteria حداکثر یکی از فیلترهای زیر را می‌توانید مشخص کنید:id، categoryId، mine، managedByMe، forHandle، forUsername. درصورت اصالت‌سنجی مالک محتوا ازطریق پارامتر onBehalfOfContentOwner، فقط id یا managedByMe را می‌توان مشخص کرد.
forbidden (403) channelForbidden کانال مشخص‌شده با پارامتر id از درخواست پشتیبانی نمی‌کند یا درخواست به‌درستی مجاز نشده است.
notFound (404) categoryNotFound دسته‌ای که با پارامتر categoryId شناسایی شده است پیدا نمی‌شود. از روش guideCategories.list برای بازیابی فهرست مقادیر معتبر استفاده کنید.
notFound (404) channelNotFound کانال مشخص‌شده در پارامتر id پیدا نشد.

امتحان کنید!

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