實作：播放清單

以下範例說明如何使用 YouTube Data API (v3) 執行與播放清單和播放清單項目相關的函式。

擷取目前使用者的播放清單

呼叫 playlists.list 方法，以擷取目前已驗證使用者的播放清單。在要求中，將 mine 參數的值設為 true。請注意，使用 mine 參數的要求必須透過 OAuth 2.0 授權。

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.list?
        part=snippet,contentDetails
        &mine=true

擷取使用者的播放清單

這個範例會擷取特定頻道建立的播放清單。此範例包含兩個步驟：

擷取特定播放清單的相關資訊

如要擷取一或多個特定播放清單的相關資訊，請呼叫 playlists.list 方法，並將 id 參數設定為以逗號分隔的 YouTube 播放清單 ID 清單，以識別所需的資源。這項功能的常見用途，是針對一組搜尋結果傳回的一組播放清單擷取額外資訊。舉例來說，您可以擷取每個播放清單中的項目數量。

以下要求會呼叫 playlists.list 方法，以擷取兩個符合查詢字詞「GoogleDevelopers」的播放清單中項目的數量。這項資訊位於 playlist 資源的 contentDetails.itemCount 屬性中，因此要求會將 part 參數值設為 contentDetails。 

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.list?
        part=contentDetails
        &id=PLOU2XLYxmsIIM9h1Ybw2DuRw6o2fkNMeR,PLyYlLs02rgBYRWBzYpoHz7m2SE8mEZ68w

新增播放清單

這個範例會呼叫 playlists.insert 方法，在已驗證的使用者頻道中建立私人播放清單。使用這個方法發出的任何 API 要求都必須使用 OAuth 2.0 授權。

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.insert?
        part=snippet,status

APIs Explorer 的連結也會設定參數，指定 API 要求的主體。要求主體包含 playlist 資源，其定義了播放清單的標題、說明和隱私設定等相關資訊。在這個範例中，要求主體為：

{
  "snippet": {
    "title": "New playlist",
    "description": "New playlist description"
  },
  "status": {
    "privacyStatus": "private"
  }
}

相關程式碼範例：Java、JavaScript、.NET、PHP、Python

更新播放清單

這個範例會將播放清單的隱私設定狀態從「private」更新為「public」。此範例包含兩個步驟：

  • 步驟 1：擷取播放清單 ID

    呼叫 playlist.list 方法，以擷取目前已驗證使用者頻道中的播放清單。以上擷取目前使用者的播放清單的範例要求示範如何示範這項要求。呼叫 API 的應用程式可以處理 API 回應以顯示播放清單清單，並將每個播放清單的 ID 做為索引鍵。

  • 步驟 2：更新播放清單

    呼叫 playlists.update 方法可修改特定播放清單。這種方法需要有效的 OAuth 2.0 授權憑證。

    要求主體必須包含 playlist 資源的 snippet 部分，因為呼叫此方法時必須使用 snippet.title 屬性。此外，如果正在更新的播放清單資源指定了 snippet.description 或 snippet.tags 屬性的值，則必須在更新要求中指定這些值，否則系統會予以刪除。

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.update?
        part=snippet,status

    如上例所示，在新增播放清單時，API Explorer 連結會設定 參數來指定 API 要求的主體。要求主體包含 playlist 資源，其定義了播放清單的標題、說明和隱私設定等相關資訊。此範例使用以下要求主體：

    {
  "id": "PLAYLIST_ID",
  "snippet": {
    "title": "New playlist",
    "description": "New playlist description"
  },
  "status": {
    "privacyStatus": "public"
  }
}

    注意：如果您是在 APIs Explorer 中測試這項查詢，就必須將有效的播放清單 ID 替換為資源主體。如要取得播放清單的 ID，建議您先執行上述新增播放清單的要求。從 API 回應中擷取播放清單 ID，並使用您要更新的播放清單值。本範例中，播放清單使用的標題和說明與範例使用的相同。

新增播放清單項目

這個範例會將一個項目新增至播放清單。此要求必須使用 OAuth 2.0 授權。此範例包含兩個步驟：

  • 步驟 1：擷取合適的播放清單 ID

    呼叫 playlist.list 方法，以擷取目前已驗證使用者頻道中的播放清單。以上擷取目前使用者的播放清單的範例要求示範如何示範這項要求。呼叫 API 的應用程式可以處理 API 回應以顯示播放清單清單，並將每個播放清單的 ID 做為索引鍵。

  • 步驟 2：將影片新增至播放清單

    呼叫 playlistItems.insert 方法，將影片新增至播放清單。此要求必須使用 OAuth 2.0 授權。要求主體是至少指定以下值的 playlistItem 資源：

    下方的 API 要求會將影片新增至播放清單。要求內容如下：

    {
  "snippet": {
    "playlistId": "PLAYLIST_ID",
    "resourceId": {
      "kind": "youtube#video",
      "videoId": "VIDEO_ID"
    }
  }
}

    如要在 APIs Explorer 中完成要求，您必須設定 snippet.playlistId 和 snippet.resourceId.videoId 屬性的值。

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.insert?
        part=snippet

    注意：playlistItems.insert 方法的說明文件會說明您在新增播放清單項目時可以設定的其他屬性值。

