PlaylistItems

playlistItem 資源會識別播放清單中包含的其他資源，例如影片。此外，playlistItem 資源包含所含資源的詳細資料，具體說明該資源在播放清單中的使用方式。

YouTube 也會使用播放清單來識別頻道上傳的影片清單，清單中的每個 playlistItem 都代表一部上傳的影片。您可以從指定頻道的 channel 資源中，擷取該清單的播放清單 ID。然後，您就可以使用 playlistItems.list 方法將項目新增至清單。

方法

這個 API 支援 playlistItems 資源的下列方法：

list
傳回符合 API 要求參數的播放清單項目集合。您可以擷取指定播放清單中的所有播放清單項目，也可以依據一或多個播放清單項目的專屬 ID 擷取項目。 立即試用。
插入
將資源新增至播放清單。 立即試用。
更新
修改播放清單項目。舉例來說，你可以更新項目在播放清單中的位置。 立即試用。
刪除
刪除播放清單項目。 立即試用。

資源表示法

下列 JSON 結構顯示 playlistItems 資源的格式：

{
  "kind": "youtube#playlistItem",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "channelTitle": string,
    "videoOwnerChannelTitle": string,
    "videoOwnerChannelId": string,
    "playlistId": string,
    "position": unsigned integer,
    "resourceId": {
      "kind": string,
      "videoId": string,
    }
  },
  "contentDetails": {
    "videoId": string,
    "startAt": string,
    "endAt": string,
    "note": string,
    "videoPublishedAt": datetime
  },
  "status": {
    "privacyStatus": string
  }
}

屬性

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

屬性
kind string
識別 API 資源的類型。值為 youtube#playlistItem。
etag etag
這項資源的 Etag。
id string
YouTube 用來識別播放清單項目的專屬 ID。
snippet object
snippet 物件包含播放清單項目的基本詳細資料，例如標題和在播放清單中的位置。
snippet.publishedAt datetime
商品加入播放清單的日期和時間。值以 ISO 8601 格式指定。
snippet.channelId string
YouTube 用來識別將項目新增至播放清單的使用者 ID。
snippet.title string
項目的標題。
snippet.description string
項目的說明。
snippet.thumbnails object
與播放清單項目相關的縮圖地圖。地圖中的每個物件，其鍵都是縮圖圖片的名稱，值則是包含縮圖其他資訊的物件。
snippet.thumbnails.(key) object
有效鍵值如下：
  • default：預設縮圖圖片。影片的預設縮圖 (或參照影片的資源，例如播放清單項目或搜尋結果) 寬度為 120 像素，高度為 90 像素。頻道的預設縮圖寬度和高度皆為 88 像素。
  • medium：縮圖圖片的高解析度版本。如果是影片 (或參照影片的資源)，這張圖片的寬度為 320 像素，高度為 180 像素。如果是頻道，這張圖片的寬度和高度都是 240 像素。
  • high - 縮圖圖片的高解析度版本。如果是影片 (或參照影片的資源)，這張圖片的寬度為 480 像素，高度為 360 像素。如果是頻道，這張圖片的寬度和高度都是 800 像素。
  • standard：比 high 解析度圖片解析度更高的縮圖圖片。這張圖片適用於部分影片，以及參照影片的其他資源，例如播放清單項目或搜尋結果。這張圖片的寬度為 640 像素，高度為 480 像素。
  • maxres：縮圖圖片的最高解析度版本。部分影片和其他參照影片的資源 (例如播放清單項目或搜尋結果) 會顯示這個尺寸的圖片。這張圖片的寬度為 1280 像素，高度為 720 像素。
snippet.thumbnails.(key).url string
圖片的網址。
snippet.thumbnails.(key).width unsigned integer
圖片寬度。
snippet.thumbnails.(key).height unsigned integer
圖片的高度。
snippet.channelTitle string
播放清單項目所屬頻道的頻道標題。
snippet.videoOwnerChannelTitle string
上傳這部影片的頻道名稱。
snippet.videoOwnerChannelId string
上傳這部影片的頻道 ID。
snippet.playlistId string
YouTube 用來識別播放清單項目的播放清單 ID。
snippet.position unsigned integer
項目在播放清單中的顯示順序。這個值採用以零為起始的索引，因此第一個項目的位置為 0，第二個項目的位置為 1，依此類推。
snippet.resourceId object
id 物件包含可用於專屬識別資源的資訊，該資源會以播放清單項目的形式納入播放清單。
snippet.resourceId.kind string
所參照資源的種類或類型。
snippet.resourceId.videoId string
如果 snippet.resourceId.kind 屬性的值為 youtube#video，則會顯示這項屬性，且其值會包含 YouTube 用來在播放清單中專屬識別影片的 ID。
contentDetails object
如果內含項目是 YouTube 影片，資源中就會包含 contentDetails 物件。這個物件包含影片的額外資訊。
contentDetails.videoId string
YouTube 用於識別影片的專屬 ID。如要擷取 video 資源，請在 API 要求中將 id 查詢參數設為這個值。
contentDetails.startAt string
注意：這項屬性已淘汰，如果設定，系統會忽略其值。

影片應開始播放的時間，以影片開始播放後經過的秒數表示。(播放清單擁有者可以指定影片在播放清單中播放時的開始和停止時間)。預設值為 0。
contentDetails.endAt string
注意：這項屬性已淘汰，如果設定，系統會忽略其值。

影片應停止播放的時間，以影片開始播放後的秒數計算。(播放清單擁有者可以指定影片在播放清單中播放時的開始和停止時間)。根據預設，video.endTime 是影片結尾。
contentDetails.note string
這項商品的使用者生成附註。屬性值的長度上限為 280 個半形字元。
contentDetails.videoPublishedAt datetime
影片發布到 YouTube 的日期和時間。值以 ISO 8601 格式指定。
status object
status 物件包含播放清單項目的隱私權狀態資訊。
status.privacyStatus string
播放清單項目的隱私權狀態。上傳播放清單項目代表影片的頻道，可以使用 videos.insert 或 videos.update 方法設定這個值。