注意事項:
channel
資源的 statistics.subscriberCount
屬性值已更新,以因應 YouTube 政策異動,這會影響訂閱人數的顯示方式。詳情請參閱修訂版本記錄或 YouTube 說明中心。
傳回符合要求條件的零或多個 channel
資源集合。
配額影響:呼叫這個方法的配額為 1 個單位。
常見用途
要求
HTTP 要求
GET https://www.googleapis.com/youtube/v3/channels
授權
擷取 channel
資源的 auditDetails
部分的要求必須提供包含 https://www.googleapis.com/auth/youtubepartner-channel-audit
範圍的授權權杖。此外,當 MCN 決定接受或拒絕頻道時,或在核發權杖後的兩週內,必須撤銷使用該範圍的權杖。
參數
下表列出此查詢支援的參數。這裡列出的參數全都是查詢參數。
參數 | ||
---|---|---|
必要參數 | ||
part |
string part 參數會指定一份以半形逗號分隔的清單,列出一或多個 API 回應會包含的 channel 資源屬性。如果參數識別含有子屬性的屬性,則回應中會加入這些子項屬性。舉例來說,在 channel 資源中,contentDetails 屬性包含 uploads 等其他屬性。因此,如果您設定 part=contentDetails ,API 回應也會包含所有巢狀屬性。以下清單包含您可以加入參數值中的 part 名稱:
|
|
篩選器 (請僅指定下列其中一個參數) | ||
categoryId |
string 這個參數已淘汰。 categoryId 參數已指定 YouTube 指南類別,可用於要求與該類別相關的 YouTube 頻道。 |
|
forHandle |
string forHandle 參數可指定 YouTube 帳號代碼,進而要求與該帳號相關聯的頻道。參數值前方可以加上 @ 符號。舉例來說,如要擷取「Google for Developers」管道的資源,請將 forHandle 參數值設為 GoogleDevelopers 或 @GoogleDevelopers 。 |
|
forUsername |
string forUsername 參數可指定 YouTube 使用者名稱,藉此要求與該使用者名稱相關聯的頻道。 |
|
id |
string id 參數會指定待擷取資源的 YouTube 頻道 ID 清單 (以半形逗號分隔)。在 channel 資源中,id 屬性會指定頻道的 YouTube 頻道 ID。 |
|
managedByMe |
boolean 這個參數只能在正確的授權要求中使用。注意:這個參數僅適用於 YouTube 內容合作夥伴。 請將這個參數的值設為 true ,指示 API 只傳回由 onBehalfOfContentOwner 參數指定的內容擁有者所管理的頻道。使用者必須以與指定內容擁有者相連結的 CMS 帳戶的身分進行驗證,且必須提供 onBehalfOfContentOwner 。 |
|
mine |
boolean 這個參數只能在正確的授權要求中使用。將這個參數的值設為 true ,即可指示 API 只傳回已驗證使用者擁有的管道。 |
|
選用參數 | ||
hl |
string hl 參數可指示 API 擷取 YouTube 網站支援的特定應用程式語言的本地化資源中繼資料。參數值必須是 i18nLanguages.list 方法傳回的清單中的語言代碼。如果該語言有本地化的資源詳細資料,則資源的 snippet.localized 物件會包含本地化值。不過,如果沒有可用的本地化詳細資料,snippet.localized 物件就會以資源預設語言中的資源詳細資料提供資源詳細資料。 |
|
maxResults |
unsigned integer maxResults 參數會指定結果集應傳回的項目數量上限。可接受的值為 0 到 50 (含頭尾)。預設值為 5 。 |
|
onBehalfOfContentOwner |
string 這個參數只能在正確的授權要求中使用。注意:這個參數僅適用於 YouTube 內容合作夥伴。 onBehalfOfContentOwner 參數代表透過要求的授權憑證,代表 YouTube CMS 使用者,代表在參數值中指定的內容擁有者擔任代理人。這個參數適用於擁有及管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。內容擁有者只要通過一次驗證,即可存取所有影片和頻道資料,不必分別提供各個頻道的驗證憑證。用於驗證的 CMS 帳戶,必須連結至指定的 YouTube 內容擁有者。 |
|
pageToken |
string pageToken 參數可在結果集中指明應傳回的特定網頁。在 API 回應中,nextPageToken 和 prevPageToken 屬性會識別其他可擷取的網頁。 |
要求主體
呼叫此方法時,不要提供要求主體。
回應
如果成功的話,這個方法會傳回回應內文,其結構如下:
{ "kind": "youtube#channelListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ channel Resource ] }
屬性
下表定義了這項資源中顯示的屬性:
屬性 | |
---|---|
kind |
string 識別 API 資源的類型。值為 youtube#channelListResponse 。 |
etag |
etag 這項資源的 Etag。 |
nextPageToken |
string 可做為 pageToken 參數值的權杖,用於擷取結果集中的下一頁。 |
prevPageToken |
string 可做為 pageToken 參數值的權杖,可在結果集中擷取上一頁。請注意,如果對應的 API 要求將 managedByMe 參數設為 true ,API 回應中就不會包含這個屬性。 |
pageInfo |
object pageInfo 物件會封裝結果集的分頁資訊。 |
pageInfo.totalResults |
integer 結果集的結果總數。 |
pageInfo.resultsPerPage |
integer API 回應中包含的結果數量。 |
items[] |
list 符合要求條件的頻道清單。 |
錯誤
下表列出 API 回應此方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息的說明文件。
錯誤類型 | 錯誤詳細資料 | 說明 |
---|---|---|
badRequest (400) |
invalidCriteria |
最多可以指定下列其中一個篩選器:id 、categoryId 、mine 、managedByMe 、forHandle 、forUsername 。如果透過 onBehalfOfContentOwner 參數驗證內容擁有者,則只能指定 id 或 managedByMe 。 |
forbidden (403) |
channelForbidden |
id 參數指定的管道不支援該要求,或是未獲適當授權。 |
notFound (404) |
categoryNotFound |
無法找到 categoryId 參數識別的類別。使用 guideCategories.list 方法擷取有效值的清單。 |
notFound (404) |
channelNotFound |
找不到 id 參數中指定的頻道。 |
試試看!
使用 APIs Explorer 呼叫這個 API 並查看 API 要求和回應。