注意事項:
這個端點只能由個別創作者使用,可以要求頻道已啟用頻道會員功能的 YouTube 頻道。請與您的 Google 或 YouTube 代表聯絡,要求存取權。
members
端點自 2020 年 3 月 31 日起將取代 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 也可以視為會員的專屬 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 月份加入會員層級 1 的新成員,且該會員資格在 3 月份前都為新會員。在 4 月和 5 月,該會員沒有會員資格。6 月時,該會員又恢復了第 1 級的會員資格。接著在 8 月將會員升級為第 2 級會員,因此,如果 API 呼叫在 10 月發出, 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 使用者可存取的指定月數,四捨五入至最接近的整數。這個值反映了成員可存取當月的完整月份數,但這個數字並不表示會員已連續擁有好幾個月的會員資格。 |