YouTube Data API 總覽

簡介

本文適用於想編寫與 YouTube 互動應用程式的開發人員。說明 YouTube 和 API 的基本概念，並概略介紹 API 支援的不同函式。

事前準備

  1. 您需要Google 帳戶才能存取 Google Cloud 控制台、要求 API 金鑰及註冊應用程式。

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

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

    1. 前往 Cloud 控制台，選取剛註冊的專案。
    2. 前往「已啟用 API」頁面。 確認 YouTube Data API 位於已啟用 API 的清單中。如果尚未啟用，請開啟 API 程式庫並啟用 API。

  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 網站支援的應用程式語言。應用程式語言也稱為 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 要求 (包括無效要求) 都會耗用至少 1 點配額。您可以在 API Console 中查看應用程式可用的配額。

啟用 YouTube Data API 的專案，預設配額為每天 100 次 search.list 呼叫、100 次 videos.insert 呼叫，以及所有其他端點加總 10,000 個單位。預設配額可能會變更，有助於我們調整配額分配，並擴充基礎架構，為 API 使用者提供更有意義的服務。您可以在 API 控制台的「配額」頁面查看配額用量。

注意：如果達到配額上限，請填寫 YouTube API 服務的配額擴充申請表單，要求提高配額。

計算配額用量

Google 會為每項要求指派費用，藉此計算配額用量。不同類型的作業有不同的配額費用。例如：

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

「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

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

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

    Google API 的用戶端程式庫對 ETag 的支援程度不一。舉例來說，JavaScript 用戶端程式庫透過允許的要求標頭的白名單 (包括 If-Match 和 If-None-Match)，支援 ETag。白名單允許正常的瀏覽器快取，因此如果資源的 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)