Members

Lưu ý: Kể từ ngày 31 tháng 3 năm 2020, điểm cuối members sẽ thay thế điểm cuối sponsors (hiện không còn dùng nữa và không còn được hỗ trợ kể từ ngày 30 tháng 9 năm 2020). Các ứng dụng API nên cập nhật các lệnh gọi thành phương thức sponsors.list để sử dụng phương thức members.list.

Chỉ nhà sáng tạo cá nhân mới có thể sử dụng điểm cuối này để gửi yêu cầu cho kênh YouTube đã bật tính năng hội viên của kênh. Hãy liên hệ với người đại diện của Google hoặc YouTube để yêu cầu quyền truy cập.

Tài nguyên member đại diện cho một hội viên của một kênh YouTube. Hội viên sẽ hỗ trợ bằng tiền định kỳ cho nhà sáng tạo và nhận được các lợi ích đặc biệt. Ví dụ: Hội viên có thể trò chuyện khi nhà sáng tạo bật chế độ chỉ dành cho hội viên cho cuộc trò chuyện.

Phương thức

API hỗ trợ các phương thức sau cho tài nguyên member:

list
Liệt kê các hội viên (trước đây gọi là "nhà tài trợ") của một kênh. Yêu cầu API phải được chủ sở hữu kênh cho phép.

Trình bày tài nguyên

Cấu trúc JSON dưới đây thể hiện định dạng của tài nguyên 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,
        }
      ]
    }
  }
}

Thuộc tính

Bảng sau đây xác định các thuộc tính xuất hiện trong tài nguyên này:

Thuộc tính
kind string
Xác định loại tài nguyên API. Giá trị sẽ là youtube#member.
etag etag
Thẻ Etag của tài nguyên này.
snippet object
Đối tượng snippet chứa thông tin chi tiết về thành viên.
snippet.creatorChannelId string
Mã nhận dạng kênh YouTube của nhà sáng tạo cung cấp chương trình hội viên.
snippet.memberDetails object
Đối tượng này chứa dữ liệu hồ sơ về kênh YouTube đang trả phí cho gói hội viên.

Xin lưu ý rằng một kênh có thể có hội viên mà không có dữ liệu hồ sơ. Ví dụ: tình trạng này xảy ra với những hội viên đã xoá kênh của họ nhưng vẫn đang trả phí cho gói hội viên. Xin lưu ý rằng những thành viên này vẫn có thể sử dụng các lợi ích của gói thành viên.

Phản hồi của API bao gồm tài nguyên dành cho các thành phần đó để đảm bảo số lượng chính xác mặc dù thông tin chi tiết về hồ sơ bên trong đối tượng memberDetails không được đặt. membershipsDetails vẫn được cung cấp cho các thành viên đó.
snippet.memberDetails.channelId string
Mã nhận dạng kênh YouTube của kênh thành viên. Nếu bạn đặt thuộc tính này thì mã nhận dạng kênh cũng có thể được coi là giá trị nhận dạng duy nhất của hội viên. Nếu bạn không đặt thuộc tính này, thì hệ thống sẽ không thể xác định duy nhất thành viên, nhưng tài nguyên vẫn truyền tải thông tin chi tiết về thành viên, chẳng hạn như các cấp độ mà thành viên có thể truy cập và thời hạn thành viên của họ.
snippet.memberDetails.channelUrl string
URL của kênh.
snippet.memberDetails.displayName string
Tên hiển thị của kênh.
snippet.memberDetails.profileImageUrl string
URL hình đại diện của kênh.
snippet.membershipsDetails object
Đối tượng này chứa thông tin chi tiết về gói hội viên của kênh hội viên.
snippet.membershipsDetails.highestAccessibleLevel string
Mã nhận dạng của cấp độ hội viên cao nhất mà kênh hội viên hiện có thể được hưởng. Giá trị này tương ứng với giá trị thuộc tính id trong tài nguyên membershipsLevel.
snippet.membershipsDetails.highestAccessibleLevelDisplayName string
Tên của cấp độ hội viên cao nhất mà kênh hội viên hiện có thể sử dụng. Giá trị này tương ứng với giá trị thuộc tính displayName trong một tài nguyên membershipsLevel.
snippet.membershipsDetails.accessibleLevels[] list (of strings)
Danh sách mã nhận dạng của tất cả các cấp độ hội viên mà người dùng hiện có thể truy cập. Danh sách này bao gồm cấp đang hoạt động và tất cả các cấp bên dưới.
snippet.membershipsDuration object
Đối tượng này chứa thông tin về tổng thời gian làm thành viên của thành viên hiện tại mà không tính đến mức giá. Sau đó, thuộc tính snippet.membershipsDetails.membershipsDurationAtLevel[] sẽ chứa một danh sách các đối tượng chứa thông tin chi tiết về một khoảng thời gian hội viên mà trong đó thành viên có quyền truy cập vào một cấp độ thành viên cụ thể.

Ví dụ sau đây cho thấy cách hoạt động của các thuộc tính này: Một thành viên mua một gói thành viên mới vào tháng 1 ở cấp độ 1 và có gói thành viên đó cho đến hết tháng 3. Vào tháng 4 và tháng 5, thành viên không có gói thành viên nào. Vào tháng 6, hội viên sẽ đăng ký lại gói hội viên ở cấp độ 1 một lần nữa. Sau đó, vào tháng 8, hội viên nâng cấp gói hội viên lên cấp độ 2. Vì vậy, nếu lệnh gọi API được thực hiện vào tháng 10, tài nguyên member sẽ chứa nội dung sau:
"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
Ngày và giờ bắt đầu gói hội viên hiện tại của hội viên. Nói cách khác, thành viên liên tục sử dụng gói hội viên kể từ ngày và giờ này. Xin lưu ý rằng các khoảng thời gian khác nhau của gói hội viên có thể đã được chi tiêu ở các cấp độ hội viên khác nhau.
snippet.membershipsDuration.memberTotalDurationMonths integer
Số tháng, được làm tròn xuống số nguyên gần nhất mà người dùng là thành viên. Giá trị này phản ánh số tháng đầy đủ của một hội viên, nhưng con số này không ngụ ý rằng một hội viên liên tục sử dụng gói hội viên trong nhiều tháng đó.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
Danh sách đối tượng, trong đó mỗi đối tượng chứa thông tin chi tiết về một khoảng thời gian thành viên mà trong đó thành viên có quyền truy cập vào một cấp độ thành viên cụ thể. Danh sách này bao gồm một đối tượng cho mỗi cấp độ thành viên mà thành viên hiện có thể truy cập.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level string
Mã cấp độ hội viên. Giá trị này tương ứng với giá trị thuộc tính id trong tài nguyên membershipsLevel.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberSince datetime
Ngày và giờ mà một hội viên bắt đầu sử dụng cấp độ hội viên đã chỉ định. Nói cách khác, thành viên đó vẫn liên tục có quyền sử dụng cấp độ đó kể từ ngày và giờ này. Xin lưu ý rằng những khoảng thời gian sử dụng gói hội viên khác nhau có thể đã được dùng ở các cấp độ hội viên cao hơn.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
Số tháng, được làm tròn xuống số nguyên gần nhất, mà người dùng có quyền truy cập vào cấp được chỉ định. Giá trị này phản ánh số tháng đầy đủ mà một hội viên có thể sử dụng cấp độ đó, nhưng con số này không ngụ ý rằng thành viên đó liên tục sử dụng một cấp độ trong nhiều tháng đó.