Subscriptions: list

Возвращает ресурсы подписок, соответствующие критериям запроса к API.

Влияние на квоту. Вызов этого метода имеет стоимость квоты в 1 единицу.

Примеры использования

Запрос

HTTP-запрос

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

Параметры

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

Параметры
Обязательные параметры
part string
Параметр part задает список из одного или нескольких свойств ресурса subscription, разделенных запятыми, которые будут включены в ответ API.

Если параметр указывает на свойство, содержащее дочерние свойства, они также будут включены в ответ. Например, в ресурсе subscription свойство snippet содержит другие свойства, такие как название подписки. Если вы зададите параметр part=snippet, ответ API будет содержать все вложенные свойства.

В списке ниже приведены названия part, которые можно включить в значение параметра:
  • contentDetails
  • id
  • snippet
  • subscriberSnippet
Фильтры (укажите ровно один из следующих параметров)
channelId string
Параметр channelId указывает идентификатор канала YouTube. API вернет только подписки этого канала.
id string
Параметр id представляет собой список идентификаторов подписок YouTube, разделенных запятыми. В ресурсе subscription свойство id указывает идентификатор подписки YouTube.
mine boolean
Этот параметр можно использовать только в авторизованном запросе. Чтобы получить фид подписок аутентифицированного пользователя, задайте для этого параметра значение true.
myRecentSubscribers boolean
Этот параметр можно использовать только в авторизованном запросе. Чтобы получить фид подписчиков аутентифицированного пользователя в обратном хронологическом порядке (начиная с самых новых), задайте для этого параметра значение true.

Обратите внимание, что максимальное количество подписчиков, возвращаемых через этот API, может быть ограничено.
mySubscribers boolean
Этот параметр можно использовать только в авторизованном запросе. Чтобы получить фид подписчиков аутентифицированного пользователя в произвольном порядке, задайте для этого параметра значение true. Обратите внимание, что максимальное количество подписчиков, возвращаемых через этот API, может быть ограничено.
Необязательные параметры
forChannelId string
Параметр forChannelId задает список идентификаторов каналов, разделенных запятыми. В этом случае ответ API будет содержать только подписки, соответствующие этим каналам.
maxResults unsigned integer
Параметр maxResults задает максимальное количество объектов, которые должны быть возвращены в наборе результатов. Допустимые значения: от 0 до 50 включительно. Значение по умолчанию: 5.
onBehalfOfContentOwner string
Примечание. Этот параметр предназначен исключительно для партнеров YouTube.

Параметр onBehalfOfContentOwner указывает, что учетные данные авторизации запроса идентифицируют пользователя системы управления контентом YouTube, который действует от имени владельца контента, указанного в значении параметра. Этот параметр предназначен для партнеров YouTube, которые владеют несколькими каналами и управляют ими. Владельцы контента могут пройти аутентификацию один раз и получить доступ ко всем своим видео и данным каналов, не предоставляя учетные данные для каждого канала отдельно. Аккаунт CMS, с помощью которого пользователь проходит аутентификацию, должен быть связан с указанным владельцем контента YouTube.
onBehalfOfContentOwnerChannel string
Этот параметр можно использовать только в авторизованном запросе. Примечание. Этот параметр предназначен исключительно для партнеров YouTube.

Параметр onBehalfOfContentOwnerChannel указывает идентификатор канала YouTube, на который добавляется видео. Этот параметр обязателен, если в запросе указано значение параметра onBehalfOfContentOwner, и может использоваться только вместе с ним. Кроме того, запрос должен быть авторизован с помощью аккаунта CMS, связанного с владельцем контента, указанным в параметре onBehalfOfContentOwner. Канал, указанный в значении параметра onBehalfOfContentOwnerChannel, должен быть связан с владельцем контента, указанным в параметре onBehalfOfContentOwner.

Этот параметр предназначен для партнеров YouTube, которые владеют и управляют множеством разных каналов YouTube. Владельцы контента могут один раз пройти аутентификацию и выполнять действия от имени канала, указанного в значении параметра, не предоставляя учетные данные для каждого отдельного канала.
order string
Параметр order определяет метод, который будет использоваться для сортировки ресурсов в ответе API. Значение по умолчанию – SUBSCRIPTION_ORDER_RELEVANCE.

Допустимые значения:
  • alphabetical – сортировка по алфавиту.
  • relevance – сортировка по релевантности.
  • unread – сортировка по порядку действий.
pageToken string
Параметр pageToken определяет конкретную страницу в наборе результатов, которую необходимо вернуть. В ответе API свойства nextPageToken и prevPageToken указывают на другие страницы, которые можно получить.

Тело запроса

При вызове этого метода не указывайте тело запроса.

Ответ

В случае успеха метод возвращает тело ответа со следующей структурой:

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

Свойства

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

Свойства
kind string
Тип ресурса API. Значение будет youtube#subscriptionListResponse.
etag etag
Тег Etag этого ресурса.
nextPageToken string
Токен, который можно использовать в качестве значения параметра pageToken, чтобы получить следующую страницу в наборе результатов.
prevPageToken string
Токен, который можно использовать в качестве значения параметра pageToken, чтобы получить предыдущую страницу результатов.
pageInfo object
Объект pageInfo содержит информацию о постраничной организации набора результатов.
pageInfo.totalResults integer
Общее количество результатов в наборе.
pageInfo.resultsPerPage integer
Количество результатов, включенных в ответ API.
items[] list
Список подписок, соответствующих критериям запроса.

Ошибки

В таблице ниже перечислены сообщения об ошибках, которые API может возвращать в ответ на вызов этого метода. Подробную информацию можно найти в документации по сообщениям об ошибках.

Тип ошибки Сведения об ошибке Описание
forbidden (403) accountClosed Не удалось получить информацию о подписках, так как аккаунт подписчика закрыт.
forbidden (403) accountSuspended Не удалось получить информацию о подписках, так как аккаунт подписчика заблокирован.
forbidden (403) subscriptionForbidden У отправителя запроса нет доступа к запрашиваемым подпискам.
notFound (404) subscriberNotFound Не удалось найти подписчика, указанного в запросе.

Попробовать

Используйте APIs Explorer, чтобы вызвать этот API и посмотреть запрос к API и ответ.