將資源新增至播放清單。
配額影響:呼叫此方法的配額費用為 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 名稱:
|
|
選用參數 | ||
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 要求和回應。