Members

注意:自 2020 年 3 月 31 日起,members 端点取代了 sponsors 端点,该端点现已弃用,自 2020 年 9 月 30 日起将不再受支持。API 客户端应更新对 sponsors.list 方法的调用,以改用 members.list 方法。

此端点只能供个人创作者自己申请启用频道会员功能的 YouTube 频道。请与您的 Google 或 YouTube 代表联系,申请访问权限。

member 资源表示 YouTube 频道的频道会员。会员可定期向创作者提供资金支持、获享特殊福利。例如,创作者可以在开启聊天功能后开启会员专享模式,让会员参与聊天。

方法

该 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
频道的网址。
snippet.memberDetails.displayName string
频道的显示名。
snippet.memberDetails.profileImageUrl string
频道的头像网址。
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)
一个对象列表,其中每个对象均包含有关某位成员在特定会员级别的访问权限期间的详细信息。该列表包含会员当前可以访问的每个会员级别的一个对象。
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level string
会员级别 ID。该值对应于 membershipsLevel 资源中的 id 属性值。
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberSince datetime
此成员有权访问指定会员级别的日期和时间。换句话说,在该日期和时间之后,此成员一直都能访问该等级。请注意,您可能在较高级别的会员期限中使用了不同的会员期限。
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
用户有权访问指定级别的月数,向下舍入为最接近的整数。该值反映了该会员相应级别拥有的会员的月数,但并不表示会员连续这么多月拥有会员资格。