Channels: list

注: channel リソースの statistics.subscriberCount プロパティ値が更新され、チャンネル登録者数の表示方法に影響する YouTube ポリシーの変更が反映されました。詳しくは、変更履歴または YouTube ヘルプセンターをご覧ください。

リクエスト条件に一致する 0 個以上の channel リソースのコレクションを返します。

割り当てへの影響: このメソッドを呼び出すと、1 ユニットの割り当てコストが発生します。

一般的なユースケース

リクエスト

HTTP リクエスト

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

承認

channel リソースの auditDetails 部分を取得するリクエストには、https://www.googleapis.com/auth/youtubepartner-channel-audit スコープを含む認証トークンを指定する必要があります。また、MCN がチャンネルを承認または拒否することを決定したとき、またはトークンが発行された日から 2 週間以内に、そのスコープを使用するトークンはすべて取り消す必要があります。

パラメータ

次の表に、このクエリでサポートされているパラメータを示します。このリストのパラメータはすべてクエリ パラメータです。

パラメータ
必須パラメータ
part string
part パラメータは、API レスポンスに含める 1 つ以上の channel リソース プロパティのカンマ区切りのリストを指定します。

パラメータが子プロパティを含むプロパティを識別する場合、子プロパティはレスポンスに含まれます。たとえば、channel リソースでは、contentDetails プロパティに uploads プロパティなどの他のプロパティが含まれています。そのため、part=contentDetails を設定すると、API レスポンスには、それらのネストされたプロパティもすべて含まれます。

次のリストには、パラメータ値に含めることができる part 名が含まれています。
  • auditDetails
  • brandingSettings
  • contentDetails
  • contentOwnerDetails
  • id
  • localizations
  • snippet
  • statistics
  • status
  • topicDetails
フィルタ（次のパラメータのうち 1 つだけを指定）
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 に設定すると、onBehalfOfContentOwner パラメータで指定されたコンテンツ所有者が管理するチャンネルのみを返すように API に指示できます。ユーザーは、指定されたコンテンツ所有者にリンクされている CMS アカウントとして認証され、onBehalfOfContentOwner が提供されている必要があります。
mine boolean
このパラメータは、適切に承認されたリクエストでのみ使用できます。このパラメータの値を true に設定すると、認証済みユーザーが所有するチャンネルのみを返すよう API に指示できます。
オプション パラメータ
hl string
hl パラメータは、YouTube ウェブサイトがサポートする特定のアプリ言語のローカライズされたリソース メタデータを取得するよう API に指示します。パラメータ値は、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 プロパティで、取得可能な他のページを識別します。

リクエストの本文

このメソッドを呼び出す場合は、リクエストの本文を指定しないでください。

Response

成功すると、このメソッドは次の構造を含むレスポンスの本文を返します。

{
  "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 のいずれか 1 つのみです。onBehalfOfContentOwner パラメータを介したコンテンツ所有者の認証の場合、id または managedByMe のみを指定できます。
forbidden (403) channelForbidden id パラメータで指定されたチャンネルがリクエストをサポートしていないか、リクエストが適切に承認されていません。
notFound (404) categoryNotFound categoryId パラメータで指定されたカテゴリが見つかりません。guideCategories.list メソッドを使用して、有効な値のリストを取得します。
notFound (404) channelNotFound id パラメータで指定されたチャンネルが見つかりません。

試してみよう:

APIs Explorer を使用してこの API を呼び出し、API リクエストとレスポンスを確認します。