Members

注意：自 2020 年 3 月 31 日起，members 端點會取代目前已淘汰的 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 頻道的設定檔資料。

請注意，頻道中的會員可能沒有個人資料。舉例來說，如果會員已刪除頻道，但仍需支付會員費用，就可能發生這種情況。請注意，這些會員仍可享有會員福利。

即使尚未設定 memberDetails 物件中的設定檔詳細資料，這些成員的 API 回應也會包含相關資源，以確保計數準確無誤。系統仍會為這類成員提供 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
使用者可存取指定級別的月數 (會無條件捨去至最接近的整數)。這個值反映了會員能享有該等級的完整月數，但數字不代表會員在這幾個月中持續保有會員資格。