Videos: list

傳回符合 API 要求參數的影片清單。

配額影響：呼叫這個方法會產生 1 個單位的配額費用。

常見用途

要求

HTTP 要求

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

參數

下表列出這項查詢支援的參數。列出的所有參數都是查詢參數。

參數
必要參數
part string
part 參數會指定一或多個 video 資源屬性的半形逗號分隔清單，API 回應會包含這些屬性。

如果參數識別的屬性包含子項屬性，回應中就會包含子項屬性。舉例來說，在 video 資源中，snippet 屬性包含 channelId、title、description、tags 和 categoryId 屬性。因此，如果您設定 part=snippet，API 回應就會包含所有這些屬性。

下列清單包含可納入參數值的 part 名稱：
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
篩選器 (請指定下列其中一個參數)
chart string
chart 參數用於指定要擷取的排行榜。

可接受的值如下：
id string
id 參數會指定要擷取資源的 YouTube 影片 ID 清單 (以半形逗號分隔)。在 video 資源中，id 屬性會指定影片的 ID。
myRating string

這項參數只能用於已授權的要求。將這個參數的值設為 like 或 dislike，指示 API 只傳回已驗證使用者喜歡或不喜歡的影片。



API 傳回的結果集最多包含 1,000 部影片。即使回應的 pageInfo.totalResults 屬性指出總數較高，使用 pageToken 參數進行分頁時，也只能擷取最新的 1000 個項目。



這項參數可接受下列值：

  • dislike：只傳回通過驗證的使用者不喜歡的影片。
  • like：只會傳回通過驗證的使用者按讚的影片。
選用參數
hl string
hl 參數會指示 API 擷取 YouTube 網站支援的特定應用程式語言本地化資源中繼資料。參數值必須是 i18nLanguages.list 方法傳回清單中的語言代碼。

如果該語言有本地化的資源詳細資料，資源的 snippet.localized 物件就會包含本地化的值。不過，如果沒有本地化詳細資料，snippet.localized 物件會包含資源預設語言的資源詳細資料。
maxHeight unsigned integer
maxHeight 參數會指定 player.embedHtml 屬性傳回的內嵌播放器高度上限。您可以透過這個參數指定嵌入碼應使用適合應用程式版面配置的高度，而非預設尺寸。如果同時提供 maxWidth 參數，播放器的高度可能會低於 maxHeight，以免超過寬度上限。可接受的值為 72 至 8192 (含)。
maxResults unsigned integer
maxResults 參數會指定結果集中應傳回的項目數量上限。

注意：這個參數可與 myRating 參數搭配使用，但無法與 id 參數搭配使用。可接受的值為 1 至 50 (含)。預設值為 5。
maxWidth unsigned integer
maxWidth 參數會指定 player.embedHtml 屬性傳回的內嵌播放器寬度上限。您可以使用這個參數指定嵌入程式碼應使用適合應用程式版面配置的寬度，而非預設尺寸。

如果同時提供 maxHeight 參數，播放器可能會比 maxWidth 窄，以免違反高度上限。可接受的值為 72 至 8192 (含)。
onBehalfOfContentOwner string
這個參數只能用於授權要求。注意：這個參數僅供 YouTube 內容合作夥伴使用。

onBehalfOfContentOwner 參數表示要求授權憑證識別的 YouTube CMS 使用者，是代表參數值中指定的內容擁有者行事。這個參數適用於擁有及管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。內容擁有者只需驗證一次，即可存取所有影片和頻道資料，不必為每個頻道提供驗證憑證。使用者驗證的 CMS 帳戶必須連結至指定的 YouTube 內容擁有者。
pageToken string
pageToken 參數會識別結果集中的特定網頁，並傳回該網頁。在 API 回應中，nextPageToken 和 prevPageToken 屬性會識別可擷取的其他網頁。

注意：這個參數可與 myRating 參數搭配使用，但無法與 id 參數搭配使用。
regionCode string
regionCode 參數會指示 API 選取指定區域可用的影片排行榜。這個參數只能與 chart 參數搭配使用。參數值為 ISO 3166-1 alpha-2 國家/地區代碼。
videoCategoryId string
videoCategoryId 參數會指定要擷取哪個影片類別的排行榜。這個參數只能與 chart 參數搭配使用。根據預設，排行榜不會限制特定類別。預設值為 0。

要求主體

呼叫這個方法時，請勿提供要求主體。

回應

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

{
  "kind": "youtube#videoListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    video Resource
  ]
}

屬性

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

屬性
kind string
識別 API 資源的類型。值為 youtube#videoListResponse。
etag etag
這項資源的 Etag。
nextPageToken string
這個權杖可做為 pageToken 參數的值，用於擷取結果集中的下一頁。
prevPageToken string
這個權杖可做為 pageToken 參數的值，用來擷取結果集中的上一頁。
pageInfo object
pageInfo 物件會封裝結果集的分頁資訊。
pageInfo.totalResults integer
結果集中的結果總數。
pageInfo.resultsPerPage integer
API 回應中包含的結果數量。
items[] list
符合要求條件的影片清單。

錯誤

下表列出 API 在呼叫這個方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息說明文件。

錯誤類型 錯誤詳情 說明
badRequest (400) videoChartNotFound 系統不支援或無法提供要求的影片排行榜。
forbidden (403) forbidden 要求未獲得適當授權，無法存取影片檔案或處理資訊。請注意，只有影片擁有者才能看到 fileDetails、processingDetails 和 suggestions 部分。
forbidden (403) forbidden 要求無法存取使用者評分資訊。如果要求未獲得適當授權，就無法使用 myRating 參數，因此可能會發生這個錯誤。
notFound (404) videoNotFound 找不到您要擷取的影片。請檢查要求 id 參數的值，確保正確無誤。

試試看！

使用 APIs Explorer 呼叫這個 API，並查看 API 要求和回應。