YouTube Data API 可讓您將一般在 YouTube 網站上執行的功能,整合至您的網站或應用程式。以下清單列出您可以使用 API 擷取的各種資源類型。這個 API 也支援插入、更新或刪除這類資源的方法。
本參考指南將說明如何使用 API 執行所有這些作業。本指南會依資源類型整理內容。「資源」代表構成 YouTube 體驗的一部分項目,例如影片、播放清單或訂閱項目。針對每個資源類型,指南會列出一或多個資料表示法,且資源會以 JSON 物件表示。本指南也會針對每種資源類型列出一或多個支援的方法 (LIST
、POST
、DELETE
等),並說明如何在應用程式中使用這些方法。
呼叫 API
下列規定適用於 YouTube Data API 要求:
-
每個要求都必須指定 API 金鑰 (含
key
參數),或提供 OAuth 2.0 權杖。您可以在開發人員控制台的「API 存取權」窗格中取得專案的 API 金鑰。 -
您必須在每次插入、更新及刪除要求時傳送授權權杖。若是擷取已驗證使用者私人資料的請求,您也必須傳送授權權杖。
此外,某些用於擷取資源的 API 方法可能支援需要授權的參數,或可在要求授權時包含額外的中繼資料。舉例來說,如果要求擷取使用者上傳的影片,如果提出要求的使用者獲得授權,該影片就可能包含私人影片。
-
API 支援 OAuth 2.0 驗證通訊協定。您可透過下列其中一種方式提供 OAuth 2.0 權杖:
- 請使用
access_token
查詢參數,例如:?access_token=
oauth2-token
- 請使用以下 HTTP
Authorization
標頭:Authorization: Bearer
oauth2-token
如需在應用程式中實作 OAuth 2.0 驗證的完整操作說明,請參閱驗證指南。
- 請使用
資源類型
活動
activity
資源含有特定頻道或使用者在 YouTube 上所採取動作的相關資訊。活動動態消息所回報的動作包括影片評分、分享影片、將影片標示為最愛、上傳影片等等。每項 activity
資源都會指出動作類型、與動作相關的頻道,以及與動作相關的資源,例如評分或上傳的影片。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /activities |
傳回符合要求條件的管道活動事件清單。例如,您可以擷取與特定管道或使用者頻道相關的事件。 |
insert |
POST /activities |
注意:這個方法已淘汰,我們不再提供支援。 |
字幕
caption
資源代表 YouTube 字幕軌。一個字幕軌只會與一部 YouTube 影片相關聯,
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /captions |
刪除指定的字幕軌。 |
download |
GET /captions/id |
下載字幕軌。除非要求指定 tfmt 參數的值及其原始語言,除非要求指定了 tlang 參數值,否則字幕軌會以原始格式傳回。 |
insert |
POST /captions |
上傳字幕軌。 |
list |
GET /captions |
傳回與特定影片相關聯的字幕軌清單。請注意,API 回應不含實際字幕,而且 captions.download 方法可提供擷取字幕軌的功能。 |
update |
PUT /captions |
更新字幕軌。更新字幕軌時,您可以變更字幕軌的草稿狀態和/或上傳新的字幕檔。 |
頻道橫幅
channelBanner
資源包含的網址,可用來將新上傳的圖片設為頻道的橫幅圖片。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
insert |
POST /channelBanners/insert |
將頻道橫幅圖片上傳至 YouTube。這個方式代表更新頻道橫幅圖片的前兩個步驟:
|
頻道版面
channelSection
資源包含頻道選擇要主打的一組影片相關資訊。舉例來說,版面可以主打頻道最新上傳的影片、熱門上傳內容,或是一或多個播放清單中的影片。
請注意,頻道的版面必須透過瀏覽檢視畫面 (而非動態消息檢視畫面) 顯示內容,頻道版面才會顯示。如要讓頻道在瀏覽檢視畫面中顯示內容,請將指定頻道的 brandingSettings.channel.showBrowseView
屬性設為 true
。
每個頻道最多可以建立 10 個影片櫃。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /channelSections |
刪除頻道版面。 |
insert |
POST /channelSections |
將頻道版面新增至已驗證使用者的頻道。一個頻道最多可以建立 10 個影片櫃。 |
list |
GET /channelSections |
傳回符合 API 要求條件的 channelSection 資源清單。 |
update |
PUT /channelSections |
更新頻道版面。 |
頻道
channel
資源包含 YouTube 頻道的相關資訊。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /channels |
傳回符合要求條件的 0 或多個 channel 資源集合。 |
update |
PUT /channels |
更新頻道的中繼資料。請注意,這個方法目前僅支援更新 channel 資源的 brandingSettings 和 invideoPromotion 物件及其子項屬性。 |
留言串
commentThread
資源包含 YouTube 留言串的相關資訊,其中包含該留言的頂層留言和回覆 (如果有的話)。commentThread
資源可以代表影片或頻道的留言。
頂層留言和回覆實際上都是 commentThread
資源巢狀結構中的 comment
項資源。commentThread
資源不一定包含對註解的所有回覆,如要擷取特定留言的所有回覆,您必須使用 comments.list
方法。另請注意,部分留言沒有回覆。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /commentThreads |
傳回符合 API 要求參數的註解執行緒清單。 |
insert |
POST /commentThreads |
建立新的頂層註解。如要在現有的註解中新增回覆,請改用 comments.insert 方法。 |
留言
comment
資源包含單一 YouTube 留言的相關資訊。comment
資源可代表影片或頻道的留言。此外,留言可以是頂層留言,也可以是頂層留言的回覆。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /comments |
傳回符合 API 要求參數的註解清單。 |
setModerationStatus |
POST /comments/setModerationStatus |
設定一或多則留言的審核狀態。API 要求必須獲得與留言相關的頻道或影片擁有者授權。 |
insert |
POST /comments |
建立現有註解的回覆。注意:如要建立頂層註解,請使用 commentThreads.insert 方法。 |
markAsSpam |
POST /comments/markAsSpam |
注意:這個方法已淘汰,我們不再提供支援。 |
delete |
DELETE /comments |
刪除註解。 |
update |
PUT /comments |
修改註解。 |
指南類別
guideCategory
資源可識別 YouTube 根據頻道內容或其他指標 (例如頻道的熱門程度) 進行演算法指派的類別,這份清單與影片類別類似,差別在於影片上傳者可以指定影片類別,但只有 YouTube 可以指派頻道類別。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /guideCategories |
傳回可與 YouTube 頻道建立關聯的類別清單。 |
I18nLanguages
i18nLanguage
資源可識別 YouTube 網站支援的應用程式語言。應用程式語言也稱為 UI 語言。如果是 YouTube 網站,系統會根據 Google 帳戶設定、瀏覽器語言或 IP 位置自動選取應用程式語言。使用者也可以從 YouTube 網站頁尾手動選取所需的 UI 語言。
每項 i18nLanguage
資源都會識別一組語言代碼和名稱。在呼叫 videoCategories.list
和 guideCategories.list
等 API 方法時,語言代碼可以用作 hl
參數值。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /i18nLanguages |
傳回 YouTube 網站支援的應用程式語言清單。 |
I18nRegions
i18nRegion
資源可識別 YouTube 使用者可將哪些地理區域做為偏好內容地區。內容地區也可稱為內容語言代碼。如果是 YouTube 網站,系統會根據 YouTube 網域或使用者的 IP 位置等經驗法則,自動選取內容地區。使用者也可以從 YouTube 網站頁尾手動選取想觀看的內容區域。
每項 i18nRegion
資源都會標示一個區碼和一個名稱。當您呼叫 search.list
、videos.list
、activities.list
和 videoCategories.list
等 API 方法時,可以使用區碼做為 regionCode
參數的值。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /i18nRegions |
傳回 YouTube 網站支援的內容區域清單。 |
成員
member
資源代表 YouTube 頻道的頻道會員。會員提供定期的金錢支援,並為創作者提供特殊福利。舉例來說,創作者啟用會員專屬聊天室後,會員就能聊天。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /members |
列出頻道的成員 (舊稱「贊助」)。API 要求必須由頻道擁有者授權。 |
會員等級
membershipsLevel
資源會針對授權 API 要求的創作者,識別定價等級。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /membershipsLevels |
傳回授權 API 要求的管道擁有的 0 或多個 membershipsLevel 資源集合。等級會以隱含顯示順序傳回。 |
播放清單項目
playlistItem
資源可識別播放清單中的其他資源,例如影片。此外,playlistItem
資源也會包含該資源在播放清單中使用資源時的專屬資源詳細資料。
YouTube 也會使用播放清單來識別頻道的上傳影片清單,而清單中的每個 playlistItem
都代表一部上傳的影片。您可以從特定頻道的 channel resource
擷取該清單的播放清單 ID。接著,您可以使用 playlistItems.list
方法至清單。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /playlistItems |
刪除播放清單項目。 |
insert |
POST /playlistItems |
將資源加入播放清單。 |
list |
GET /playlistItems |
傳回符合 API 要求參數的播放清單項目集合。您可以擷取指定播放清單中的所有播放清單項目,也可以按照專屬 ID 擷取一或多個播放清單項目。 |
update |
PUT /playlistItems |
修改播放清單項目。舉例來說,您可以更新項目在播放清單中的位置。 |
播放清單
playlist
資源代表 YouTube 播放清單。播放清單是影片合輯,可依序觀看及分享。一個播放清單最多可包含 200 部影片,YouTube 對每位使用者建立的播放清單數量沒有限制。根據預設,其他使用者都能看到播放清單,但播放清單可以是公開或私人。
YouTube 也會使用播放清單來辨識頻道中的特殊影片集合,例如:
- 已上傳的影片
- 評分 (喜歡) 的影片
- 觀看記錄
- 稍後觀看。
channel resource
擷取每份清單的播放清單 ID。接著,您可以使用
playlistItems.list
方法擷取任何這些清單。您也可以呼叫 playlistItems.insert
和 playlistItems.delete
方法,在這些清單中新增或移除項目。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /playlists |
刪除播放清單。 |
list |
GET /playlists |
傳回符合 API 要求參數的一組播放清單。舉例來說,您可以擷取已驗證使用者擁有的所有播放清單,也可以依據專屬 ID 擷取一或多個播放清單。 |
insert |
POST /playlists |
建立播放清單。 |
update |
PUT /playlists |
修改播放清單。舉例來說,你可以變更播放清單的標題、說明或隱私權狀態。 |
搜尋
搜尋結果包含的 YouTube 影片、頻道或播放清單的相關資訊,符合 API 要求中指定的搜尋參數。雖然搜尋結果指向可以明確識別的資源 (例如影片),卻沒有專屬的永久資料。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /search |
傳回一組搜尋結果,這些結果符合 API 要求中指定的查詢參數。根據預設,搜尋結果集可識別相符的 video 、channel 和 playlist 資源,但您也可以將查詢設定為僅擷取特定類型的資源。 |
個訂閱項目
subscription
資源包含 YouTube 使用者訂閱項目的相關資訊。當其他使用者將新影片加入頻道時,或是其他使用者在 YouTube 上採取至少一項動作 (例如上傳影片、為影片評分或對影片留言) 時,訂閱就會通知使用者。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /subscriptions |
刪除訂閱項目。 |
insert |
POST /subscriptions |
為已驗證使用者的頻道新增訂閱項目。 |
list |
GET /subscriptions |
傳回符合 API 要求條件的訂閱資源。 |
縮圖
thumbnail
資源會識別與資源相關聯的不同縮圖大小。請注意縮圖圖片特性:
- 資源的
snippet.thumbnails
屬性是識別該資源可用縮圖的物件。 thumbnail
資源包含一系列的物件。每個物件的名稱 (default
、medium
、high
等) 是指縮圖尺寸。- 不同類型的資源可以支援不同的縮圖大小。
- 不同的資源類型可能會為同名的縮圖定義不同大小。舉例來說,
video
資源的default
縮圖通常是 120 x 90 像素,channel
資源的default
縮圖通常為 88 x 88 像素。 - 視原始圖片的解析度或上傳到 YouTube 的內容而定,相同類型的資源可能仍會有不同的縮圖圖片大小。舉例來說,HD 高畫質影片支援的縮圖解析度可能會比非 HD 高畫質影片更高。
- 每個包含縮圖尺寸相關資訊的物件都有
width
屬性和height
屬性。不過,該圖片可能不會傳回寬度和高度屬性。 - 如果上傳的縮圖不符合規定的尺寸,系統會將圖片大小調整為合適的大小,而不變更長寬比。圖片不會經過裁剪,但可能會含有黑邊,以便正確顯示尺寸。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
set |
POST /thumbnails/set |
將自訂影片縮圖上傳至 YouTube 並設定成影片。 |
VideoAbuseReportReasons
videoAbuseReportReason
資源包含影片遭檢舉含有不當內容的原因資訊。當應用程式呼叫 videos.reportAbuse
方法檢舉濫用影片時,該要求會使用 videoAbuseReportReason
資源中的資訊識別檢舉影片的原因。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /videoAbuseReportReasons |
擷取可用於檢舉違規影片的原因清單。 |
影片類別
videoCategory
資源可識別已上傳影片或與上傳的影片相關聯的類別。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /videoCategories |
傳回可與 YouTube 影片相關聯的類別清單。 |
影片
video
資源代表 YouTube 影片。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
insert |
POST /videos |
將影片上傳到 YouTube,並視需要設定影片的中繼資料。 |
list |
GET /videos |
傳回符合 API 要求參數的影片清單。 |
delete |
DELETE /videos |
刪除 YouTube 影片。 |
update |
PUT /videos |
更新影片的中繼資料。 |
rate |
POST /videos/rate |
為影片加上喜歡或不喜歡的評分,或移除影片的評分。 |
getRating |
GET /videos/getRating |
擷取授權使用者針對特定影片清單提供的評分。 |
reportAbuse |
POST /videos/reportAbuse |
檢舉含有不當內容的影片。 |
浮水印
watermark
資源可識別在特定頻道的影片播放期間顯示的圖片。您也可以指定要與圖片連結的目標頻道,同時根據時間詳細資料決定浮水印出現在影片播放期間的時機,以及顯示的時間長度。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
set |
POST /watermarks/set |
將浮水印圖片上傳至 YouTube 並為其設定頻道。 |
unset |
POST /watermarks/unset |
刪除頻道的浮水印圖片。 |