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 使用者找到所需內容。頻道可與一或多個節目表類別建立關聯，但不保證會出現在任何節目表類別中。
i18nLanguage 識別 YouTube 網站支援的應用程式語言。應用程式語言也稱為使用者介面語言。
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 個單位。
  • 上傳影片的費用為 100 單位。

「API 要求的配額費用」表格會顯示各項 API 方法的配額費用。請記住這些規則，即可估算應用程式每天在配額範圍內可傳送的要求數量。

部分資源

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

這項 API 支援兩個要求參數 (詳情請見下節)，可讓您識別應納入 API 回應的資源屬性。

  • part 參數會識別應為資源傳回的屬性群組。
  • fields 參數會篩選 API 回應，只傳回所要求資源部分中的特定屬性。

如何使用 part 參數

對於任何會擷取或傳回資源的 API 要求，part 參數都是必要參數。這個參數會識別一或多個應納入 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 參數值也必須經過網址編碼。為方便閱讀，本文中的範例會省略編碼。

部分要求範例

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

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

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

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

    Google API 的用戶端程式庫對 ETag 的支援程度不一。舉例來說，JavaScript 用戶端程式庫透過允許的要求標頭許可清單支援 ETag，其中包含 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 要求標頭，因此 ETags 可以在一般瀏覽器快取環境中運作。

使用 gzip

啟用 gzip 壓縮功能，也能減少每個 API 回應占用的頻寬。雖然應用程式需要額外的 CPU 時間來解壓縮 API 回應，但通常消耗較少網路資源的好處會大於這項成本。

如要接收以 gzip 編碼的回應，請務必完成以下兩個動作：

  • 將 Accept-Encoding HTTP 要求標頭設為 gzip。
  • 修改使用者代理程式，使其包含 gzip 字串。

以下 HTTP 標頭範例說明啟用 gzip 壓縮時的這些要求：

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