本頁面由 Cloud Translation API 翻譯而成。

Channels: list

注意：channel 資源的 statistics.subscriberCount 屬性值已更新，以反映 YouTube 政策變更，這項變更會影響訂閱者人數的顯示方式。詳情請參閱「修訂版本記錄」或 YouTube 說明中心。

傳回符合要求條件的 channel 資源集合 (0 個以上)。

配額影響：呼叫此方法的配額費用為 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 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 在回應對此方法的呼叫時可能傳回的錯誤訊息。詳情請參閱「YouTube Data 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 要求和回應。