此页面由 Cloud Translation API 翻译。

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 请求和响应。