YouTube Data API 可讓您將在 YouTube 網站上執行的功能,整合到自己的網站或應用程式中。以下清單列出您可以使用 API 擷取的不同資源類型。這個 API 也支援插入、更新或刪除許多這些資源的方法。
這份參考指南說明如何使用 API 執行上述所有操作。本指南是依據資源類型進行分類。資源代表構成 YouTube 體驗的項目類型,例如影片、播放清單或訂閱項目。針對每個資源類型,指南會列出一或多個資料表示法,資源則以 JSON 物件表示。這份指南也針對每種資源類型列出一或多個支援的方法 (LIST
、POST
、DELETE
等),並說明如何在應用程式中使用這些方法。
呼叫 API
下列規定適用於 YouTube Data API 要求:
-
每個要求都必須指定 API 金鑰 (含
key
參數) 或提供 OAuth 2.0 權杖。您可以在 Developer Console 的「API Access」(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 |
更新字幕軌。更新字幕軌時,您可以變更曲目的草稿狀態和/或上傳該曲目的新字幕檔。 |
ChannelBanners
channelBanner
資源包含網址,用於將新上傳的圖片設為頻道橫幅圖片。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
insert |
POST /channelBanners/insert |
將頻道橫幅圖片上傳到 YouTube。這個方法代表在三個步驟中更新頻道橫幅圖片的前兩個步驟:
|
ChannelSections
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 |
傳回符合要求條件的零或多個 channel 資源集合。 |
update |
PUT /channels |
更新頻道的中繼資料。請注意,這個方法目前僅支援更新 channel 資源的 brandingSettings 和 invideoPromotion 物件及其子項屬性。 |
CommentThreads
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 |
修改註解。 |
GuideCategories
guideCategory
資源可識別 YouTube 系統根據頻道內容或指標 (例如頻道的熱門程度) 等指標指派的類別。這份清單與影片類別類似,差別在於影片上傳者可以指派影片類別,但只有 YouTube 可以指派頻道類別。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /guideCategories |
傳回可與 YouTube 頻道建立關聯的類別清單。 |
I18nLanguages
i18nLanguage
資源可識別 YouTube 網站支援的應用程式語言。應用程式語言也可以稱為 UI 語言。在 YouTube 網站上,系統可能會根據 Google 帳戶設定、瀏覽器語言或 IP 位置,自動選取應用程式語言。使用者也可以在 YouTube 網站頁尾手動選取偏好的使用者介面語言。
每項 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 要求必須獲得頻道擁有者的授權。 |
MembershipsLevels
membershipsLevel
資源會指出授權 API 要求創作者的定價等級。
方法 | HTTP 要求 | 說明 |
---|---|---|
相對於 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /membershipsLevels |
傳回零或多個 membershipsLevel 資源的集合,這些資源是由授權 API 要求的管道擁有。等級會以隱含顯示順序傳回。 |
PlaylistItems
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 |
修改播放清單。例如,您可以變更播放清單的標題、說明或隱私設定。 |
搜尋
搜尋結果會包含與 API 要求中指定的搜尋參數相符的 YouTube 影片、頻道或播放清單的相關資訊。雖然搜尋結果指向的是明確識別資源 (例如影片),但其並沒有持續性資料。
方法 | 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 |
擷取可用於檢舉不當影片的原因清單。 |
VideoCategories
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 |
刪除頻道的浮水印圖片。 |