YouTube Data API 總覽

簡介

本文件可協助開發人員編寫與 YouTube 互動的應用程式。其介紹 YouTube 和 API 本身的基本概念。同時也概述 API 支援的各種函式。

事前準備

  1. 您必須擁有 Google 帳戶,才能存取 Google API 控制台、要求 API 金鑰並註冊應用程式。

  2. Google Developers Console 中建立專案並取得授權憑證,以便應用程式提交 API 要求。

  3. 建立專案後,請確認 YouTube Data API 是該應用程式註冊使用的服務之一:

    1. 前往 API 控制台,然後選取您剛註冊的專案。
    2. 前往「已啟用的 API」頁面。 在 API 清單中,確認 YouTube Data API v3 的狀態為「ON」(開啟)

  4. 如果您的應用程式會使用任何需要使用者授權的 API 方法,請參閱驗證指南,瞭解如何執行 OAuth 2.0 授權。

  5. 選取用戶端程式庫來簡化 API 導入作業。

  6. 熟悉 JSON (JavaScript Object Notation) 資料格式的核心概念。JSON 是一種與語言無關的常用資料格式,可透過簡單的文字方式呈現任意資料結構。詳情請參閱 json.org 網站。

資源和資源類型

資源是具有專屬 ID 的個別資料實體。下表說明您可以透過 API 與哪些資源類型互動。

資源
activity 包含特定使用者在 YouTube 網站上所採取動作的相關資訊。在活動動態消息中回報的使用者動作包括:影片評分、分享影片、將影片標示為最愛,以及發布頻道公告等等。
channel 包含單一 YouTube 頻道的相關資訊。
channelBanner 識別用於將新上傳的圖片設為頻道橫幅圖片的網址。
channelSection 含有頻道選擇要主打的一系列影片資訊。舉例來說,版面可以主打頻道最新上傳的影片、最熱門的上傳內容,或是一或多個播放清單的影片。
guideCategory 指出 YouTube 根據頻道內容或其他指標 (例如熱門程度) 與頻道建立關聯的類別。指南類別旨在整理頻道,方便 YouTube 使用者找到想看的內容。雖然頻道可以與一或多個節目類別建立關聯,但不保證屬於任何節目類別。
i18nLanguage 識別 YouTube 網站支援的應用程式語言,應用程式語言也稱為 UI 語言。
i18nRegion 指定 YouTube 使用者可以選取做為偏好內容地區的地理區域。內容地區也可稱為內容語言代碼。
playlist 代表單一 YouTube 播放清單。播放清單是影片合輯,可依序觀看及分享。
playlistItem 用於識別屬於播放清單的資源,例如影片。listItem 資源中也包含詳細資料,說明播放清單如何使用內含的資源。
search result 根據 API 要求中指定的搜尋參數,列出相符的 YouTube 影片、頻道或播放清單的相關資訊。雖然搜尋結果指向可以明確識別的資源 (例如影片),卻沒有專屬的永久資料。
subscription 內含 YouTube 使用者訂閱的相關資訊。當其他使用者將新影片加入頻道時,或是其他使用者在 YouTube 上採取至少一項動作 (例如上傳影片、為影片評分或對影片留言) 時,訂閱就會通知使用者。
thumbnail 識別與資源相關聯的縮圖。
video 代表單一 YouTube 影片。
videoCategory 識別已上傳影片或與上傳影片相關聯的類別。
watermark 識別指定頻道影片播放期間顯示的圖片。頻道擁有者也能指定圖片連結的目標頻道,以及詳細的時間詳細資料,以便決定浮水印出現在影片播放期間及顯示的時間長度。

請注意,在許多情況下,資源會包含其他資源的參照。舉例來說,playlistItem 資源的 snippet.resourceId.videoId 屬性可識別影片資源,而此資源包含影片的完整資訊。例如,搜尋結果包含可識別特定影片、播放清單或頻道資源的 videoIdplaylistIdchannelId 屬性。

支援作業

下表列出了 API 最常支援的方法。有些資源也支援其他方法,以執行更具體於這些資源的函式。舉例來說,videos.rate 方法會將使用者評分與影片建立關聯,thumbnails.set 方法則會將影片縮圖上傳至 YouTube 並連結至影片。

