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

YouTube Data API 總覽

簡介

本文件可協助開發人員編寫與 YouTube 互動的應用程式。並說明 YouTube 和 API 本身的基本概念。並概略介紹 API 支援的不同功能。

事前準備

您必須擁有 Google 帳戶，才能存取 Google API 控制台、要求 API 金鑰，並註冊應用程式。
在 Google Developers Console 中建立專案並取得授權憑證，以便應用程式提交 API 要求。
建立專案後，請確認 YouTube Data API 是您的應用程式註冊使用的其中一項服務：
1. 前往 API 控制台，然後選取您剛才註冊的專案。
2. 前往已啟用的 API 頁面。在 API 清單中，確認 YouTube Data API v3 的狀態已設為「ON」。
如果您的應用程式會使用任何需要使用者授權的 API 方法，請參閱驗證指南，瞭解如何執行 OAuth 2.0 授權。
選取用戶端程式庫簡化 API 導入程序。
熟悉 JSON (JavaScript 物件標記法) 資料格式的核心概念。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`	包含 YouTube 影片、頻道或播放清單的相關資訊，且這些內容與 API 要求中指定的搜尋參數相符。雖然搜尋結果指向可明確識別的資源 (例如影片)，但沒有永久性資料。
`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 控制台的「配額」頁面中查看配額用量。

注意：如果達到配額上限，可以按照下列步驟申請更多配額：完成配額擴充功能要求表單。

計算配額用量

Google 會指定每個要求的費用，計算配額用量。不同類型的負載平衡各項作業的配額費用也不同。例如：

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

「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 會傳回包含四個部分的影片資源，以及 kind 和 etag 屬性。
範例 2 會傳回包含兩個部分以及 kind 和 etag 屬性的影片資源。
範例 3 會傳回包含兩個部分但排除 kind 和 etag 屬性的影片資源。
範例 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 並未變更，資源即可透過瀏覽器快取提供。另一方面，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)