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

Videos: list

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

配額影響：呼叫此方法的配額費用為 1 單位。

常見用途

要求

HTTP 要求

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

參數

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

參數
必要參數
`part`	`string` `part` 參數會指定以逗號分隔的清單，其中包含 API 回應所包含的一或多個 `video` 資源屬性。如果參數指定的屬性包含子項資源，則子屬性將納入回應中。舉例來說，在 `video` 資源中，`snippet` 屬性包含 `channelId`、`title`、`description`、`tags` 和 `categoryId` 屬性。因此，如果您設定 `part=snippet`，API 回應就會包含以上所有屬性。以下清單包含可在參數值中加入的 `part` 名稱： `contentDetails` `fileDetails` `id` `liveStreamingDetails` `localizations` `player` `processingDetails` `recordingDetails` `snippet` `statistics` `status` `suggestions` `topicDetails`
篩選器 (請僅指定下列其中一個參數)
`chart`	`string` `chart` 參數可識別您想要擷取的圖表。可接受的值如下： `mostPopular` - 傳回指定內容地區和影片類別中最熱門的影片。
`id`	`string` `id` 參數會擷取以逗號分隔的 YouTube 影片 ID 清單。在 `video` 資源中，`id` 屬性會指定影片的 ID。
`myRating`	`string` 這個參數只能在妥善的授權要求中使用。將這個參數的值設為 `like` 或 `dislike`，指示 API 只傳回已驗證使用者喜歡或不喜歡的影片。可接受的值如下： `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 要求和回應。