作業套件
list 擷取 (GET) 零或多個資源的清單。
insert 建立 (POST) 新資源。
update 修改 (PUT) 現有資源以反映您要求中的資料。
delete 移除 (DELETE) 特定資源。

API 目前支援列出每個支援資源類型的方法,同時也支援許多資源的寫入作業。

下表列出不同資源類型支援的作業。插入、更新或刪除資源的作業一律需要使用者授權。在某些情況下,list 方法支援已授權和未經授權的要求,其中未授權的要求只會擷取公開資料,而已獲得授權的要求也可以擷取目前驗證使用者的相關資訊或私人資料。

支援的作業
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

配額使用量

YouTube Data API 會使用配額,確保開發人員能按預期使用服務,且不會建立應用程式來不公平地降低服務品質,或限制他人存取應用程式。所有 API 要求 (包含無效的要求) 都會產生至少一分的配額費用。您可以在 API Console 中找到應用程式可用的配額。

啟用 YouTube Data API 的專案預設每日分配配額為 10,000 個單位,這個配額足以應付絕大多數的 API 使用者。預設配額隨時可能變動,可協助我們根據 API 使用者更有意義的方式分配配額,並調度基礎架構資源。您可以在 API 控制台的「配額」頁面中,查看配額用量。

注意:如果您已達到配額限制,可以填寫 YouTube API 服務的配額延長申請表單,申請額外配額。

計算配額用量

Google 會分配每項要求的費用,藉此計算您的配額用量。不同類型的作業有不同的配額費用。例如:

  • 擷取資源清單 (頻道、影片、播放清單) 的讀取作業 (通常費用為 1 個單位)。
  • 建立、更新或刪除資源的寫入作業通常會需要 50 個單位。
  • 搜尋要求會需要 100 個單位。
  • 影片上傳需要 1600 個單位。

API 要求的配額費用表格會顯示各個 API 方法的配額費用。考量這些規則後,您就可以估計應用程式每天可在不超出配額的情況下傳送的要求數量。

部分資源

這個 API 允許且實際上需要擷取部分資源,讓應用程式避免傳輸、剖析及儲存不需要的資料。這種做法也能確保 API 以更有效率的方式使用網路、CPU 和記憶體資源。

此 API 支援兩個要求參數,這在以下各節有詳細說明,可讓您識別應包含在 API 回應中的資源屬性。

  • part 參數會識別應針對資源傳回的屬性群組。
  • fields 參數會篩選 API 回應,僅傳回要求資源部分的特定屬性。

如何使用 part 參數

part 參數是所有擷取或傳回資源的 API 要求的必要參數。這個參數會指定 API 回應中應包含的一或多個頂層 (非巢狀) 資源屬性。舉例來說,video 資源包含下列部分:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

這些部分都是包含巢狀屬性的物件,您可以將這些物件視為 API 伺服器可能會 (或可能不會) 擷取的中繼資料欄位群組。因此,part 參數會要求您選取應用程式實際使用的資源元件。這項規定有兩個主要目的:

  • 也能避免 API 伺服器擷取應用程式未使用的中繼資料欄位,藉此減少延遲時間。
  • 藉此減少 (或消除) 應用程式可擷取的非必要資料量,進而降低頻寬用量。

隨著資源不斷增加,這些優勢只會越來越長,因為應用程式不會要求其不支援的新屬性。

如何使用 fields 參數

fields 參數會篩選 API 回應,其中包含 part 參數值中識別的資源部分,因此回應只包含一組特定欄位。fields 參數可讓您移除 API 回應中的巢狀屬性,進一步降低頻寬用量。(part 參數無法用於篩選回應中的巢狀屬性)。

以下規則說明 fields 參數值 (以 XPath 語法大致為基礎) 支援的語法:

  • 請使用逗號分隔的清單 (fields=a,b),選取多個欄位。
  • 使用星號 (fields=*) 做為萬用字元來識別所有欄位。
  • 使用括號 (fields=a(b,c)) 即可指定要包含在 API 回應中的一組巢狀屬性。
  • 請使用正斜線 (fields=a/b) 來識別巢狀屬性。