更新播放清單項目

此範例會更新播放清單項目，使其是播放清單中的第一個項目。此要求必須使用 OAuth 2.0 授權。此範例有三個步驟：

  • 步驟 1：擷取合適的播放清單 ID

    呼叫 playlist.list 方法，以擷取目前已驗證使用者頻道中的播放清單。以上擷取目前使用者的播放清單的範例要求示範如何示範這項要求。呼叫 API 的應用程式可以處理 API 回應以顯示播放清單清單，並將每個播放清單的 ID 做為索引鍵。

  • 步驟 2：擷取所選播放清單中的項目

    呼叫 playlistItems.list 方法，以擷取所選播放清單中的影片清單。將 playlistId 參數的值設為您在步驟 1 中取得的播放清單 ID。

    API 回應中的每個資源都包含一個 id 屬性，該屬性可識別該項目的識別項目編號。在下一個步驟中，您將使用這個值從清單中移除項目。

  • 步驟 3：更新所選的播放清單項目

    呼叫 playlistItems.update 方法可變更影片在播放清單中的位置。將 part 參數值設為 snippet。要求主體必須為至少設定下列值的 playlistItem 資源：

    • 將 id 屬性設定為步驟 2 中取得的播放清單項目 ID。
    • 將 snippet.playlistId 屬性設定為步驟 1 中取得的播放清單 ID。
    • 將 snippet.resourceId.kind 屬性設定為 youtube#video。
    • 將 snippet.resourceId.videoId 屬性設定為能正確識別播放清單中影片的影片 ID。
    • 將 snippet.position 屬性設為 0，或決定您要顯示該項目的位置 (使用以 0 為基礎的索引)。

    下方的 API 要求會將播放清單項目更新為播放清單中的第一個項目。要求內容如下：

    {
  "id": "PLAYLIST_ITEM_ID",
  "snippet": {
    "playlistId": "PLAYLIST_ID",
    "resourceId": {
      "kind": "youtube#video",
      "videoId": "VIDEO_ID"
    },
    "position": 0
  }
}

    如要在 APIs Explorer 中完成要求，您必須設定 id、snippet.playlistId 和 snippet.resourceId.videoId 屬性的值。

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.update?
        part=snippet

移除播放清單項目

這個範例刪除播放清單中的影片。此要求必須使用 OAuth 2.0 授權。此範例有三個步驟。前兩個步驟與上述更新播放清單項目的步驟相同。

完成上述步驟之後，請呼叫 playlistItems.delete 方法，從播放清單中移除影片。針對要移除的項目，將要求的 id 參數設為播放清單項目 ID。此要求必須使用 OAuth 2.0 授權。

請注意，用於識別播放清單影片的播放清單項目 ID，與可識別影片的專屬 YouTube 影片 ID 不同。播放清單項目 ID 可將影片識別成特定播放清單中的項目。

如要在 APIs Explorer 中完成要求，您必須設定 id 屬性的值。

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.delete?
        id=PLAYLIST_ITEM_ID

移除播放清單

這個範例刪除播放清單。此範例包含兩個步驟：

  • 步驟 1：擷取播放清單 ID

    呼叫 playlist.list 方法，以擷取目前已驗證使用者頻道中的播放清單。以上擷取目前使用者的播放清單的範例要求示範如何示範這項要求。呼叫 API 的應用程式可以處理 API 回應以顯示播放清單清單，並將每個播放清單的 ID 做為索引鍵。

  • 步驟 2：刪除播放清單

    呼叫 playlists.delete 方法可刪除特定播放清單。在要求中，id 參數會指定待刪除播放清單的播放清單 ID。這種方法需要有效的 OAuth 2.0 授權憑證。如果您要在 APIs Explorer 中測試這項查詢，就必須將 id 參數值替換成有效的播放清單 ID。

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlists.delete?
        id=PLAYLIST_ID

    注意：如果您是在 APIs Explorer 中測試這項查詢，就必須將 id 參數值換成有效的播放清單 ID。如要取得播放清單的 ID，建議您先執行上述新增播放清單的要求。從 API 回應中擷取播放清單 ID，然後用做要刪除的播放清單。