Members

注: 2020 年 3 月 31 日をもって、sponsors エンドポイントは members エンドポイントに置き換わります。このエンドポイントは非推奨となり、2020 年 9 月 30 日以降はサポートされなくなります。API クライアントは、sponsors.list メソッドの呼び出しを更新して、代わりに members.list メソッドを使用する必要があります。

このエンドポイントは、個々のクリエイターがチャンネル メンバーシップが有効になっている自分の YouTube チャンネルをリクエストする場合にのみ使用できます。Google または YouTube の担当者に連絡して、アクセス権をリクエストしてください。

member リソースは、YouTube チャンネルのチャンネル メンバーを表します。メンバーはクリエイターに金銭的サポートを定期的に提供し、特別な特典を受けることができます。たとえば、クリエイターがチャットに対してメンバー限定モードを有効にすると、メンバーはチャットできるようになります。

Methods

API は、member リソースに対して次のメソッドをサポートしています。

list
チャンネルのメンバー(旧称「スポンサー」)を一覧表示します。API リクエストはチャンネル所有者によって承認される必要があります。

リソース表現

次の JSON 構造は、member リソースの形式を示しています。

{
  "kind": "youtube#member",
  "etag": etag,
  "snippet": {
    "creatorChannelId": string,
    "memberDetails": {
      "channelId": string,
      "channelUrl": string,
      "displayName": string,
      "profileImageUrl": string
    },
    "membershipsDetails": {
      "highestAccessibleLevel": string,
      "highestAccessibleLevelDisplayName": string,
      "accessibleLevels": [
        string
      ],
      "membershipsDuration": {
        "memberSince": datetime,
        "memberTotalDurationMonths": integer,
      },
      "membershipsDurationAtLevel": [
        {
          "level": string,
          "memberSince": datetime,
          "memberTotalDurationMonths": integer,
        }
      ]
    }
  }
}

プロパティ

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

プロパティ
kind string
API リソースのタイプを識別します。値は youtube#member です。
etag etag
このリソースの Etag。
snippet object
snippet オブジェクトには、メンバーの詳細が含まれます。
snippet.creatorChannelId string
メンバーシップを提供しているクリエイターの YouTube チャンネル ID。
snippet.memberDetails object
このオブジェクトには、メンバーシップ料金を支払っている YouTube チャンネルに関するプロフィール データが含まれます。

なお、チャンネルには、プロフィール データが利用できないメンバーがいる場合があります。たとえば、チャンネルは削除したが、メンバーシップの料金を支払っているメンバーなどです。なお、これらのメンバーは引き続きメンバーシップの特典にアクセスできます。

API レスポンスには、memberDetails オブジェクト内のプロファイルの詳細が設定されていなくても、正確なカウントを確保するためにこれらのメンバーのリソースが含まれます。このようなメンバーに対しては、引き続き membershipsDetails が提供されます。
snippet.memberDetails.channelId string
メンバー チャンネルの YouTube チャンネル ID。設定されている場合、チャンネル ID をメンバーの一意の識別子として扱うこともできます。このポリシーを設定しない場合、メンバーは一意に識別されませんが、メンバーがアクセスできるレベルやメンバーシップの有効期間などのメンバーシップの詳細がリソースから伝えられます。
snippet.memberDetails.channelUrl string
チャンネルの URL。
snippet.memberDetails.displayName string
チャンネルの表示名。
snippet.memberDetails.profileImageUrl string
チャンネルのアバターの URL。
snippet.membershipsDetails object
このオブジェクトには、メンバー チャンネルのメンバーシップの詳細が含まれます。
snippet.membershipsDetails.highestAccessibleLevel string
メンバー チャンネルが現在アクセスできる、最も高いメンバーシップ レベルの ID。この値は、membershipsLevel リソースの id プロパティ値に対応します。
snippet.membershipsDetails.highestAccessibleLevelDisplayName string
メンバー チャンネルで現在アクセスできるメンバーシップの最上位のレベルの名前。この値は、membershipsLevel リソースの displayName プロパティ値に対応します。
snippet.membershipsDetails.accessibleLevels[] list (of strings)
ユーザーが現在アクセスできるすべてのメンバーシップ レベルの ID のリスト。リストには、現在アクティブなレベルとその下のすべてのレベルが含まれます。
snippet.membershipsDuration object
このオブジェクトには、料金レベルに関係なく、現在のメンバーのメンバーシップの有効期間全体に関する情報が含まれます。snippet.membershipsDetails.membershipsDurationAtLevel[] プロパティには、メンバーが特定のメンバーシップ レベルにアクセスできたメンバーシップ期間の詳細を含むオブジェクトのリストが含まれます。

次の例は、これらのプロパティの仕組みを示しています。メンバーが 1 月にメンバーシップ レベル 1 で新しいメンバーシップを購入し、3 月までそのメンバーシップを持ちます。4 月と 5 月はメンバーシップがありません。6 月にメンバーシップを再開し、再びレベル 1 になります。その後 8 月にメンバーシップをレベル 2 にアップグレードします。そのため、10 月に API 呼び出しが行われた場合、member リソースには次のものが含まれます。
"membershipsDetails": {
  "membershipsDuration": {
    "memberSince": "2020-06-01T12:00:00",
    "memberTotalDurationMonths": 7,
  },
  "membershipsDurationAtLevel": [
    {
      "level": "level_1_ID",
      "memberSince": "2020-06-01T12:00:00",
      "memberTotalDurationMonths": 7
    },
    {
      "level": "level_2_ID",
      "memberSince": "2020-08-01T12:00:00",
      "memberTotalDurationMonths": 2
    },
  ]
}
snippet.membershipsDuration.memberSince datetime
メンバーの現在のメンバーシップが開始された日時。つまり、この日時以降、メンバーはメンバーシップを継続しています。なお、メンバーシップ レベルによって利用期間が異なっている場合もあります。
snippet.membershipsDuration.memberTotalDurationMonths integer
ユーザーがメンバーである月数(最も近い整数に切り捨てられます)。 この値は、メンバーがメンバーシップに加入していた月数を示しますが、その月数だけメンバーを続けていたことを意味するものではありません。
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
オブジェクトのリスト。各オブジェクトには、メンバーが特定のメンバーシップ レベルにアクセスできたメンバーシップ期間の詳細が含まれます。このリストには、メンバーが現在アクセスできるメンバーシップ レベルごとに 1 つのオブジェクトが含まれます。
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level string
メンバーシップ レベルの ID。この値は、membershipsLevel リソースの id プロパティ値に対応しています。
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberSince datetime
指定したメンバーシップ レベルにメンバーがアクセスできるようになった日時。つまり、メンバーはこの日時以降、継続的にレベルへのアクセス権を持っています。上位のメンバーシップ レベルでは、利用期間が異なっている場合があります。
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
指定されたレベルにユーザーがアクセスできた月数(最も近い整数に切り捨てられます)。この値は、メンバーがレベルへのアクセス権を持っていた月数を表しますが、その月数だけメンバーがメンバーを続けていたことを意味するものではありません。