Channels: list

注意：channel 资源的 statistics.subscriberCount 属性值已更新，以反映影响订阅人数显示方式的 YouTube 政策变更。如需了解详情，请参阅修订记录或 YouTube 帮助中心。

返回与请求条件匹配的零个或多个 channel 资源的集合。

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

常见使用场景

请求

HTTP 请求

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

授权

用于检索 channel 资源的 auditDetails 部分的请求必须提供包含 https://www.googleapis.com/auth/youtubepartner-channel-audit 范围的授权令牌。此外，在 MCN 决定接受或拒绝频道时，或在令牌签发之日起两周内，必须撤消使用该范围的所有令牌。

参数

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

参数
必需参数
part string
part 参数指定 API 响应将包含的一个或多个 channel 资源属性的逗号分隔列表。

如果该参数标识包含子属性的属性，则响应中将包含这些子属性。例如，在 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 频道 ID 的逗号分隔列表。在 channel 资源中，id 属性用于指定频道的 YouTube 频道 ID。
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 - 错误。

错误类型 错误详情 说明
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 请求和响应。