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 的狀態為「開啟」。

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

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

  6. 熟悉 JSON (JavaScript 物件標記法) 資料格式的核心概念。JSON 是一種與語言無關的通用資料格式，能夠以簡單的文字表示任意資料結構。詳情請參閱 json.org 網站。

資源和資源類型

資源是具有專屬 ID 的個別資料實體。下表說明可與 API 互動的各種資源類型。

資源
activity 包含特定使用者在 YouTube 網站上採取了哪些動作的相關資訊。在活動資訊提供中回報的使用者動作，包括對影片進行評分、分享影片、將影片標示為最愛，以及發布頻道公告等等。
channel 包含單一 YouTube 頻道的相關資訊。
channelBanner 識別一個網址，以便將新上傳的圖片設為頻道的橫幅圖片。
channelSection 提供頻道選擇精選的一組影片的資訊。舉例來說，版面可能會顯示某頻道的最新上傳內容、最熱門的上傳影片，或是一或多個播放清單的影片。
guideCategory 根據 YouTube 的內容或其他指標 (例如熱門程度)，找出 YouTube 頻道所屬的類別。YouTube 使用者可透過引導類別整理頻道，以便使用者輕鬆找到需要的內容。儘管頻道可能與一或多個指南類別相關聯，但無法保證可涵蓋任何類別。
i18nLanguage 表示 YouTube 網站支援的應用程式語言。應用程式語言也稱為 UI 語言。
i18nRegion 指出可供 YouTube 使用者選擇偏好的內容地區。內容地區也稱為內容語言代碼。
playlist 代表單一 YouTube 播放清單。播放清單是可以依序播放的影片，而且可以與其他使用者分享。
playlistItem 識別播放清單中的資源，例如影片。playlistItem 資源也提供了詳細資料，說明如何在播放清單中使用內含的資源。
search result 包含與 API 要求中指定的搜尋參數相符的 YouTube 影片、頻道或播放清單的相關資訊。雖然搜尋結果指向了可識別的專屬資源，例如影片，但它沒有專屬的持續性資料。
subscription 包含 YouTube 使用者訂閱的相關資訊。訂閱會在頻道新增影片，或其他使用者在 YouTube 上採取多種行動時 (例如上傳影片、為影片評分，或對影片發表留言) 通知使用者。
thumbnail 識別與資源相關聯的縮圖。
video 代表一部 YouTube 影片。
videoCategory 識別已上傳的影片，或與上傳影片相關的類別。
watermark 識別特定頻道影片播放時要顯示的圖片。頻道擁有者也可以指定連結圖片的目標頻道，以及決定影片播放期間浮水印顯示時間以及顯示時間長短的時間詳細資訊。

請注意，在多數情況下，資源包含其他資源的參照。例如，playlistItem 資源的 snippet.resourceId.videoId 屬性可識別影片資源，其中包含影片的完整資訊。例如，搜尋結果包含 videoId、playlistId 或 channelId 屬性，以識別特定影片、播放清單或頻道資源。

支援作業

下表列出 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 回應。例如，如果您想擷取播放清單中每個項目的播放清單項目編號、標題和位置，您可以使用以下的值：

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

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

部分要求範例

下列範例說明如何使用 part 和 fields 參數，以確保 API 回應僅包含應用程式使用的資料：

  1. 範例 1 傳回影片資源，其中包含四個部分以及 kind 和 etag 屬性。
  2. 範例 2 會傳回包含兩個部分的影片資源，以及 kind 和 etag 屬性。
  3. 範例 3 會傳回包含兩個部分但不含 kind 和 etag 屬性的影片資源。
  4. 範例 4 傳回影片資源，其中包含兩個部分，但排除 snippet 物件中的 kind 和 etag，以及部分巢狀屬性。
範例 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

ETags 是 HTTP 通訊協定的標準元件，可讓應用程式參照特定 API 資源的特定版本。該資源可以是整個資訊提供，或是資訊提供中的項目。這項功能支援以下使用情境：

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

    Google API 的用戶端程式庫支援 ETag。舉例來說，JavaScript 用戶端程式庫支援許可清單，納入包含 If-Match 和 If-None-Match 的允許要求標頭。許可清單可讓一般瀏覽器進行快取，如果資源的 ETag 沒有變更，就可透過瀏覽器快取提供資源。但 Obj-C 用戶端不支援 ETag。

  • 防止意外覆寫變更 – ETag 可協助確保多個 API 用戶端在無意間覆寫彼此所做的變更。更新或刪除資源時，您的應用程式可以指定資源的 ETag。如果 ETag 與這項資源的最新版本不相符，API 要求就會失敗。

在應用程式中使用 ETag 有幾個好處：

  • API 可以更迅速地回應快取但未變更的資源要求，進而降低延遲時間並減少頻寬用量。
  • 您的應用程式不會不小心以其他 API 用戶端資源來覆寫資源變更。

Google APIs Client Library for JavaScript 支援 If-Match 和 If-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)