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 プロパティによって、取得可能な他のページが識別されます。

リクエストの本文

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

Response

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

{
  "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 リクエストとレスポンスを確認します。