此页面由 Cloud Translation API 翻译。

Subscriptions: list

返回符合 API 请求条件的订阅资源。

对配额的影响：调用此方法的配额费用为 1 个单位。

常见使用场景

请求

HTTP 请求

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

参数

下表列出了此查询支持的参数。列出的所有参数都是查询参数。

参数
必需参数
`part`	`string` `part` 参数会指定一个逗号分隔列表，其中包含 API 响应将包含的一个或多个 `subscription` 资源属性。如果该参数标识了包含子属性的媒体资源，相应子属性将包含在响应中。例如，在 `subscription` 资源中，`snippet` 属性包含其他属性，例如订阅的显示标题。如果您设置了 `part=snippet`，API 响应还将包含所有这些嵌套属性。以下列表包含您可以包含在参数值中的 `part` 名称： `contentDetails` `id` `snippet` `subscriberSnippet`
过滤条件（请仅指定以下参数之一）
`channelId`	`string` `channelId` 参数会指定 YouTube 频道 ID。该 API 将仅返回该频道的订阅。
`id`	`string` `id` 参数指定要检索的资源的 YouTube 订阅 ID 列表（以英文逗号分隔）。在 `subscription` 资源中，`id` 属性用于指定 YouTube 订阅 ID。
`mine`	`boolean` 此参数只能在正确授权的请求中使用。请将此参数的值设置为 `true`，以检索经过身份验证的用户的订阅的 Feed。
`myRecentSubscribers`	`boolean` 此参数只能在正确授权的请求中使用。将此参数的值设置为 `true` 可按时间倒序（由新到旧）检索经过身份验证的用户的订阅者的 Feed。请注意，通过此 API 返回的订阅者数量上限可能会受到限制。
`mySubscribers`	`boolean` 此参数只能在正确授权的请求中使用。将此参数的值设置为 `true` 可检索经过身份验证的用户的订阅者的 Feed，没有特定顺序。请注意，通过此 API 返回的最大订阅者数量可能会受到限制。
可选参数
`forChannelId`	`string` `forChannelId` 参数指定了以逗号分隔的频道 ID 列表。这样，API 响应就会只包含与这些频道匹配的订阅。
`maxResults`	`unsigned integer` `maxResults` 参数指定结果集中应返回的商品数量上限。可接受的值包括`0`到`50`（含 0 和 10000）。默认值为 `5`。
`onBehalfOfContentOwner`	`string` 注意：此参数仅适用于 YouTube 内容合作伙伴。 `onBehalfOfContentOwner` 参数用于指明该请求的授权凭据会标识代表参数值中指定的内容所有者的 YouTube 内容管理系统用户。此参数适用于拥有和管理众多不同 YouTube 频道的 YouTube 内容合作伙伴。它可让内容所有者在一次身份验证后获得访问其所有视频和频道数据的权限，而无需为每个频道提供身份验证凭据。用户进行身份验证时所用的 CMS 账号必须与指定的 YouTube 内容所有者相关联。
`onBehalfOfContentOwnerChannel`	`string` 此参数只能在正确授权的请求中使用。注意：此参数仅适用于 YouTube 内容合作伙伴。 `onBehalfOfContentOwnerChannel` 参数用于指定要添加视频的频道的 YouTube 频道 ID。当请求为 `onBehalfOfContentOwner` 形参指定值时，此形参是必需项，并且只能与形参结合使用。此外，该请求还必须通过与 `onBehalfOfContentOwner` 参数指定的内容所有者相关联的 CMS 账号进行授权。最后，`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 请求和响应。