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 для разработчиков», установите для параметра 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
Этаг этого ресурса.
nextPageToken string
Токен, который можно использовать в качестве значения параметра pageToken для получения следующей страницы в наборе результатов.
prevPageToken string
Токен, который можно использовать в качестве значения параметра pageToken для получения предыдущей страницы в наборе результатов. Обратите внимание, что это свойство не включается в ответ API, если в соответствующем запросе API для параметра managedByMe установлено значение true .
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.