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. Кроме того, любой токен, в котором используется этот диапазон, должен быть отозван, когда МКС принимает или отклоняет канал, или в течение двух недель с даты выдачи токена.

Параметры

В таблице ниже перечислены параметры, которые поддерживает этот запрос. Все перечисленные параметры являются параметрами запроса.

Параметры
Обязательные параметры
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 для разработчиков", задайте для параметра 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, который действует от имени владельца контента, указанного в значении параметра. Этот параметр предназначен для партнеров 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, если в соответствующем запросе к API для параметра managedByMe задано значение true.
pageInfo object
Объект pageInfo содержит информацию о постраничной организации набора результатов.
pageInfo.totalResults integer
Общее количество результатов в наборе.
pageInfo.resultsPerPage integer
Количество результатов, включенных в ответ API.
items[] list
Список каналов, соответствующих критериям запроса.

Ошибки

В таблице ниже перечислены сообщения об ошибках, которые API может возвращать в ответ на вызов этого метода. Подробнее об ошибках YouTube Data 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 и ответ.