Members

注意：自 2020 年 3 月 31 日起，members 端点取代了 sponsors 端点。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
用户对指定级别的访问权限有效期（以月为单位），向下舍入到最接近的整数。此值反映的是会员获享相应等级的完整月数，但该数值并不意味着会员连续享受了这么多个月的会员福利。