Playlists

playlist 資源代表 YouTube 播放清單。播放清單是一組可依序觀看並分享給其他使用者的影片。根據預設,其他使用者都能看見播放清單,但播放清單中的瀏覽權限可以設為公開或私人。

YouTube 也會利用播放清單來表揚頻道上的特別影片集,例如:

  • 上傳的影片
  • 評分 (喜歡) 的影片
更具體來說,這些清單會與某個頻道建立關聯,也就是由使用者、團體或公司的影片、播放清單和其他 YouTube 資訊集結而成。您可以透過特定頻道的 channel resource 擷取這些清單的播放清單 ID。

接著,您可以使用 playlistItems.list 方法擷取任何這些清單。您也可以呼叫 playlistItems.insertplaylistItems.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 用來識別發布播放清單的頻道 ID。
snippet.title string
播放清單的標題。
snippet.description string
播放清單的說明。
snippet.thumbnails object
與播放清單相關聯的縮圖地圖。對於地圖中的每個物件,鍵是縮圖圖片的名稱,值則是包含縮圖其他資訊的物件。
snippet.thumbnails.(key) object
有效的鍵值如下:
  • default:預設縮圖圖片。影片的預設縮圖,或指向影片 (例如播放清單項目或搜尋結果) 的資源縮圖,寬度為 120 像素,高度為 90 像素。頻道的預設縮圖寬度為 88 像素,高度為 88 像素。
  • medium:解析度較高的縮圖圖片。影片 (或影片資源) 寬度為 320 像素,高度為 180 像素。頻道的圖片寬度為 240px,高度為 240px。
  • high:縮圖的高解析度版本。影片 (或影片資源) 寬度為 480px,高度為 360px。頻道圖片的寬度和高度為 800px 和 800px。
  • standard - 比 high 解析度圖片更高的縮圖圖片解析度版本。這張圖片用於部分影片和其他有關影片的資源,例如播放清單項目或搜尋結果。此圖片的寬度為 640px,高度為 480px。
  • maxres:縮圖圖片的解析度最高版本。這個圖片大小適用於部分影片和其他有關影片的資源,例如播放清單項目或搜尋結果。此圖片的寬度為 1280px,高度為 720px。
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.titlesnippet.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
本地化的播放清單說明。