Members

注意事項: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
使用者可存取的指定月數,四捨五入至最接近的整數。這個值反映了成員可存取當月的完整月份數,但這個數字並不表示會員已連續擁有好幾個月的會員資格。