Channels: list

注意：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 參數會指定一或多個 channel 資源屬性，並以逗號分隔的清單呈現，這些屬性會包含在 API 回應中。

如果參數識別的屬性包含子屬性，則子屬性會包含在回應中。舉例來說，在 channel 資源中，contentDetails 屬性包含其他屬性，例如 uploads 屬性。因此，如果您設定 part=contentDetails，API 回應也會包含所有這些巢狀屬性。

下列清單包含可納入參數值的 part 名稱：
  • auditDetails
  • brandingSettings
  • contentDetails
  • contentOwnerDetails
  • id
  • localizations
  • snippet
  • statistics
  • status
  • topicDetails
篩選器 (請指定下列其中一個參數)
categoryId string
這個參數已淘汰。 categoryId 參數指定了 YouTube 指南類別，可用於要求與該類別相關聯的 YouTube 頻道。
forHandle string
forHandle 參數會指定 YouTube 帳號代碼，藉此要求與該帳號代碼相關聯的頻道。參數值可加上 @ 符號。舉例來說，如要擷取「Google 開發人員平台」頻道的資源，請將 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 在呼叫這個方法時可能傳回的錯誤訊息。詳情請參閱「YouTube Data API - Errors」。

錯誤類型 錯誤詳情 說明
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 要求和回應。