Members: list

注意：只有個別創作者才能使用這個端點，為自己的 YouTube 頻道啟用頻道會員功能。如需存取權限，請聯絡 Google 或 YouTube 代表。

列出頻道的會員 (舊稱「贊助者」)。API 要求必須獲得頻道擁有者的授權。

配額影響：呼叫這個方法的配額為 2 個單位。

要求

HTTP 要求

GET https://www.googleapis.com/youtube/v3/members

授權

這項要求需要取得下列範圍的授權：

內容範圍
https://www.googleapis.com/auth/youtube.channel-memberships.creator

參數

下表列出此查詢支援的參數。這裡列出的參數全都是查詢參數。

參數
必要參數
part string
part 參數會指定 API 回應會包含的 member 資源屬性。將參數值設為 snippet。
選用參數
mode string
mode 參數會指出 API 回應將包含哪些成員。將參數值設為下列其中一個值：
  • all_current (預設)：列出目前成員 (由新到舊)。如果使用這個值，則當 API 回應不含 nextPageToken 時，會到達清單結尾。
  • updates：只列出自上次 API 呼叫後加入或升級的成員。請注意，第一個呼叫會啟動新的更新串流，但實際上不會傳回任何成員。如要開始擷取成員資格更新內容，您必須按照所需頻率使用 nextPageToken 輪詢端點。

    請注意，使用這個值時，API 回應一律包含 nextPageToken。
maxResults unsigned integer
maxResults 參數會指定結果集應傳回的項目數量上限。可接受的值為 0 到 1000 (含頭尾)。預設值為 5。
pageToken string
pageToken 參數可識別結果集中應傳回的特定網頁。權杖專屬於搭配原始 API 要求使用的 mode，因此您無法使用以一種模式擷取的頁面符記在後續切換至其他模式。
hasAccessToLevel string
hasAccessToLevel 參數值是一種等級 ID，用來指定結果集內的成員應具備的最低等級。
filterByMemberChannelId string
filterByMemberChannelId 參數會指定一份以半形逗號分隔的頻道 ID 清單，可用於查看特定使用者的會員資格狀態。例如：UC_1,UC_2,UC_3。每次呼叫最多可以指定 100 個管道。

要求主體

呼叫此方法時，不要提供要求主體。

回應

如果成功的話，這個方法會傳回回應內文，其結構如下：

{
  "kind": "youtube#memberListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    member Resource
  ]
}

屬性

下表定義了這項資源中顯示的屬性：

屬性
kind string
識別 API 資源的類型。值為 youtube#memberListResponse。
etag etag
這項資源的 Etag。
nextPageToken string
可做為 pageToken 參數值的權杖，擷取結果集的下一頁。網頁權杖可能會過期，因此應用程式應捨棄權杖，並在沒有 pageToken 的情況下呼叫 API，以啟動新的要求。
pageInfo object
pageInfo 物件會封裝結果集的分頁資訊。
pageInfo.totalResults integer
結果集的結果總數。
pageInfo.resultsPerPage integer
API 回應中包含的結果數量。
items[] list
符合要求條件的成員清單。

錯誤

下表列出 API 回應此方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息的說明文件。

錯誤類型 錯誤詳細資料 說明
badRequest (400) channelMembershipsNotEnabled 授權要求的創作者頻道未啟用頻道會員功能。
badRequest (400) invalidMode mode 參數值無效。如果 pageToken 參數指定的權杖使用不是指定的模式擷取，就可能會發生這個錯誤。
badRequest (400) invalidPageToken pageToken 參數值無效。如果要求中使用的頁面權杖過期或無法辨識，就有可能發生這個錯誤。
badRequest (400) invalidHasAccessToLevel hasAccessToLevel 參數值無效。沒有具有指定的 id 的等級。
badRequest (400) invalidFilterByMemberChannelId filterByMemberChannelId 參數值無效。如果 filterByMemberChannelId 參數值指定的管道超過 100 個，就會發生這個錯誤。