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

PlaylistItems: insert

將資源新增至播放清單。

配額影響：呼叫這個方法的配額費用為 50 個單位。

常見用途

要求

HTTP 要求

POST https://www.googleapis.com/youtube/v3/playlistItems

授權

這項要求需要至少下列其中一個範圍的授權 (進一步瞭解驗證和授權)。

內容範圍
`https://www.googleapis.com/auth/youtubepartner`
`https://www.googleapis.com/auth/youtube`
`https://www.googleapis.com/auth/youtube.force-ssl`

參數

下表列出此查詢支援的參數。這裡列出的參數全都是查詢參數。

參數
必要參數
`part`	`string` 在這項作業中，`part` 參數有兩個用途。它會指出寫入作業設定的屬性，以及 API 回應會包含的屬性。下列清單包含可在參數值中加入的 `part` 名稱： `contentDetails` `id` `snippet` `status`
選用參數
`onBehalfOfContentOwner`	`string` 這個參數只能在正確的授權要求中使用。注意：這個參數僅適用於 YouTube 內容合作夥伴。 `onBehalfOfContentOwner` 參數代表透過要求的授權憑證，代表 YouTube CMS 使用者，代表在參數值中指定的內容擁有者擔任代理人。這個參數適用於擁有及管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。內容擁有者只要通過一次驗證，即可存取所有影片和頻道資料，不必分別提供各個頻道的驗證憑證。用於驗證的 CMS 帳戶，必須連結至指定的 YouTube 內容擁有者。

要求主體

在要求主體中提供 playlistItem 資源。針對該資源：

您必須指定下列屬性的值：
- snippet.playlistId
- snippet.resourceId
您可以設定下列屬性的值：
- snippet.playlistId
- snippet.position
- snippet.resourceId
- contentDetails.note
- contentDetails.startAt
- contentDetails.endAt

回應

如果成功的話，這個方法會在回應內文中傳回 playlistItem 資源。

錯誤

下表列出 API 回應此方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息的說明文件。

錯誤類型	錯誤詳細資料	說明
`forbidden (403)`	`playlistContainsMaximumNumberOfVideos`	播放清單內含的項目數量已達上限。
`forbidden (403)`	`playlistItemsNotAccessible`	這項要求未獲適當授權，無法插入指定的播放清單項目。
`invalidValue (400)`	`invalidContentDetails`	要求中的 `contentDetails` 屬性無效。可能的原因是 `contentDetails.note` 欄位的長度超過 280 個半形字元。
`invalidValue (400)`	`invalidPlaylistItemPosition`	這項要求嘗試將播放清單項目的位置設為無效或不支援的值。檢查資源 `snippet` 中 `position` 屬性的值。
`invalidValue (400)`	`invalidResourceType`	系統不支援針對資源 ID 指定的 `type`，進行這項作業。資源 ID 可用來識別要加入播放清單的項目，例如 `youtube#video`。
`invalidValue (400)`	`manualSortRequired`	這項要求嘗試設定播放清單項目的位置，但播放清單並未使用手動排序。(例如，播放清單項目可以依照日期或熱門程度排序)。如要解決這個錯誤，請從要求插入的資源中移除 `snippet.position` 元素。如果您希望播放清單項目在清單中的特定位置，請先在播放清單設定中，將播放清單的「排序」選項更新為「手動」。你可以前往 YouTube 影片管理員調整這項設定。
`invalidValue (400)`	`videoAlreadyInAnotherSeriesPlaylist`	你要加入播放清單的影片已在另一個系列播放清單中。
`notFound (404)`	`playlistNotFound`	找不到使用要求 `playlistId` 參數指定的播放清單。
`notFound (404)`	`videoNotFound`	找不到您要加入播放清單的影片。檢查 `videoId` 屬性的值，確認該值正確無誤。
`required (400)`	`channelIdRequired`	要求並未指定必要的 `channelId` 屬性值。
`required (400)`	`playlistIdRequired`	要求並未指定必要的 `playlistId` 屬性值。
`required (400)`	`resourceIdRequired`	要求必須包含 `snippet` 物件指定 `resourceId` 的資源。
`invalidValue (400)`	`playlistOperationUnsupported`	API 不支援將影片插入指定的播放清單。舉例來說，你無法在上傳的影片播放清單中插入影片。

試試看！

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