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

API 要求範例

本頁說明傳送至 YouTube Data API 的要求範例。您可以使用 YouTube Data API 擷取及操控 YouTube 資源，例如影片、頻道和播放清單。每個範例都會連結至並填入 Google APIs Explorer，讓您可以執行範例並查看回應。

想瞭解如何使用 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 APIs Explorer，代表其執行 YouTube Data API 要求。(如要進一步瞭解如何授權私人管道資料的存取權，請參閱執行 OAuth 2.0 驗證)。連結至 APIs Explorer 後，按一下「使用 OAuth 2.0 授權要求」按鈕。這個步驟會授權 APIs Explorer 代表擁有者提出要求。您也可以選取授權範圍，指定 API Explorer 可執行的要求類型。

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

摘要
contentDetails
球員
統計資料
狀態

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

擷取頻道資訊

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

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

這項要求的回應會包含已驗證使用者頻道的頻道 ID 和 contentDetails。contentDetails 包括多個系統為該頻道產生的播放清單。後續的許多要求都需要有頻道 ID 或其中一個播放清單 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" 值都是它的 playlistItem 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 的永久物件。

許多要求搜尋公開的內容，因此不需要驗證。在下列範例中，只有第一個需要驗證，因為其特別要求輸入「my」影片。提交未經驗證的要求時，您必須加入 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 Data 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}

搜尋播放清單或頻道

搜尋範圍不限於影片，以及搜尋播放清單或頻道。這項要求會擷取與關鍵字「足球」相符的播放清單。

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 表示法。

建立訂閱項目

這項要求會將已驗證的使用者訂閱 GoogleDevelopers 頻道。換句話說，它會建立訂閱資源。

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
      }
   }