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 がチャンネルを承認または拒否した場合や、トークンが発行されてから 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 チャンネルをリクエストします。
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 プロパティを使用して他のページを取得できます。

リクエスト本文

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

レスポンス

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

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

実習

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