Channels: list

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

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

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

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

درخواست

درخواست 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 تنظیم کنید، پاسخ API نیز شامل همه آن ویژگی‌های تودرتو خواهد بود.

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

خطاها

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

نوع خطا جزئیات خطا شرح
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 استفاده کنید.