實際上,這些規則通常會允許多個不同的 fields 參數值擷取相同的 API 回應。舉例來說,如要擷取播放清單中每個項目的播放清單項目 ID、標題和位置,可以使用下列任一值:

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

附註:和所有查詢參數值一樣,fields 參數值也必須使用網址編碼。為方便閱讀,本文中的範例會省略編碼。

部分要求範例

以下範例說明如何使用 partfields 參數,確保 API 回應僅包含應用程式使用的資料:

  1. 範例 1 會傳回影片資源,其中包含四個部分,以及 kindetag 屬性。
  2. 範例 2 會傳回影片資源,其中包含兩個部分,以及 kindetag 屬性。
  3. 範例 3 傳回的影片資源包含兩個部分,但排除 kindetag 屬性。
  4. 範例 4 傳回的影片資源,其中包含兩個部分,但排除 kindetag,以及資源 snippet 物件中的部分巢狀屬性。
範例 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status
Description: This example retrieves a video resource and identifies several resource parts that should be included in the API response. API response:
{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "contentDetails": { "duration": "PT15M51S", "aspectRatio": "RATIO_16_9" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" }, "status": { "uploadStatus": "STATUS_PROCESSED", "privacyStatus": "PRIVACY_PUBLIC" } } ] }
範例 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics
Description: This example modifies the part parameter value so that the contentDetails and status properties are not included in the response. API response:
{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
範例 3
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics&fields=items(id,snippet,statistics)
Description: This example adds the fields parameter to remove all kind and etag properties from the API response. API response:
{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
範例 4
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics
Description: This example modifies the fields parameter from example 3 so that in the API response, each video resource's snippet object only includes the channelId, title, and categoryId properties. API response:
{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }

最佳化效能

使用 ETag

ETagsHTTP 通訊協定的標準部分,可讓應用程式參照特定版本的 API 資源。資源可以是整個動態饋給,也可以是該動態饋給中的項目。這項功能支援下列用途:

  • 快取和條件式擷取:應用程式可快取 API 資源及其 ETag。之後,當應用程式再次要求儲存的資源時,就會指定與該資源相關聯的 ETag。如果資源有變,API 會傳回修改過的資源,以及與該資源版本相關聯的 ETag。如果資源未變更,API 會傳回 HTTP 304 回應 (Not Modified),表示資源未變更。應用程式可透過這種方式提供快取資源,藉此縮短延遲時間和頻寬用量。

    Google API 的用戶端程式庫支援 ETag 並不相同。舉例來說,JavaScript 用戶端程式庫可透過許可清單中的允許要求標頭 (包含 If-MatchIf-None-Match) 支援 ETag。許可清單允許一般瀏覽器快取執行,以便在資源的 ETag 尚未變更時,透過瀏覽器快取提供資源。另一方面,Obj-C 用戶端不支援 ETag。

  • 防止意外覆寫變更:ETag 可協助確保多個 API 用戶端不會意外覆寫彼此的變更。更新或刪除資源時,應用程式可指定資源的 ETag。如果 ETag 與該項資源的最新版本不符,API 要求就會失敗。

在應用程式中使用 ETag 有幾項好處:

  • API 能更快回應已快取但尚未變更資源的要求,以縮短延遲時間並減少頻寬用量。
  • 應用程式不會意外覆寫來自其他 API 用戶端的資源變更。

Google APIs Client Library for JavaScript 支援 If-MatchIf-None-Match HTTP 要求標頭,因此 ETag 可在一般瀏覽器快取環境內運作。

使用 gzip

您還可以啟用 gzip 壓縮功能,藉此降低每個 API 回應所需的頻寬。雖然應用程式需要額外的 CPU 作業時間才能解壓縮 API 回應,但使用較少網路資源的好處通常遠超過成本。

如要接收以 gzip 編碼的回應,您必須執行下列兩項操作:

  • Accept-Encoding HTTP 要求標頭設為 gzip
  • 請修改使用者代理程式,加入 gzip 字串。

下列 HTTP 標頭範例示範了啟用 gzip 壓縮功能的相關規定:

Accept-Encoding: gzip
User-Agent: my program (gzip)