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

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 می تواند در پاسخ به تماس با این روش بازگرداند. برای جزئیات بیشتر، 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 استفاده کنید.