Playlists

playlist 資源代表 YouTube 播放清單。播放清單就是影片的合輯，可依序觀看並分享給其他使用者。播放清單預設會公開顯示給其他使用者，但播放清單可以設為公開或私人。

YouTube 也會使用播放清單，找出頻道的特殊影片集，例如：

  • 上傳的影片
  • 獲得好評 (喜歡) 的影片
具體來說，這些名單會與頻道建立關聯，而頻道是個人、團體或公司的影片、播放清單和其他 YouTube 資訊的集合。你可以從指定頻道的 channel resource 擷取這些清單的播放清單 ID。

接著，您可以使用 playlistItems.list 方法擷取任一清單。您也可以呼叫 playlistItems.insert 和 playlistItems.delete 方法，從這些清單新增或移除項目。

方法

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

list
傳回符合 API 要求參數的播放清單集合。舉例來說，您可以擷取已驗證使用者擁有的所有播放清單，也可以透過一或多個播放清單的專屬 ID 擷取播放清單。 立即試用。
插入
建立播放清單。 立即試用。
更新
修改播放清單。舉例來說，你可以變更播放清單的標題、說明或隱私權狀態。 立即試用。
刪除
刪除播放清單。 立即試用。

資源表示法

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

{
  "kind": "youtube#playlist",
  "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,
    "defaultLanguage": string,
    "localized": {
      "title": string,
      "description": string
    }
  },
  "status": {
    "privacyStatus": string,
    "podcastStatus": enum
  },
  "contentDetails": {
    "itemCount": unsigned integer
  },
  "player": {
    "embedHtml": string
  },
  "localizations": {
    (key): {
      "title": string,
      "description": string
    }
  }
}

屬性

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

屬性
kind string
識別 API 資源的類型。值為 youtube#playlist。
etag etag
這項資源的 Etag。
id string
YouTube 用來識別播放清單的專屬 ID。
snippet object
snippet 物件包含播放清單的基本詳細資料，例如名稱和說明。
snippet.publishedAt datetime
播放清單的建立日期和時間。值以 ISO 8601 格式指定。
snippet.channelId string
YouTube 用來識別發布播放清單的頻道。
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.tags[] list
此屬性已淘汰。

與播放清單相關聯的關鍵字標記。
snippet.defaultLanguage string
playlist 資源 snippet.title 和 snippet.description 屬性中的文字語言。
snippet.localized object
snippet.localized 物件包含播放清單的本地化標題和說明，或是播放清單中繼資料的預設語言標題。
  • 如果 playlists.list 要求使用 hl 參數指定要傳回本地化文字的語言，且該語言有可用的本地化文字，資源代碼片段就會傳回本地化文字。
  • 如果未指定 hl 參數值或指定的值沒有相應的本地化中繼資料，系統會傳回預設語言的中繼資料。
屬性包含唯讀值。使用 localizations 物件新增、更新或刪除本地化名稱。
snippet.localized.title string
本地化播放清單標題。
snippet.localized.description string
本地化播放清單說明。
status object
status 物件包含播放清單的狀態資訊。
status.privacyStatus string
播放清單的隱私權狀態。

這個屬性的有效值如下：
  • private
  • public
  • unlisted
status.podcastStatus string
播放清單的 Podcast 狀態。如果值為 enabled，播放清單會標示為 Podcast 節目。如要將播放清單的 Podcast 狀態設為 enabled，播放清單必須有播放清單圖片。

這個屬性的有效值如下：
  • enabled
  • disabled
  • unspecified
contentDetails object
contentDetails 物件包含播放清單內容的相關資訊，包括播放清單中的影片數量。
contentDetails.itemCount unsigned integer
播放清單中的影片數量。
player object
player 物件包含的資訊可用於在嵌入式播放器中播放播放清單。
player.embedHtml string
<iframe> 標記，用於嵌入播放清單的播放器。
localizations object
localizations 物件會封裝播放清單中繼資料的翻譯內容。
localizations.(key) object
與鍵值相關聯的本地化文字語言。這個值是包含 BCP-47 語言代碼的字串。
localizations.(key).title string
本地化播放清單標題。
localizations.(key).description string
本地化播放清單說明。