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. Điểm cuối sponsors hiện không được dùng nữa và sẽ không được hỗ trợ nữa kể từ ngày 30 tháng 9 năm 2020. Ứng dụng API nên cập nhật các lệnh gọi đến phương thức sponsors.list để sử dụng phương thức members.list.

Chỉ những 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 của riêng họ, trong đó có tính năng hội viên. 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 hỗ trợ tài chính định kỳ cho một nhà sáng tạo và nhận 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 một cuộc trò chuyện.

Phương thức

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

list
Liệt kê 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 uỷ quyền.

Biểu thị tài nguyên

Cấu trúc JSON sau đây cho thấy đị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
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 phần.
snippet.creatorChannelId string
Mã nhận dạng kênh YouTube của nhà sáng tạo cung cấp gói 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ó những thành viên không có dữ liệu hồ sơ. Ví dụ: trường hợp này xảy ra với những hội viên đã xoá kênh nhưng vẫn 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 API bao gồm tài nguyên cho các thành viê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 những thành viên như vậy.
snippet.memberDetails.channelId string
Mã nhận dạng kênh YouTube của kênh thành viên. Nếu được đặt, mã nhận dạng kênh cũng có thể được coi là giá trị nhận dạng duy nhất cho thành viên. Nếu bạn không đặt thuộc tính này, thì bạn 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ề gói 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 của gói thành viên.
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ã của cấp hội viên cao nhất mà kênh hội viên hiện có thể truy cập. 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 tài nguyên membershipsLevel.
snippet.membershipsDetails.accessibleLevels[] list (of strings)
Danh sách mã nhận dạng cho 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 cấp đó.
snippet.membershipsDuration object
Đối tượng này chứa thông tin về tổng thời lượng gói thành viên hiện tại của thành viên mà không phụ thuộc vào mức giá. Sau đó, thuộc tính snippet.membershipsDetails.membershipsDurationAtLevel[] sẽ chứa danh sách các đối tượng chứa thông tin chi tiết về một khoảng thời gian của gói 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ể.

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 gói thành viên mới vào tháng 1 ở cấp thành viên 1 và có gói thành viên đó cho đến tháng 3. Vào tháng 4 và tháng 5, thành viên này không có gói thành viên. Vào tháng 6, người dùng này lại mua gói hội viên ở cấp 1. Sau đó, vào tháng 8, thành viên này nâng cấp gói hội viên lên cấp 2. Vì vậy, nếu một lệnh gọi API được thực hiện vào tháng 10, thì 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 thành viên hiện tại của thành viên. Nói cách khác, thành viên này đã liên tục có gói thành viên kể từ ngày và giờ này. Xin lưu ý rằng các khoảng thời gian sử dụng gói thành viên có thể ở các cấp độ thành viên khác nhau.
snippet.membershipsDuration.memberTotalDurationMonths integer
Số tháng (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 trọn vẹn mà thành viên đã có gói thành viên, nhưng con số này không có nghĩa là thành viên đã liên tục có gói thành viên trong nhiều tháng như vậy.
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 của gói thành viên 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 hội 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à hội viên có quyền truy cập vào cấp hội viên được chỉ định. Nói cách khác, thành viên này liên tục có quyền truy cập vào cấp này kể từ ngày và giờ này. Xin lưu ý rằng các khoảng thời gian của gói hội viên có thể đã được sử dụng ở các cấp hội viên cao hơn.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
Số tháng (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 hoàn chỉnh mà thành viên có quyền sử dụng cấp đó, nhưng con số này không có nghĩa là thành viên liên tục có gói thành viên trong nhiều tháng như vậy.