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 范围的授权令牌。此外,如果多频道网络决定接受或拒绝频道,或者在令牌发放后的两周内,就必须撤消使用该范围的任何令牌。

参数

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

参数
必需参数
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 参数指定结果集中应返回的商品数量上限。可接受的值包括050(含 0 和 10000)。默认值为 5
onBehalfOfContentOwner string
此参数只能在正确授权的请求中使用。注意:此参数仅适用于 YouTube 内容合作伙伴。

onBehalfOfContentOwner 参数用于指明该请求的授权凭据会标识代表参数值中指定的内容所有者执行操作的 YouTube 内容管理系统用户。此参数适用于拥有和管理众多不同 YouTube 频道的 YouTube 内容合作伙伴。它可让内容所有者在一次身份验证后获得访问其所有视频和频道数据的权限,而无需为每个频道提供身份验证凭据。用户进行身份验证时所用的 CMS 账号必须与指定的 YouTube 内容所有者相关联。
pageToken string
pageToken 参数用于标识结果集中应返回的特定网页。在 API 响应中,nextPageTokenprevPageToken 属性用于标识可检索到的其他页面。

请求正文

调用此方法时,请勿提供请求正文。

响应

如果成功,此方法将返回采用以下结构的响应正文:

{
  "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 在响应对此方法的调用时可能会返回的错误消息。如需了解详情,请参阅错误消息文档。

错误类型 错误详情 说明
badRequest (400) invalidCriteria 最多可以指定以下过滤条件之一:idcategoryIdminemanagedByMeforHandleforUsername。如果通过 onBehalfOfContentOwner 参数对内容所有者进行身份验证,则只能指定 idmanagedByMe
forbidden (403) channelForbidden id 参数指定的渠道不支持该请求,或该请求未获得适当的授权。
notFound (404) categoryNotFound 找不到 categoryId 参数所标识的类别。使用 guideCategories.list 方法检索有效值列表。
notFound (404) channelNotFound 找不到 id 参数中指定的渠道。

试试看!

使用 APIs Explorer 调用此 API 并查看 API 请求和响应。