Subscriptions: list

API リクエスト条件に一致する登録チャンネルのリソースを返します。

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

一般的なユースケース

リクエスト

HTTP リクエスト

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

パラメータ

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

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

子プロパティを含むプロパティがパラメータで識別される場合、子プロパティはレスポンスに含まれます。たとえば、subscription リソースの snippet プロパティには、定期購入の表示タイトルなどの他のプロパティが含まれています。part=snippet を設定すると、API レスポンスにはネストされたプロパティもすべて含まれます。

次のリストは、パラメータ値に含めることができる part 名を示します。
  • contentDetails
  • id
  • snippet
  • subscriberSnippet
フィルタ（次のパラメータのいずれか 1 つのみを指定）
channelId string
channelId パラメータは YouTube チャンネル ID を指定します。API はそのチャンネルの登録チャンネルのみを返します。
id string
id パラメータは、取得するリソースの YouTube サブスクリプション ID のカンマ区切りのリストを指定します。subscription リソースでは、id プロパティに YouTube サブスクリプション ID を指定します。
mine boolean
このパラメータは、適切に承認されたリクエストでのみ使用できます。認証されたユーザーの登録チャンネルのフィードを取得するには、このパラメータの値を true に設定します。
myRecentSubscribers boolean
このパラメータは、適切に承認されたリクエストでのみ使用できます。このパラメータの値を true に設定すると、認証済みユーザーの定期購読者のフィードが新しい順（新しい順）に取得されます。

この API を通じて返される定期購読者の最大数には制限があります。
mySubscribers boolean
このパラメータは、適切に承認されたリクエストでのみ使用できます。認証されたユーザーの定期購読者のフィードを順不同で取得するには、このパラメータの値を true に設定します。この API によって返されるサブスクライバーの最大数は制限されている場合があります。
オプション パラメータ
forChannelId string
forChannelId パラメータは、チャンネル ID のカンマ区切りのリストを指定します。API レスポンスには、これらのチャンネルに一致する登録チャンネルのみ含まれます。
maxResults unsigned integer
maxResults パラメータは、結果セットで返されるアイテムの最大数を指定します。有効な値は 0～50 です。デフォルト値は 5 です。
onBehalfOfContentOwner string
注: このパラメータは YouTube コンテンツ パートナー専用です。

onBehalfOfContentOwner パラメータは、リクエストの認証情報が、パラメータ値で指定されたコンテンツ所有者の代理である YouTube CMS ユーザーを識別することを示します。このパラメータは、複数の YouTube チャンネルを所有、管理している YouTube コンテンツ パートナーを対象にしています。このパラメータを使用すると、コンテンツ所有者は一度認証されれば、すべての動画やチャンネル データにアクセスできるようになります。チャンネルごとに認証情報を指定する必要はありません。ユーザー認証に使用する CMS アカウントは、指定された YouTube コンテンツ所有者にリンクされていなければなりません。
onBehalfOfContentOwnerChannel string
このパラメータは、適切に承認されたリクエストでのみ使用できます。注: このパラメータは YouTube コンテンツ パートナー専用です。

onBehalfOfContentOwnerChannel パラメータは、動画が追加されるチャンネルの YouTube チャンネル ID を指定します。このパラメータは、リクエストで onBehalfOfContentOwner パラメータの値が指定されている場合に必須で、そのパラメータと組み合わせて使用できます。また、リクエストは、onBehalfOfContentOwner パラメータで指定されたコンテンツ所有者にリンクされた CMS アカウントを使用して承認される必要があります。最後に、onBehalfOfContentOwnerChannel パラメータ値で指定されたチャンネルを、onBehalfOfContentOwner パラメータで指定されたコンテンツ所有者にリンクする必要があります。

このパラメータは、さまざまな YouTube チャンネルを所有および管理している YouTube コンテンツ パートナーを対象としています。このパラメータを使用すると、コンテンツ所有者は一度認証されれば、パラメータ値で指定されたチャンネルの代わりにアクションを実行できるようになります。チャンネルごとに認証情報を指定する必要はありません。
order string
order パラメータは、API レスポンス内のリソースの並べ替えに使用されるメソッドを指定します。デフォルト値は SUBSCRIPTION_ORDER_RELEVANCE です。

指定できる値は次のとおりです。
  • alphabetical – アルファベット順に並べ替えます。
  • relevance – 関連性で並べ替えます。
  • unread – アクティビティで並べ替えます。
pageToken string
pageToken パラメータは、結果セットの特定のページを返します。API レスポンスでは、nextPageToken プロパティと prevPageToken プロパティは取得可能な他のページを示します。

リクエスト本文

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

レスポンス

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

{
  "kind": "youtube#subscriptionListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    subscription Resource
  ]
}

プロパティ

次の表は、このリソースで使用されているプロパティの定義を示したものです。

プロパティ
kind string
API リソースのタイプを識別します。値は youtube#subscriptionListResponse です。
etag etag
このリソースの Etag。
nextPageToken string
結果セットで次のページを取得するために、pageToken パラメータの値として使用できるトークン。
prevPageToken string
結果セット内の前のページを取得するために、pageToken パラメータの値として使用できるトークン。
pageInfo object
pageInfo オブジェクトは、結果セットのページング情報をカプセル化します。
pageInfo.totalResults integer
結果セット内の結果の合計数。
pageInfo.resultsPerPage integer
API レスポンスに含まれる結果の数。
items[] list
リクエスト条件に一致するサブスクリプションのリスト。

エラー

次の表に、このメソッドの呼び出しに対して API から返されるエラー メッセージを示します。詳細については、エラー メッセージのドキュメントを参照してください。

エラーのタイプ エラーの詳細 説明
forbidden (403) accountClosed チャンネル登録者のアカウントが閉じられているため、チャンネル登録を取得できませんでした。
forbidden (403) accountSuspended チャンネル登録者のアカウントが一時停止されているため、チャンネル登録を取得できませんでした。
forbidden (403) subscriptionForbidden リクエスト送信者は、リクエストしたチャンネル登録へのアクセスを許可されていません。
notFound (404) subscriberNotFound リクエストで特定されているチャンネル登録者が見つかりません。

試してみよう:

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