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 也可視為會員的專屬 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
使用者可存取指定層級的月份數量，四捨五入至最接近的整數。這個值代表會員可使用該等級的完整月份數，但這個數字並不表示會員連續訂閱了這麼多個月。