本頁面由 Cloud Translation API 翻譯而成。

API 要求範例

本頁面顯示傳送至 YouTube Data API 的要求範例。您可以使用 YouTube Data API 擷取及操控影片、頻道、播放清單等 YouTube 資源。每個範例都會連結至 Google API 探索工具並填入資料，方便您執行範例並查看回應。

如要進一步瞭解如何使用 YouTube Data API 上傳內容，請參閱支援續傳的上傳作業。

總覽

為方便理解，這個頁面中的範例顯示了每個要求的獨特元素，以及處理 Data API 要求 (https://www.googleapis.com/youtube/v3) 的主機的基本網址。若要在範例之外再提出要求，您必須加入完整網址。

以下列要求為例為例：

GET {base-URL}/channels?part=contentDetails
                       &mine=true

這個要求的完整網址如下：

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails
                                                  &mine=true

其中幾項要求會擷取僅供 YouTube 頻道擁有者存取的資料，例如訂閱者清單。這些要求需要頻道擁有者授權 Google API Explorer 代為執行 YouTube Data API 要求。(如要進一步瞭解如何授予私人頻道資料的存取權，請參閱實作 OAuth 2.0 驗證)。連結 APIs Explorer 後，按一下 [使用 OAuth 2.0 授權要求] 按鈕。這個步驟會授權 APIs Explorer 代表擁有者提出要求。您也可以選取授權範圍，以指定 APIs Explorer 可執行的要求類型。

每項要求的回應都是 YouTube 資源的 JSON 表示法。要求中的 part 參數會指定回應中要包含資源的一部分。這個參數可識別應納入回應中的一或多個頂層 (非巢狀) 資源屬性。例如，影片資源的某些部分有：

摘要
內容詳細資料
球員
統計學
狀態

這些部分都是包含巢狀屬性的物件，您可以將其視為 API 伺服器可能 (也可能不會) 擷取的中繼資料欄位群組。因此，part 參數會要求您選取應用程式實際使用的資源元件。詳情請參閱「開始使用 YouTube Data API」。

擷取頻道資訊

這個要求使用 channels.list 方法，擷取已驗證使用者之頻道的詳細資料。

GET {base_URL}/channels?part=contentDetails
                       &mine=true

此要求的回應包含已驗證使用者的頻道 ID 和 contentDetails。contentDetails 包含數個與頻道相關聯的系統產生的播放清單。許多後續要求都需要頻道 ID 或播放清單 ID 之一，因此請務必妥善記錄。

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

上傳影片和系統產生的播放清單

YouTube 會將所有上傳的影片加入與頻道相關聯的播放清單。如要取得已上傳的影片清單，請使用頻道資訊回應的以上回應，透過這個管道查詢傳回的「上傳」播放清單，並使用 playlistItems.list 方法擷取該播放清單中的影片。

在 Google APIs Explorer 中執行下列範例要求之前，請將 {UPLOADS_PLAYLIST_ID} 替換成先前要求的播放清單 ID。

GET {base_URL}/playlistItems?part=contentDetails
                            &playlistId={UPLOADS_PLAYLIST_ID}

請注意，每個傳回項目的 "id" 值都是播放清單項目 ID。播放清單項目的影片 ID 是 contentDetails 區段中的 videoId。

您可以使用上述資訊，從頻道資訊回應中將對應的播放清單 ID 改成，即可擷取使用者最愛的影片、喜歡的影片、觀看記錄或稍後觀看清單。

使用者建立的播放清單

這個要求使用 playlists.list 方法擷取與已驗證頻道相關聯的播放清單。請注意，這項要求「不會」擷取頻道資訊中產生的系統產生的播放清單 (例如上傳項目、手錶記錄等)。只會擷取使用者建立的播放清單。

GET {base_URL}/playlists?part=snippet
                        &mine=true

取得播放清單 ID 後，您就能使用上一節的要求從播放清單擷取項目。

您不必經過驗證，就能要求取得頻道公開播放清單的相關資訊。提交未經驗證的要求時，您必須加入 key 引數，藉此指定提出要求應用程式的專屬 API 金鑰。例如，此要求會擷取與 GoogleDevelopers 頻道相關聯的播放清單。

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

擷取訂閱

subscription 資源可定義 YouTube 使用者 (訂閱者) 與頻道之間的關係。subscriptions.list 方法會根據您在要求中加入的參數，擷取訂閱者至特定頻道或特定使用者的訂閱項目。

頻道訂閱人數

此要求會擷取已驗證頻道的訂閱者清單。

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

使用者訂閱

列出訂閱者 (subscriptions.list) 的相同方法，可用來列出使用者訂閱的頻道。此要求使用 mine 參數來擷取已驗證使用者訂閱的 YouTube 頻道清單。

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

擷取使用者活動

activity 資源包含特定頻道或使用者在 YouTube 上採取的動作相關資訊，例如上傳影片、訂閱頻道等。activities.list 方法會擷取與要求條件相符的管道或使用者相關聯的動作。舉例來說，您可以擷取與特定頻道、訂閱項目或使用者的自訂 YouTube 首頁相關聯的動作。

指定期間內的活動

這項要求會擷取已驗證使用者於 2013 年 4 月採取的所有動作。

GET {base_URL}/activities?part=snippet,contentDetails
                         &mine=true
                         &publishedAfter=2013-04-01T00%3A00%3A00Z
                         &publishedBefore=2013-05-01T00%3A00%3A00Z

首頁活動

這項要求會擷取已驗證使用者的 YouTube 首頁上顯示的自訂活動資訊提供。

GET {base_URL}/activities?part=snippet,contentDetails
                         &home=true

如要擷取 YouTube 影片和頻道的觀看統計資料、熱門指標和客層資訊，請使用 YouTube Analytics API。「API 要求範例」頁面說明如何從 YouTube 數據分析擷取常見的報表。

搜尋

search.list 方法可讓您搜尋符合特定條件的 YouTube 影片、頻道或播放清單。您可以依據影片屬性、關鍵字或主題 (或兩者的組合) 進行搜尋，也可以依據建立日期、觀看次數或評分等因素來排序結果。

與其他 YouTube Data API 要求一樣，search.list 方法會傳回 YouTube 資源的 JSON 表示法。然而，與其他 YouTube 資源不同，搜尋結果並不是具有唯一 ID 的永久性物件。

許多要求會搜尋公開內容，因此不需要進行驗證。在下方示例中，由於只有提供「我的」影片，所以只有第一個需要驗證。提交未經驗證的要求時，您必須加入 key 引數，以指定應用程式專屬的 API 金鑰。

我觀看次數最多的影片

此要求會擷取所有已驗證使用者的影片，並按觀看次數以遞減方式列出。

GET {base_URL}/search?part=snippet
                     &forMine=true
                     &order=viewCount
                     &type=video

嵌入式高畫質影片

此要求會搜尋具備特定屬性的影片，也就是可嵌入其他網站的高畫質影片。結果會依評分遞減排序。

GET {base_URL}/search?part=snippet
                     &order=rating
                     &type=video
                     &videoDefinition=high
                     &videoEmbeddable=true
                     &key={YOUR_API_KEY}

有關特定主題的影片

這項要求會搜尋關鍵字，內容是關於 YouTube 資料 API 的字幕。

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

主題式搜尋

如要搜尋特定主題的影片，建議您使用 Freebase 主題而非關鍵字。YouTube 頻道和影片資源都有 topicDetails 物件，其中包含與資源相關聯的 Freebase 主題 ID 清單。主題式搜尋比關鍵字搜尋更聰明，因為 Freebase 主題代表實際概念或事物的各方面。

如要使用 Freebase 主題進行搜尋，請先使用 Freebase API 擷取主題 ID。這項要求會傳回與 Python 的 Freebase 主題 (主題 ID 為 /m/05z1_) 相關聯的影片。

GET {base_URL}/search?part=snippet
                     &topicId=/m/05z1_
                     &type=video
                     &key={YOUR_API_KEY}

搜尋播放清單或頻道

搜尋範圍不限於影片。你也可以搜尋播放清單或頻道。這個要求會擷取與關鍵字「soccer」相符的播放清單。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

如果您想尋找足球頻道，只要變更 type 參數即可。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

如果您想尋找所有足球相關內容 (頻道、播放清單和影片)，可以使用通用搜尋功能。如果省略 type 參數，該要求會擷取所有類型的內容

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

建立及更新資源

目前為止，所有要求都使用 HTTP GET 方法擷取 YouTube 資料。YouTube Data API 也提供使用 HTTP POST 建立或更新 YouTube 資源的方法，例如影片、播放清單或頻道。下列要求提供範例。

POST 方法包括 Request body，這是所建立或更新資源的 JSON 表示法。您可以使用互動式工具在 Google APIs Explorer 中建立 JSON 表示法。

建立訂閱項目

這項要求可將通過驗證的使用者訂閱 Google Developers 頻道。換句話說，它會建立訂閱資源。

POST {base_URL}/subscriptions?part=snippet
 Request body:
  {
    'snippet': {
      'resourceId': {
        'kind': 'youtube#channel',
        'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' 
       }
     }
  }

建立播放清單

這項要求會建立新的公開播放清單。

POST {base_URL}/playlists?part=snippet
 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

將影片新增至播放清單

建立播放清單後，我們來新增一部影片吧！這項要求會將影片新增至播放清單的開頭 ('position': 0)。

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }