本頁面列出 YouTube Data API (v3) 的異動內容和說明文件更新。訂閱這份變更記錄。
2024 年 10 月 30 日
API 現在可識別含有逼真變造或合成 (A/S) 內容的影片。進一步瞭解與 A/S 內容相關的 YouTube 政策。
以下列舉幾種 A/S 內容的例子:
- 內容中真實人物的言論與動作非本人實際作為
- 變造真實事件或地點的影片片段
- 生成看似真實但從未發生的場景
如要指出影片是否包含 A/S 內容,請設定 status.containsSyntheticMedia
屬性。您可以在呼叫 videos.insert
或 videos.update
方法時設定這個屬性。如果已設為此值,系統會在 video
資源中傳回該屬性。
2024 年 4 月 30 日
注意:這是淘汰公告。
這次更新的修改如下:
API 不再支援插入或擷取頻道討論串的功能。這項異動與 YouTube 網站所提供的功能一致,該網站不支援對頻道發布留言功能。
2024 年 3 月 13 日
注意:這是一則淘汰功能的公告。
這次更新的修改如下:
captions.insert
和 captions.update
方法的 sync
參數已淘汰。YouTube 將於 2024 年 4 月 12 日停止支援參數。
為配合這項異動,開發人員在插入或更新字幕軌時必須提供時間資訊,否則上傳會失敗。
2024 年 3 月 12 日
這次更新的修改如下:
captions
資源的說明文件已更新,指出 snippet.name
欄位的長度上限為 150 個字元。如果音軌名稱過長,API 會傳回 nameTooLong
錯誤。
2024 年 3 月 7 日
注意:這是淘汰公告。
channel
資源屬性 brandingSettings.channel.moderateComments
已淘汰。YouTube 將從 2024 年 3 月 7 日起停止支援這個參數。
2024 年 1 月 31 日
這次更新的修改如下:
channels.list
方法的新 forHandle
參數可讓您指定 YouTube 帳號,藉此擷取頻道相關資訊。
2023 年 11 月 9 日
由於 videoId
資源並未透過 API 呼叫傳回,因此已移除 Comments
下所有 videoId
資源的參照。
2023 年 9 月 12 日
注意:這是淘汰公告。
comments.markAsSpam
方法已淘汰好幾年。YouTube 不支援這種方法,且無法再透過 API 支援。
所有參照 comments.markAsSpam
方法的文件都會新增淘汰通知。
2023 年 8 月 22 日
search.list
方法現在支援 videoPaidProductPlacement
參數。這個參數可讓您篩選搜尋結果,只顯示創作者認定為付費宣傳內容的影片。
2023 年 8 月 18 日
video
資源的 liveStreamingDetails.concurrentViewers
定義已更新,指出 YouTube Data API 傳回的同時觀看人數可能與透過 YouTube 數據分析處理後的非垃圾郵件同時觀看人數不同。YouTube 說明中心提供關於直播指標的詳細資訊。
2023 年 8 月 7 日
如2023 年 6 月 12 日宣布,search.list
方法的 relatedToVideoId
參數已淘汰。我們已不再支援該參數,且已從 API 說明文件中移除對該參數的參照。
2023 年 6 月 28 日
thumbnails.set 方法現在支援 uploadRateLimitExceeded
錯誤,表示頻道在過去 24 小時內上傳過多縮圖,請稍後再試。
2023 年 6 月 12 日
注意:這是一則停用功能的公告。
search.list 方法的 relatedToVideoId
參數已淘汰。YouTube 將自 2023 年 8 月 7 日起停止支援這項參數。
目前在 search.list
方法的說明文件中加入淘汰通知。此參數將於 2023 年 8 月 7 日當天或之後從 search.list
說明文件中完全移除。
此外,API 實作指南已移除示範如何擷取相關影片的範例。
2022 年 8 月 22 日
修正 video.statistics 欄位的型別註解,從未簽署的長整數改為字串。
2022 年 8 月 5 日
YouTube 已變更字幕 ID 的產生方式,包括將新的字幕 ID 指派給所有字幕軌。對於儲存 caption_id
值的應用程式,這項變更可能會造成回溯不相容的變更,但不會影響未儲存 caption_id
值的應用程式。
在 2022 年 12 月 1 日期間,captions.list
、captions.update
、captions.download
和 captions.delete
方法將同時支援新舊字幕軌 ID。不過,自 2022 年 12 月 1 日起,YouTube 將停止支援舊的字幕軌 ID。屆時,如果使用舊的字幕軌 ID 呼叫任何這些 API 方法,都會導致 captionNotFound
錯誤。
為因應這項異動,建議您在 2022 年 12 月 1 日前完全替換所有已儲存的字幕軌資料。也就是說,對於儲存字幕音軌資料的任何影片,您應該刪除目前儲存的資料,然後呼叫 captions.list
方法,擷取影片目前的字幕音軌組合,並按照平常方式將資料儲存在 API 回應中。
2022 年 7 月 12 日
《YouTube API 服務條款》已更新。詳情請參閱《YouTube API 服務條款 - 修訂版本記錄》。
2022 年 4 月 27 日
videos.insert
方法說明已更新,指出上傳影片的最大檔案大小已從 128 GB 提高至 256 GB。
2022 年 4 月 8 日
subscriptions.list
方法的 myRecentSubscribers
和 mySubscribers
參數定義已更新,以注意 API 傳回的訂閱人數上限可能受到限制。這項變更代表說明文件修正,而不是 API 行為的變更。
2021 年 12 月 15 日
如同 2021 年 11 月 18 日的公告所述,我們在整個 YouTube 平台上將影片的「不喜歡」次數設為私人資料,因此 video
資源的 statistics.dislikeCount
屬性現已設為私人資料。
歡迎前往 YouTube 官方網誌,進一步瞭解這項異動。
2021 年 11 月 18 日
由於影片不喜歡人數在整個 YouTube 平台上設為不公開,video
資源的 statistics.dislikeCount
屬性將從 2021 年 12 月 13 日起設為不公開。這表示只有在影片擁有者驗證 API 要求時,只有 videos.list
端點的 API 回應才會包含該屬性。
videos.rate
端點不受這項異動影響。
如果開發人員不公開顯示不喜歡次數,但仍需要 API 用戶端的不喜歡次數,可以申請加入許可清單,以便取得豁免。如要申請豁免,請務必填寫這份申請表單。
歡迎前往 YouTube 官方網誌,進一步瞭解這項異動。
2021 年 7 月 2 日
注意:這是一則淘汰功能的公告。
commentThreads.update
端點已淘汰,不再受支援。
這個端點重複了其他 API 端點提供的功能。您可以改為呼叫 comments.update
commentThreads
資源,請對 commentThreads.list
方法進行第二次呼叫。
2021 年 7 月 1 日
凡是使用 YouTube API 服務的開發人員,都必須完成 API 法規遵循稽核,才能獲得超過預設配額 (10,000 個單位) 的授權。到目前為止,法規遵循稽核程序以及額外配額單位配額的要求都是由開發人員填寫並提交 YouTube API 服務 - 稽核與配額擴充表單。
為清楚說明這些程序,並進一步滿足開發人員使用 API 服務的需求,我們將添加三份新表單和指南,協助您完成這些表單:
- 經過稽核的開發人員要求表單:如果開發人員已通過 API 法規遵循稽核,可以填寫並提交這份簡短的表單,申請展延配額。
- 申訴表單:如果 API 專案未通過法規遵循稽核 (或已拒絕提高配額單位),開發人員可以填寫並提交這份表單。
- 控製表單變更:開發人員或代為執行 API 用戶端的任何一方,如果與 API 專案相關聯的控制權異動 (例如透過股票買賣、併購或其他形式的公司交易) 變更,請務必填寫並提交這份表單。這可讓 YouTube 的 API 團隊更新記錄、稽核新 API 專案的用途法規遵循情況,並驗證開發人員目前的配額分配。
每份新表單都會告知我們您預期的 YouTube API 使用方式,以便為您提供更完善的協助。
詳情請參閱新版 API 法規遵循稽核指南。
2021 年 5 月 12 日
注意:這是一則淘汰功能的公告。
本次更新涵蓋下列 API 異動:
-
channel
資源的contentDetails.relatedPlaylists.favorites
屬性已淘汰。如2016 年 4 月 28 日修訂版本記錄所述,最愛影片功能已停用多年。在此更新之前,如果 API 用戶端嘗試將影片加入不存在的最愛播放清單,API 仍會建立新的播放清單。日後,系統將不會在這種情況下建立播放清單,且 API 會傳回錯誤。凡是嘗試新增、修改或刪除項目來修改最愛的播放清單,也都會在先前的公告中淘汰,且隨時可能開始傳回錯誤。
-
下列
channel
資源屬性已淘汰。YouTube 工作室使用者介面和 YouTube 均不支援這些屬性。因此,這些 API 也不再透過 API 提供支援。brandingSettings.channel.defaultTab
brandingSettings.channel.featuredChannelsTitle
brandingSettings.channel.featuredChannelsUrls[]
brandingSettings.channel.profileColor
brandingSettings.channel.showBrowseView
brandingSettings.channel.showRelatedChannels
所有屬性都已從
channel
資源表示法中移除,且其定義也已從資源的屬性清單中移除。此外,與這些屬性相關的錯誤也已從方法的專屬說明文件中移除。 -
下列
channelSection
資源屬性已淘汰。這些屬性已不再支援 YouTube 工作室使用者介面和 YouTube 平台。因此,我們也已停止透過 API 支援這些功能。snippet.style
snippet.defaultLanguage
snippet.localized.title
localizations
localizations.(key)
localizations.(key).title
targeting
targeting.languages[]
targeting.regions[]
targeting.countries[]
與這項變更相關的是,由於
channelSection.list
方法支援的功能已淘汰,因此channelSection.list
方法的hl
參數也已淘汰。所有屬性均已從
channelSection
資源表示法中移除,其定義也已從資源的屬性清單中移除。此外,我們已從特定方法的說明文件中移除與這些屬性相關的錯誤。 -
對於
channelSection
資源的snippet.type
屬性,下列值已遭淘汰。YouTube 頻道頁面不支援這些值,因此也無法再透過 API 支援這些值。likedPlaylists
likes
postedPlaylists
postedVideos
recentActivity
recentPosts
-
playlist
資源的snippet.tags[]
屬性已淘汰。YouTube 不再支援這項屬性,因此該 API 已不再支援這項屬性。
2021 年 2 月 9 日
playlistItem
資源支援兩個新屬性:
snippet.videoOwnerChannelId
屬性可用來識別上傳播放清單影片的頻道 ID。snippet.videoOwnerChannelTitle
屬性可用來識別上傳播放清單影片的頻道名稱。
2021 年 1 月 28 日
這次更新的修改如下:
-
playlistItems.delete
、playlistItems.insert
、playlistItems.list
、playlistItems.update
、playlists.delete
、playlists.list
和playlists.update
方法都支援新的playlistOperationUnsupported
錯誤。如果要求嘗試執行特定播放清單不允許的作業,就會發生錯誤。例如,使用者無法從上傳的影片播放清單中刪除影片,也無法刪除播放清單本身。無論何種情況,這項錯誤都會傳回
400
HTTP 回應碼 (無效要求)。 -
已從說明文件中移除
playlistItems.list
方法的watchHistoryNotAccessible
和watchLaterNotAccessible
錯誤。雖然使用者的觀看記錄和稍後觀看清單確實無法透過 API 存取,但 API 不會傳回這些特定錯誤。
2020 年 10 月 15 日
開發人員政策新增了兩個部分:
- 新版第 III.E.4.i 節提供更多資訊,說明透過 YouTube 嵌入式播放器收集及傳送的資料。在使用者與播放器互動以表示播放意圖之前,您透過任何 YouTube 嵌入式播放器傳送給我們的任何使用者資料,均由您負責。您可以將「自動播放」設為「false」,限制在使用者與播放器互動前,與 YouTube 分享的資料。
- 新的第 III.E.4.j 節是用來檢查內容,確認內容是否屬於兒童專屬 (MFK) 狀態,然後再將其嵌入網站和應用程式。您必須瞭解 API 用戶端嵌入的影片是否為兒童專屬,並據此處理從嵌入式播放器收集的資料。因此,您必須先使用 YouTube Data API 服務查看內容狀態,才能透過任何 YouTube 嵌入式播放器將內容嵌入 API 用戶端。
全新的尋找影片的 MadeForKids 狀態指南說明如何使用 YouTube Data API 服務查詢影片的 MFK 狀態。
為配合這些變更,嵌入播放器參數說明文件中新增了提醒,說明如果啟用自動播放功能,則使用者在未與播放器互動的情況下播放影片,系統就會在載入網頁時收集與分享資料。
2020 年 10 月 8 日
這項更新包含有關 channel
資源的三項小幅變更:
- 如果是新建立的頻道,用來識別頻道的縮圖圖片的
snippet.thumbnails
物件可能是空白,且最多需要一天才能填入資料。 statistics.videoCount
屬性只會反映頻道的公開影片數量 (包括擁有者在內)。這種行為與 YouTube 網站上顯示的計數一致。- 如果管道關鍵字超過 500 個字元的上限,或包含未經轉義的引號 (
"
),系統可能會截斷這些關鍵字。請注意,500 個字元的限制並非針對個別關鍵字,而是針對所有關鍵字的總長度。在 YouTube 網站上,這種行為與運作方式一致。
2020 年 9 月 9 日
注意:這是淘汰公告。
本次更新涵蓋下列 API 變更。所有變更都會自這則公告的公告日期 2020 年 9 月 9 日當天或之後生效。因此,開發人員不應再使用下列任一 API 功能。
-
下列 API 資源、方法、參數和資源屬性已淘汰,並會在本公告發布當天或之後停止運作:
- 下列
channel
資源屬性:statistics.commentCount
屬性brandingSettings.image
物件及其所有子項屬性brandingSettings.hints
清單和其所有子項屬性
channels.list
方法的categoryId
篩選器參數guideCategories
資源和guideCategories.list
方法
- 下列
-
如果 API 要求將
managedByMe
參數設為true
,channels.list
方法的 API 回應就不會再包含prevPageToken
屬性。這項變更不會影響其他channels.list
要求的prevPageToken
屬性,也不會影響任何要求的nextPageToken
屬性。 -
channel
資源的contentDetails.relatedPlaylists.watchLater
和contentDetails.relatedPlaylists.watchHistory
屬性已於 2016 年 8 月 11 日宣布淘汰。此外,playlistItems.insert
方法和playlistItems.delete
方法對這些播放清單的支援現已完全淘汰,這兩項屬性也已從說明文件中移除。 -
我們已從說明文件中移除
channels.list
方法的mySubscribers
參數 (該參數已於 2013 年 7 月 30 日宣布為淘汰)。使用subscriptions.list
方法及其mySubscribers
參數,擷取已驗證使用者頻道的訂閱者清單。 -
channel
資源的invideoPromotion
物件及其所有子項屬性已於 2017 年 11 月 27 日宣布淘汰,並已從說明文件中移除。
2020 年 7 月 29 日
我們移除了與 part
參數相關聯的額外費用,以簡化 API 要求的收費配額程序。此後即刻生效,我們只會針對呼叫的方法收取基本費用。請參閱這篇文章,進一步瞭解精簡的配額。
這項變更的影響,大多數 API 呼叫的配額費用都較低,而某些 API 呼叫的費用仍維持不變。本次異動不會增加任何 API 呼叫的費用。整體而言,這可能會影響您的配額;您可以在 Google Cloud 控制台查看這些配額,
強烈建議所有開發人員都完成專案的法規遵循稽核,確保可以持續存取 YouTube API 服務。
這項修訂歷史記錄項目最初發布於 2020 年 7 月 20 日。
2020 年 7 月 28 日
凡是在 2020 年 7 月 28 日以後建立且未經驗證的 API 專案,透過 videos.insert
端點上傳的影片都會設為私人觀看模式。如要解除這項限制,每個專案都必須接受稽核,確認符合《服務條款》的規定。
創作者如果使用未經驗證的 API 用戶端上傳影片,系統會寄送電子郵件通知,說明影片遭鎖定為私人影片,而只要使用官方或經過稽核的用戶端,即可避免遭到限制。
在 2020 年 7 月 28 日前建立的 API 專案目前不會受到這項異動影響。不過,我們強烈建議所有開發人員為自己的專案完成法規遵循稽核,確保能持續存取 YouTube API 服務。
2020 年 7 月 21 日
[Updated July 28, 2020.] 這個修訂版本記錄項目中參照的說明文件更新已於 2020 年 7 月 28 日重新發布。
昨天,我們發布了與收費配額程序相關的文件更新內容。不過,由於發生不可預期的情況,配額異動尚未生效。因此,為了確保準確性,我們已將說明文件恢復原狀。為避免造成混淆,說明變更內容的修訂版本記錄項目已遭移除,並會在近期內重新發布。
2020 年 7 月 7 日
注意:這是一則停用功能的公告。
videos.insert
方法的 autoLevels
和 stabilize
參數現已淘汰,這兩個參數已從說明文件中移除。系統會忽略這些值,不會影響新上傳影片的處理方式。
2020 年 6 月 15 日
新版《遵守 YouTube 開發人員政策》指南提供了相關指引和範例,可協助您確保 API 用戶端符合 YouTube API 服務條款和政策 (API 服務條款) 的特定規範。
本指南將深入分析 YouTube 如何強制執行《API 服務條款》的特定部分,但不會取代任何現有文件。本指南將解答開發人員在 API 法規遵循稽核期間最常詢問的問題。我們希望能協助您瞭解我們如何解讀及落實政策,進而簡化功能開發程序。
2020 年 6 月 4 日
注意:以下是先前淘汰的公告內容。
頻道公告功能現已完全淘汰。這項異動最初是在 2020 年 4 月 17 日宣布,目前已生效。因此,系統不再支援 activities.insert
方法,activities.list
方法也不再傳回頻道公告。詳情請參閱 YouTube 說明中心。
2020 年 4 月 17 日
注意:這是一則淘汰功能的公告。
YouTube 即將淘汰頻道公告功能。因此,activities.insert
方法將遭到淘汰,activities.list
方法也會停止傳回管道公告。這些變更會在 2020 年 5 月 18 日當天或之後在 API 中生效。詳情請參閱 YouTube 說明中心。
2020 年 3 月 31 日
這次更新的修改如下:
-
新資源和方法
-
新的
member
資源代表 YouTube 頻道的頻道會員。會員可以定期為創作者提供金錢支援,並享有特別福利。舉例來說,創作者啟用聊天室的會員專屬模式時,會員就能進行聊天。這個資源會取代
sponsor
資源,後者已在 YouTube Live Streaming API 的說明中有所說明。sponsor
資源現已淘汰,API 用戶端應更新對sponsors.list
方法的呼叫,改為使用members.list
方法。 -
新的
membershipsLevel
資源會指出由授權 API 要求的創作者管理的價格等級。membershipsLevels.list
方法會擷取創作者的所有會員等級清單。
-
2020 年 1 月 10 日
這個 API 現在能夠識別兒童導向內容,YouTube 因此稱之為「兒童專屬」。前往 YouTube 說明中心,進一步瞭解「兒童專屬」的內容。
channel
和 video
資源支援兩項新屬性,可讓內容創作者和觀眾識別為兒童打造的內容:
-
內容創作者可透過
selfDeclaredMadeForKids
屬性,指定頻道或影片是否為兒童專屬。
如果是管道,則可在呼叫channels.update
方法時設定這個屬性。對於影片,您可以在呼叫videos.insert
或videos.update
方法時設定此屬性。
請注意,只有在頻道擁有者授權 API 要求時,含有channel
或video
資源的 API 回應才會包含這項屬性。 -
madeForKids
屬性可讓任何使用者擷取頻道或影片的「兒童專屬」狀態。舉例來說,狀態可根據selfDeclaredMadeForKids
屬性的值決定。如要進一步瞭解如何設定頻道、影片或直播的目標觀眾,請參閱 YouTube 說明中心。
我們也更新了《YouTube API 服務條款》和《開發人員政策》。如需更多資訊,請參閱 YouTube API 服務條款 - 修訂版本歷史記錄。《YouTube API 服務條款》和《開發人員政策》的異動將於太平洋時間 2020 年 1 月 10 日生效。
2019 年 9 月 10 日
API 參考資料說明文件已更新,反映 YouTube 和 API 回應中訂閱者計數的方式異動。因此,如果訂閱人數超過 1,000 人,YouTube Data API 服務傳回的訂閱人數會四捨五入至三位有效數字。這項異動會影響 channel
資源的 statistics.subscriberCount 屬性。
注意:即使使用者傳送已授權的自身頻道相關資料要求,這項變更也會影響這個屬性值。頻道擁有者還是可以在 YouTube 工作室中查看確切的訂閱人數。
舉例來說,如果頻道有 123,456 名訂閱者,statistics.subscriberCount
屬性就會包含 123000
值。
下表列出 API 回應中訂閱人數的捨入方式,以及其他公開顯示的 YouTube 使用者介面中縮寫的例子:
訂閱人數範例 | YouTube Data API | 公開顯示的 YouTube UI |
---|---|---|
1,234 人 | 1230 | 1230 |
12,345 人 | 12300 | 1.23 萬 |
123,456 | 123000 | 12.3 萬 |
1,234,567 人 | 1230000 | 123 萬 |
12,345,678 | 12300000 | 1230 萬 |
123,456,789 | 123000000 | 1.23 億 |
2019 年 4 月 4 日
這次更新的修改如下:
-
更新 API 參考資料文件,進一步解釋每種方法的常見用途,並透過 APIs Explorer 小工具提供動態的高品質程式碼範例。如需範例,請參閱
channels.list
方法的說明文件。說明 API 方法的頁面現在有兩個新元素:-
API Explorer 小工具可讓您選取授權範圍、輸入範例參數和屬性值,然後傳送實際的 API 要求,並查看實際的 API 回應。小工具也提供全螢幕檢視畫面,其中顯示完整的程式碼範例,可根據您輸入的範圍和值動態更新。
-
「常見用途」一節將說明本頁所述方法的一或多個常見用途。舉例來說,您可以呼叫
channels.list
方法來擷取特定管道的相關資料,或是擷取目前使用者頻道的相關資料。您可以使用該部分的連結,根據用途在 APIs Explorer 中填入範例值,或開啟已填入這些值的全螢幕 API 多層檢視。這些變更旨在方便您查看直接適用的程式碼範例,適合您在自己的應用程式中實作的用途。
目前支援 Java、JavaScript、PHP、Python 和 curl 的程式碼範例。
-
-
程式碼範例工具也更新了,新的 UI 提供上述所有相同的功能。透過該工具,您可以探索不同方法的用途、將值載入 APIs Explorer,以及開啟全螢幕 API Explorer,取得 Java、JavaScript、PHP 和 Python 語言的程式碼範例。
隨著這項變更,我們移除了先前列出 Java、JavaScript、PHP 和 Python 相關程式碼範例的網頁。
-
Java、JavaScript、PHP 和 Python 的快速入門指南已更新。修訂版指南將說明如何使用 API 金鑰和 OAuth 2.0 用戶端 ID 分別執行兩個範例,並使用 APIs Explorer 中的程式碼範例。
請注意,上述變更會取代 2017 年加入 API 說明文件的交互式工具。
2018 年 7 月 9 日
這次更新的修改如下:
-
channel
資源的snippet.thumbnails
屬性定義已更新,指出在應用程式中顯示縮圖時,程式碼應使用 API 回應中傳回的圖片網址。舉例來說,應用程式不應在 API 回應中傳回的網址中使用http
網域,而應使用https
網域。自 2018 年 7 月起,頻道縮圖網址只能在
https
網域使用 (這也是網址在 API 回應中顯示的方式)。在此之後,如果應用程式嘗試從http
網域載入 YouTube 圖片,您可能會看到應用程式毀損的圖片。 -
注意:這是淘汰公告。
video
資源的recordingDetails.location.altitude
屬性已淘汰。我們不保證影片會傳回這個屬性的值。同樣地,即使 API 要求嘗試設定該屬性的值,系統仍可能不會儲存傳入的資料。
2018 年 6 月 22 日
《實作指南》(原稱「實作與遷移」指南) 已更新,移除從第 2 版 API 遷移至 v3 API 的操作說明。此外,針對自第 3 版 API 中淘汰的功能 (例如最愛影片),我們也移除了相關說明。
2017 年 11 月 27 日
這次更新的修改如下:
-
注意:這是一則淘汰功能的公告。
YouTube 將停止支援「精選影片」和「精選網站」功能,這兩項功能在 API 中透過
channel
資源的invideoPromotion
物件提供支援。因此,該物件 (包括所有子項資源) 已淘汰。您仍可在 2017 年 12 月 14 日前擷取及設定
invideoPromotion
資料。付款週期結束後:- 如果在呼叫
channels.list
時嘗試擷取invideoPromotion
部分,將會傳回空白的invideoPromotion
,或不會傳回任何invideoPromotion
資料。 - 至少在 2018 年 5 月 27 日前,呼叫
channels.update
時嘗試更新invideoPromotion
資料時,系統會傳回成功回應,但會視為無操作,也就是不會實際執行更新。
2018 年 5 月 27 日後,這些要求可能會傳回錯誤訊息,指出
invalidPromotion
是無效的部分。 - 如果在呼叫
2017 年 11 月 16 日
這次更新的修改如下:
-
互動式程式碼片段工具現在支援 Node.js 程式碼範例。您也可以在幾乎所有 API 方法 (例如
channels.list
方法) 的說明文件中查看這些範例。這些可自訂的範例旨在提供 Node.js 應用程式的特定用途起始點。這項功能與 Node.js 快速入門指南中的程式碼類似。不過,範例包含一些公用程式函式,這些函式並不會出現在快速入門導覽課程中:
removeEmptyParameters
函式會使用與 API 要求參數相對應的鍵/值組合清單,並移除沒有值的參數。createResource
函式會使用與 API 資源中屬性相對應的鍵/值組合清單。然後將屬性轉換為可用於insert
和update
作業的 JSON 物件。以下範例顯示一組屬性名稱和值,以及程式碼為這些屬性建立的 JSON 物件:# Key-value pairs: {'id': 'ABC123', 'snippet.title': 'Resource title', 'snippet.description': 'Resource description', 'status.privacyStatus': 'private'} # JSON object: { 'id': 'ABC123', 'snippet': { 'title': 'Resource title', 'description': 'Resource description', }, 'status': { 'privacyStatus': 'private' } }
所有這些範例都設計為下載並在本機執行。詳情請參閱程式碼片段工具操作說明中在本機執行完整程式碼範例的先決條件。
2017 年 10 月 25 日
這次更新的修改如下:
-
互動式程式碼片段工具中的 Python 程式碼範例已更新為使用
google-auth
和google-auth-oauthlib
程式庫,而非已淘汰的oauth2client
程式庫。除了這項變更之外,這項工具現在也為已安裝的 Python 應用程式和 Python 網頁伺服器應用程式提供完整程式碼範例,這兩者使用略有不同的授權流程。如何查看完整範例 (以及這項變更):
- 前往互動式程式碼片段工具或任何 API 方法 (例如
channels.list
方法) 的說明文件。 - 按一下程式碼範例上方的
Python
分頁標籤。 - 點選分頁上方的切換按鈕,即可從查看摘要切換至完整樣本。
- 分頁現在應會顯示使用
InstalledAppFlow
授權流程的完整程式碼範例。範例上方的說明介紹了這個做法,也可以連結至網路伺服器應用程式的範例。 - 點選連結即可切換至網路伺服器範例。該範例使用 Flask 網路應用程式架構和不同的授權流程。
上述所有範例都設計為在本機下載並執行。如要執行範例,請參閱程式碼片段工具操作說明,在本機執行完整程式碼範例。
- 前往互動式程式碼片段工具或任何 API 方法 (例如
2017 年 8 月 29 日
這次更新的修改如下:
- 我們更新了
search.list
方法forContentOwner
參數的定義,提醒您如果該參數設為true
,則type
參數必須設為video
。 - 我們更新了
search.list
方法regionCode
參數的定義,以闡明此參數會將搜尋結果限制為可在特定區域內觀看的影片。 - YouTube 已更新品牌標誌和圖示。您可以前往品牌宣傳指南頁面下載新的「由 YouTube 開發」標誌。該頁面也會顯示其他新的 YouTube 標誌和圖示,你可以前往 YouTube 品牌網站下載。
2017 年 7 月 24 日
這次更新的修改如下:
- 我們推出了適用於 iOS 的全新 YouTube Data API 快速入門指南。本指南說明如何在以 Objective-C 或 Swift 編寫的簡易 iOS 應用程式中使用 YouTube Data API。
- YouTube Data API 的互動式程式碼片段工具現在提供了一些說明文件,說明這項工具的部分功能:
- 執行 API 要求
- 切換程式碼片段和完整程式碼範例
- 使用樣板函式
- 正在載入現有資源 (用於更新方法)
注意:這項工具也嵌入 API 方法的 API 參考說明文件 (範例)。
2017 年 6 月 1 日
這次更新的修改如下:
-
注意:這是淘汰公告。
下列
video
資源屬性即將淘汰。雖然系統會持續支援這些屬性,但無法保證影片會在 2017 年 12 月 1 日前持續傳回這些屬性的值。同樣地,在該日期之前,設定這些屬性值的videos.insert
和videos.update
要求不會產生錯誤,但可能不會儲存傳入的資料。
2017 年 5 月 17 日
這次更新的修改如下:
-
API 參考說明文件經過更新,讓程式碼片段更普及且更具互動性。說明 API 方法 (例如
channels.list
或videos.rate
) 的頁面現在提供互動式工具,可讓您查看及自訂 Java、JavaScript、PHP、Python、Ruby、Apps Script 和 Go 的程式碼片段。針對任何方法,這項工具會顯示一或多個用途的程式碼片段,每個用途都會說明呼叫該方法的常用方式。舉例來說,您可以呼叫
channels.list
方法,擷取特定頻道或目前使用者頻道的相關資料。您也可以與程式碼範例互動:
-
修改參數和屬性值,程式碼片段就會動態更新,反映您提供的值。
-
切換程式碼片段和完整範例。程式碼片段顯示呼叫 API 方法的部分。完整範例包含該程式碼片段,以及用於授權及傳送要求的固定程式碼。您可以複製完整範例,並透過指令列或本機網路伺服器執行。
-
按一下按鈕即可執行要求。(如要執行要求,您必須授權工具代您呼叫 API)。
請注意,這項工具已取代可用頁面上的 API Explorer。(每個頁面都會顯示連結,方便您在 API Explorer 中載入正在處理的要求)。
-
-
Data API 程式碼片段工具也已更新為新版 UI,提供上述所有功能。這個頁面提供的主要新功能如下:
- 支援寫入資料的 API 要求。
- 支援 Java 範例。
- 更彈性且全面的範本程式碼,可授權使用者並建構 API 要求。
2017 年 4 月 27 日
這次更新的修改如下:
- 新的快速入門指南會說明如何設定簡單的應用程式來提出 YouTube Data API 要求。目前的指南適用於 Android、Apps Script、Go、Java、JavaScript、Node.js、PHP、Python 和 Ruby。
2017 年 3 月 30 日
這次更新的修改如下:
channel
資源的新topicDetails.topicCategories[]
屬性包含描述頻道內容的 Wikipedia 網址清單。這些網址對應至資源的topicDetails.topicIds[]
屬性中傳回的主題 ID。playlistItem
資源的新contentDetails.videoPublishedAt
屬性會指出影片發布至 YouTube 的時間。資源已包含snippet.publishedAt
屬性,表示該項目加入播放清單的時間。- 與
channel
資源一樣,video
資源現在會傳回topicDetails.topicCategories[]
屬性,其中包含描述影片內容的 Wikipedia 網址清單。對於video
資源,網址會對應至資源topicDetails.relevantTopicIds[]
屬性中傳回的主題 ID。 video
資源的新contentDetails.contentRating.mpaatRating
屬性可識別美國電影協會 (Motion Picture Association of America) 為電影預告片或預覽片給予的分級。
2017 年 2 月 27 日
如我們在 2016 年 8 月 11 日的公告所述,YouTube 已經將支援的主題 ID 清單變更為已收錄的清單。您可以在 channel
和 video
資源的 topicDetails
屬性,以及 search.list
方法的 topicId
參數中找到支援主題 ID 的完整清單。
請注意,收錄清單內容有幾項異動:
- 下列主題已新增為
Society
的子主題:名稱 主題 ID 公司行號 /m/09s1f
健康狀態 /m/0kt51
軍事 /m/01h6rj
政治 /m/05qt0
宗教 /m/06bvp
- 已移除「
Animated cartoon
」主題,該主題之前為Entertainment
的子項。 Children's music
主題 (先前為Music
的子項) 已遭到移除。
這項變更的結果是,與影片相關的主題現在一律會透過 video
資源的 topicDetails.relevantTopicIds[]
屬性值傳回。
2016 年 11 月 29 日
這次更新的修改如下:
-
我們將於 2017 年 2 月 10 日開始,對主題 ID 清單做出三項小幅變更:
Professional wrestling
類別先前是Sports
類別的子項,現在則是Entertainment
的子項。TV shows
類別是Entertainment
的子項,是新增的類別。Health
類別 (先前為Lifestyle
的子項) 已遭到移除。
此外,還有幾個父項類別 (
Entertainment
、Gaming
、Lifestyle
、Music
和Sports
)。所有與子類別相關聯的影片 (例如Tennis
) 也會與父項類別 (Sports
) 建立關聯。
2016 年 11 月 10 日
這次更新的修改如下:
-
正如我們在 2016 年 8 月 11 日首次宣布,淘汰 Freebase 和 Freebase API 需要與主題 ID 相關的數項變更。主題 ID 可識別與
channel
和video
資源相關聯的主題,您也可以使用topicId
搜尋參數尋找與特定主題相關的頻道或影片。自 2017 年 2 月 10 日起,YouTube 會開始傳回一組一小部分的主題 ID,而不是目前所傳回更為精細的主題 ID。此外,請注意,頻道和影片不一定會與任何主題建立關聯,這與目前的 API 行為一致。
為讓您能為這些變更做好 API 用戶端的準備,我們已更新下列 API 參數和屬性的定義,列出之後會支援的主題 ID。請注意,所有屬性的類別清單都相同。
channel
資源的topicDetails.topicIds[]
屬性。video
資源的topicDetails.relevantTopicIds[]
屬性。search.list
方法的topicId
參數。
-
注意:這是一則停用功能的公告。
下列屬性即將淘汰:
channel
資源的topicDetails.topicIds[]
屬性。這項資源將於 2017 年 11 月 10 日停用。video
資源的topicDetails.relevantTopicIds[]
屬性。這項資源的支援期限為 2017 年 11 月 10 日。video
資源的topicDetails.topicIds[]
屬性。2017 年 2 月 10 日後,這個屬性不會包含任何值。(在該日期之後,topicDetails.relevantTopicIds[]
屬性值會標示與影片相關的所有主題)。
-
由於 Freebase 已淘汰,說明文件已移除「使用 Freebase 主題進行搜尋」指南。該指南提供程式碼範例,說明應用程式如何與 Freebase API 搭配運作。
此外,我們也從
search.list
方法的說明文件中移除數個與主題 ID 相關的程式碼範例。
2016 年 11 月 2 日
這次更新的修改如下:
-
新屬性和參數
-
video
資源包含多個新屬性:-
player.embedHtml
屬性包含<iframe>
標記,可用於嵌入播放影片的播放器。新的player.embedHeight
和player.embedWidth
屬性可用來識別嵌入式播放器的尺寸。只有在 API 要求為至少一個maxHeight
或maxWidth
參數指定值時,才會傳回這些屬性。這兩個新參數的說明會在本修訂歷史記錄項目的後續部分。 -
新的
hasCustomThumbnail
屬性會指出影片上傳者是否已提供影片的自訂縮圖。請注意,只有影片上傳者才能看到這項屬性。 -
新版
fpbRatingReasons[]
會指出影片獲得 FPB (南非) 分級的原因。 -
新的
mcstRating
會指出影片在越南獲得的分級。
-
-
videos.list
方法支援兩個新參數:maxHeight
和maxWidth
。擷取video
資源中的player
部分時,您可以使用參數,也可以同時使用兩者。根據預設,
player.embedHtml
屬性中傳回的<iframe>
高度為 360 像素。寬度會調整為符合影片的顯示比例,確保內嵌播放器不會在影片周圍顯示黑邊。舉例來說,如果影片長寬比為 16:9,播放器的寬度就會是 640 像素。透過新參數,您可以指定嵌入程式碼應使用應用程式版面配置適用的高度和/或寬度,而非預設尺寸。API 伺服器會視情況調整播放器尺寸,確保內嵌播放器沒有影片框架顯示黑邊。請注意,這兩個參數都會指定嵌入式播放器的尺寸上限。因此,如果同時指定兩個參數,一個維度仍可能小於該維度允許的上限。
舉例來說,假設影片的長寬比為 16:9。因此,如果未設定
maxHeight
或maxWidth
參數,player.embedHtml
代碼就會包含 640x360 播放器。- 如果
maxHeight
參數設為720
,且未設定maxWidth
參數,API 就會傳回 1280x720 播放器。 - 如果
maxWidth
參數設為960
,且未設定maxHeight
參數,API 就會傳回 960x540 播放器。 - 如果
maxWidth
參數設為960
,且maxHeight
參數設為450
,API 就會傳回 800x450 播放器。
如上所述,新的
player.embedHeight
和player.embedWidth
屬性可用來識別玩家尺寸。 - 如果
-
-
現有方法、屬性和參數更新
-
channelSection
資源說明已更新,指出頻道在未設定指定目標資料的情況下,最多可建立 10 個貨架,如果設定指定目標資料,則最多可建立 100 個貨架。此外,我們更新了
channelSection
資源的targeting
屬性,反映只能透過 API 設定指定目標選項。如果透過 YouTube 網站的使用者介面修改頻道版面,指定目標選項就會刪除。 -
i18nLanguage
資源的snippet.name
屬性定義已修正,以反映該值代表的語言名稱,因為該名稱是使用i18nLanguage.list
方法的hl
參數指定的語言所寫。 -
playlistItem
資源的contentDetails.note
屬性已更新,指出屬性值的長度上限為 280 個半形字元。 -
playlistItem
資源的contentDetails.startAt
和contentDetails.endAt
屬性已淘汰。如果playlistItems.insert
或playlistItems.update
要求中設定這些欄位,系統就會忽略這些欄位。 -
playlistItems.delete
和playlistItems.update
方法現在支援onBehalfOfContentOwner
參數,其他幾種方法已經支援此參數。使用該方法的要求也必須透過可提供https://www.googleapis.com/auth/youtubepartner
範圍存取權的權杖進行授權。 -
search.list
方法的publishedBefore
和publishedAfter
參數都已更新,以表示參數值是包含範圍。舉例來說,如果設定了publishedBefore
參數,API 會傳回指定時間之前「或」建立的資源。 -
video
資源的contentDetails.contentRating.grfilmRating
屬性支援三個額外值:grfilmK12
、grfilmK15
和grfilmK18
。 -
videos.insert
方法說明已更新,指出上傳影片的檔案大小上限已從 64 GB 提高至 128 GB。
-
-
新增及更新的錯誤
-
這個 API 支援下列新的錯誤:
錯誤類型 錯誤詳情 說明 forbidden (403)
homeParameterDeprecated
activities.list
方法會傳回這項錯誤,表示無法透過這個 API 取得使用者的首頁活動資料。如果您在未經授權的要求中將home
參數設為true
,就可能發生這項錯誤。invalidValue (400)
invalidContentDetails
playlistItems.insert
方法會傳回這個錯誤,表示要求中的contentDetails
物件無效。發生這項錯誤的其中一個原因是contentDetails.note
欄位長度超過 280 個字元。forbidden (403)
watchHistoryNotAccessible
playlistItems.list
方法會傳回此錯誤,表示要求嘗試擷取「觀看記錄」播放清單項目,但無法使用 API 擷取這些項目。forbidden (403)
watchLaterNotAccessible
playlistItems.list
方法會傳回這項錯誤,表示要求嘗試擷取「稍後觀看」播放清單項目,但無法使用 API 擷取這些項目。badRequest (400)
uploadLimitExceeded
videos.insert
方法會傳回這項錯誤,表示頻道已超過可上傳的影片數量。forbidden (403)
forbiddenEmbedSetting
videos.update
方法會傳回這個錯誤,表示 API 要求嘗試為影片設定無效的嵌入設定。請注意,部分頻道可能無權為直播提供嵌入式播放器。詳情請參閱 YouTube 說明中心。 -
在播放清單中插入重複的影片時,
playlistItems.insert
方法不會再傳回錯誤。先前某些播放清單 (例如 [我的收藏]) 不允許重複,但系統不再支援。一般而言,播放清單允許重複影片。
-
-
其他更新
-
我們更新了 2016 年 9 月 15 日的修訂版本記錄項目,明確指出只要回應中包含
channel
資源的contentDetails.relatedPlaylists.watchHistory
和contentDetails.relatedPlaylists.watchLater
屬性,則一律分別包含HL
和WL
值。此外,只有在授權使用者擷取使用者本身頻道的資料時,系統才會納入這些資源。
-
2016 年 9 月 15 日
這次更新的修改如下:
-
修訂版本記錄更新於 2016 年 8 月 11 日生效,當中探討了幾項與主題 ID 相關的異動,包括系統從 2017 年 2 月 10 日起,支援的主題 ID 組合將有所變動。我們將於 2016 年 11 月 10 日公布目前支援的主題清單。
-
下列變更現已生效。我們在 2016 年 8 月 11 日的修訂版本記錄更新中公布了這些變更:
-
如果透過設為
true
的home
參數呼叫activities.list
方法,API 回應現在會包含類似未登入 YouTube 使用者在首頁看到的項目。這個簡單的變更旨在提供比 2016 年 8 月 11 日修訂版本記錄更新所述行為更好的使用者體驗。該更新說明指出,使用
home
參數的請求會傳回空白清單。 -
channel
資源的contentDetails.relatedPlaylists.watchHistory
和contentDetails.relatedPlaylists.watchLater
屬性現在分別包含所有管道的HL
和WL
值。請注意,只有授權使用者才能查看這些屬性,且只能擷取使用者自己的頻道資料。即使是授權使用者擷取自身頻道的資料,這些屬性也一律會包含
HL
和WL
值。因此,您無法透過 API 擷取觀看記錄和「稍後觀看」播放清單 ID。此外,針對頻道觀看記錄或「稍後觀看」播放清單的播放清單詳細資料 (
playlists.list
) 或播放清單項目 (playlistItems.list
) 的擷取要求,現在會傳回空白清單。這項行為適用於新值HL
和WL
,以及 API 用戶端可能已儲存的任何觀看記錄或稍後觀看播放清單 ID。
-
-
系統不再傳回
video
資源的fileDetails.recordingLocation
物件及其子項屬性。以前只有影片擁有者才能擷取這項資料 (例如父項fileDetails
物件)。
2016 年 8 月 11 日
這次更新的修改如下:
-
在新版《YouTube API 服務條款》(以下簡稱「新版條款」) 中,YouTube 工程與開發人員網誌詳細介紹了舊版《服務條款》的一系列更新內容。除了「新版條款」(將於 2017 年 2 月 10 日生效) 外,本次更新也包含多份證明文件,可協助說明開發人員必須遵守的政策。
如需完整的新版文件,請參閱修訂版條款的修訂版本記錄。此外,日後對更新版條款或相關附件文件的變更,也會在該修訂版本記錄中說明。您可以訂閱 RSS 動態消息,從文件中的連結列出該修訂版本記錄的變更。
-
由於 Freebase 和 Freebase API 已淘汰,因此我們對主題 ID 進行了幾項變更。下列 API 資源和方法會使用主題 ID:
channel
資源的topicDetails
部分會標示與頻道相關的主題。video
資源的topicDetails
部分會標示與影片相關的主題。search.list
方法的topicId
參數可讓您搜尋與特定主題相關的影片或頻道。
這些功能的變更如下:
-
自 2017 年 2 月 10 日起,YouTube 會開始傳回一組一小部分的主題 ID,而不是目前所傳回更為精細的 ID 組合。本系列支援的主題會辨識概略分類,例如「運動」或「籃球」,但其不會識別特定球隊或球員。我們會公布支援的主題組合,讓您有時間為應用程式做好這項異動的準備。
-
您已擷取的任何 Freebase 主題 ID 可用於搜尋內容,直到 2017 年 2 月 10 日為止。不過,在這之後,您將只能用在前一個項目中找出的少數主題,以便依主題擷取搜尋結果。
-
2017 年 2 月 10 日後,如果您嘗試使用的主題 ID 進行搜尋,該主題 ID 不在支援的較小主題 ID 中,API 會傳回空白的結果集。
-
部分 API 欄位和參數將於 2016 年 9 月 12 日淘汰:
-
activities.list
方法的home
參數可讓授權使用者擷取該名使用者的 YouTube 首頁活動動態消息。2016 年 9 月 12 日後使用這個參數的要求將傳回空白清單。 -
只有經過授權的使用者可查看
channel
資源的contentDetails.relatedPlaylists.watchHistory
和contentDetails.relatedPlaylists.watchLater
屬性,以便擷取使用者自身頻道的資料。2016 年 9 月 12 日後,contentDetails.relatedPlaylists.watchHistory
會傳回HL
值,contentDetails.relatedPlaylists.watchLater
屬性則會傳回所有管道的WL
值。2016 年 9 月 12 日後,如果要求擷取頻道觀看記錄或稍後觀看播放清單的詳細資料 (
playlists.list
),系統將傳回空白清單。從其中一個播放清單擷取播放清單項目 (playlistItems.list
) 的要求,也會在 7 天之後傳回空白清單。無論是新值HL
和WL
,以及 API 用戶端已儲存過的所有觀看記錄或稍後觀看播放清單 ID,都是如此。 -
2016 年 9 月 12 日後,系統不再傳回
video
資源的fileDetails.recordingLocation
物件或其任何子項屬性。只有影片擁有者才能擷取這項資料,因為只有影片擁有者可以擷取父項fileDetails
物件。
-
2016 年 6 月 13 日
這次更新的修改如下:
-
channel
資源的contentDetails.googlePlusUserId
屬性已淘汰。在過去,資源只有在頻道已與 Google+ 個人資料建立關聯時才會顯示。在停用後,該屬性就不會再納入任何channel
資源。 -
comment
資源的snippet.authorGoogleplusProfileUrl
屬性已淘汰。在過去,資源只有在頻道已與 Google+ 個人資料建立關聯時才會顯示。在停用後,該屬性就不會再納入任何comment
資源。
這些屬性都不會在淘汰後傳回,因此這兩項屬性也已從對應的資源說明文件中移除。
2016 年 5 月 31 日
這次更新的修改如下:
-
subscriptions.list
方法的新myRecentSubscribers
參數會擷取已驗證使用者頻道的訂閱者清單,依使用者訂閱的時間反向排序。請注意,新參數僅支援擷取已驗證使用者頻道最近 1000 名訂閱者。如要擷取完整的訂閱者清單,請使用
mySubscribers
參數。該參數不會依特定順序傳回訂閱者,而不會限制可擷取的訂閱人數。 -
活動、playlistItem、playlist、搜尋結果、縮圖和影片資源的
snippet.thumbnails.(key)
屬性定義已更新,指出部分影片可使用其他縮圖圖片大小。standard
圖片的寬度為 640px,高度為 480px。maxres
圖片的寬度為 1280 像素,高度為 720 像素。
-
我們更新了
channelSection.list
方法part
參數的定義,新增targeting
部分時,可以採用2
配額單位的費用擷取。 -
當有不當授權的要求嘗試擷取
video
資源的fileDetails
、processingDetails
或suggestions
部分時,videos.list
方法現在會傳回「禁止」 (403
) 錯誤。只有影片擁有者才能使用這些片段。
2016 年 5 月 17 日
新的 Data API 程式碼片段工具提供常見 YouTube Data API 用途的短程式碼片段。目前,只要是 Apps Script、Go、JavaScript、PHP、Python 和 Ruby 語言中的唯讀 API 方法,均能使用程式碼片段。
這項工具會顯示個別方法的程式碼範例。例如,它為 search.list
方法提供五個程式碼片段:
- 依關鍵字列出影片
- 依地點列出影片
- 列出現場活動
- 搜尋已驗證使用者的影片
- 列出相關影片
針對所有用途,工具都會顯示 API 要求中使用的參數。您可以修改參數值,這時工具會更新程式碼片段,以反映您提供的參數值。
最後,這項工具會顯示每個要求的 API 回應。如果您修改了要求參數,API 回應會根據您提供的參數值。請注意,您必須授權這項工具代您提交要求,以便系統顯示 API 回應。
2016 年 4 月 28 日
這次更新的修改如下:
-
video
資源的新contentDetails.projection
屬性會指定影片的投影格式。有效的屬性值為360
和rectangular
。 -
video
資源的recordingDetails.location
和fileDetails.recordingLocation
屬性已更新,以便說明兩個屬性的差異:recordingDetails.location
屬性會指出影片擁有者想與影片建立關聯的位置。這個位置可供編輯,可在公開影片中搜尋,且可能會向使用者顯示公開影片。fileDetails.recordingLocation
屬性值不可變更,代表與原始上傳影片檔案相關聯的位置。只有影片擁有者看得到這個值。
-
channel
資源的contentDetails.relatedPlaylists.favorites
屬性定義已更新,指出屬性值可能包含參照空播放清單的播放清單 ID,且無法擷取。這是因為收藏影片功能已淘汰。請注意,這項屬性不適用 API 廢止政策。 -
ineligibleAccount
錯誤的定義已更新,以反映出當用於授權 API 要求的 YouTube 帳戶未與使用者的 Google 帳戶合併時,會發生錯誤。comments.insert
、comments.update
、commentThreads.insert
或commentThreads.update
方法可傳回這類錯誤。
2016 年 4 月 20 日
這次更新的修改如下:
-
channels.update
方法的part
參數定義已更新,指出localizations
也是該參數的有效值。 -
入門指南的配額用量一節已更新,可提供與 Google Developers Console 的連結,方便您查看實際配額和配額用量。
2016 年 3 月 16 日
這次更新的修改如下:
-
現有資源和方法的更新內容
-
更新
channelBanner
資源說明文件,建議上傳頻道橫幅圖片的建議尺寸為 2560 x 1440 像素。最小尺寸 (2048 x 1152 像素) 並未改變。 -
channel
資源的新snippet.customUrl
屬性可識別與頻道相關聯的自訂網址。(並非所有頻道都有自訂網址)。YouTube 說明中心說明了取得自訂網址的資格規定,以及如何設定網址。 -
channel
資源的brandingSettings.watch
物件和其所有子項屬性都已淘汰。 -
search.list
要求的 API 回應現在包含regionCode
屬性。這個屬性可識別搜尋查詢所用的區碼。區碼會指示 API 傳回指定國家/地區的搜尋結果。屬性值是雙字母的 ISO 國家/地區代碼,用來識別區域。
i18nRegions.list
方法會傳回支援區域的清單。預設值為US
。如果指定了不支援的地區,YouTube 可能仍會選取其他區域 (而非預設值) 來處理查詢。 -
videoAbuseReportReason
資源的snippet.label
和snippet.secondaryReasons[].label
屬性定義已更新,指出這些屬性包含濫用檢舉原因的本地化標籤文字。此外,
videoAbuseReportReasons.list
方法現在支援hl
參數,該參數可指定 API 回應中標籤文字應使用的語言。預設參數值為en_US
。 -
video
資源的新contentDetails.contentRating.ecbmctRating
屬性會識別土耳其文化部的評估與分類委員會 (Ministry of Culture and Tourism) 評估的影片評分。此外,其他評分系統的 API 屬性支援下列新的屬性值:
contentDetails.contentRating.fpbRating
(南非)
評分:10;屬性值:fpb10
contentDetails.contentRating.moctwRating
(台灣)
評分:R-12;屬性值:moctwR12
contentDetails.contentRating.moctwRating
(台灣)
評分:R-15;屬性值:moctwR15
-
video
資源的liveStreamingDetails.activeLiveChatId
屬性包含與影片相關聯的有效聊天室 ID。只有在影片為目前啟用聊天室功能的直播時,才會顯示屬性值。直播結束後,直播結束後,房源就不會再顯示該房源。 -
video
資源的status.rejectionReason
屬性支援新的屬性值legal
。
-
-
這個 API 支援下列新錯誤:
錯誤類型 錯誤詳情 說明 badRequest (400)
notEditable
channelSections.insert
、channelSections.update
和channelSections.delete
方法會傳回此錯誤,表示無法建立、更新或刪除指定的管道部分。badRequest (400)
styleRequired
channelSections.insert
和channelSections.update
方法會傳回這項錯誤,表示 API 要求中提交的channelSection
資源必須指定snippet.style
屬性的值。badRequest (400)
typeRequired
channelSections.insert
和channelSections.update
方法會傳回這個錯誤,表示在 API 要求中提交的channelSection
資源必須指定snippet.type
屬性的值。badRequest (400)
processingFailure
commentThreads.list
方法會傳回此錯誤,表示 API 伺服器無法成功處理要求。這可能是暫時性錯誤,但通常表示要求的輸入內容無效。請檢查要求主體中commentThread
資源的結構,確保該資源有效。forbidden (403)
commentsDisabled
commentThreads.list
方法會傳回這個錯誤,表示videoId
參數識別的影片已停用留言功能。badRequest (400)
commentTextTooLong
commentThreads.insert
方法會傳回這個錯誤,表示所插入的comment
資源在snippet.topLevelComment.snippet.textOriginal
屬性中包含太多字元。invalidValue (400)
videoAlreadyInAnotherSeriesPlaylist
playlistItems.insert
方法會傳回這項錯誤,表示你嘗試新增至播放清單的影片已在其他系列播放清單中。如要進一步瞭解系列播放清單,請參閱 YouTube 說明中心。badRequest (400)
subscriptionForbidden
subscriptions.insert
方法會傳回這項錯誤,表示您已達到訂閱數量上限,或是最近建立的訂閱項目過多。如果是第二種情況,您可以在幾小時後重試要求。badRequest (400)
invalidCategoryId
videos.update
方法會傳回這項錯誤,表示上傳的video
資源中的snippet.categoryId
屬性指定了無效的類別 ID。使用videoCategories.list
方法擷取支援的類別。badRequest (400)
invalidDescription
videos.update
方法會傳回這項錯誤,表示上傳的video
資源中指定的snippet.description
屬性值無效。badRequest (400)
invalidPublishAt
videos.update
方法會傳回這項錯誤,表示上傳的video
資源中的status.publishAt
屬性指定了無效的排定發布時間。badRequest (400)
invalidRecordingDetails
videos.update
方法會傳回這個錯誤,表示上傳的video
資源中recordingDetails
物件指定了無效的錄影詳細資料。badRequest (400)
invalidTags
videos.update
方法會傳回這項錯誤,表示上傳的video
資源中指定的snippet.tags
屬性值無效。badRequest (400)
invalidTitle
videos.update
方法傳回這個錯誤,表示上傳的video
資源中的snippet.title
屬性指定了無效或空白的影片標題。badRequest (400)
invalidVideoMetadata
videos.update
方法會傳回這個錯誤,表示要求中繼資料無效。如果要求更新video
資源的snippet
部分,但未為snippet.title
和snippet.categoryId
屬性同時設定值,就會發生這個錯誤。
2015 年 12 月 18 日
根據歐盟 (EU) 法律規定,您必須向歐盟境內的使用者揭露特定資訊,並徵得同意聲明。因此,如果使用者位於歐盟地區,您必須遵守《歐盟地區使用者同意授權政策》。我們已在 YouTube API 服務條款中新增這項規定的通知。
2015 年 11 月 19 日
這個 API 現在支援設定及擷取 playlist
和 video
資源的 snippet.title
和 snippet.description
屬性、channelSection
資源的 snippet.title
屬性,以及 channel
資源的 snippet.description
屬性等本地化文字。
-
設定經過翻譯的標題和說明
您可以在呼叫資源的
insert
或update
方法時,為該資源設定本地化值。如要為資源設定本地化值,請同時執行下列兩項操作:-
確認已設定資源的
snippet.defaultLanguage
屬性值。這個屬性會識別資源的snippet.title
和snippet.description
屬性語言。其值可以是任何支援的應用程式語言,或大多數其他 ISO 639-1:2002 語言代碼。舉例來說,如果您上傳的影片含有英文標題和說明,則應將snippet.defaultLanguage
屬性設為en
。更新
channel
資源的注意事項:如要設定channel
資源的snippet.defaultLanguage
屬性,您其實需要更新brandingSettings.channel.defaultLanguage
屬性。 -
將
localizations
物件新增至要更新的資源。每個物件鍵都是字串,可用來識別應用程式語言或 ISO 639-1:2002 語言代碼,每個鍵都會對應至物件,其中包含資源的本地化標題 (和說明)。下方的範例程式碼片段會將資源的預設語言設為英文。並為影片新增德文和西班牙文的本地化標題和說明:
{ "kind": "youtube#video", ... "snippet": { "title": "Playing soccer", "description": "We play soccer in the park on Sundays.", "defaultLanguage": "en", ... }, "localizations": "de": { "title": "Fußball spielen", "description": "Wir spielen Fußball im Park am Sonntag" }, "es": { "title": "Jugar al fútbol", "description": "Nosotros jugamos fútbol en el parque los domingos", } } }
重要事項:提醒您,更新資源的本地化資料時,API 要求必須包括資料的所有現有本地化版本。舉例來說,如果您在上述範例中,傳送了後續要求,希望在影片中加入葡萄牙文資料,則要求中必須包含德文、西班牙文和葡萄牙文的本地化資料。
-
-
擷取本地化值
此 API 支援兩種擷取資源的本地化值方法:
-
將
hl
參數加到channels.list
、channelSections.list
、playlists.list
或videos.list
要求中,以擷取YouTube 網站支援的特定應用程式語言的本地化資料。如果該語言提供本地化資源詳細資料,資源的snippet.localized
物件會包含本地化值。不過,如果無法取得本地化詳細資料,snippet.localized
物件就會以資源的預設語言會包含資源詳細資料。舉例來說,假設
videos.list
要求擷取上述影片的資料,並提供經本地化的德文和西班牙文資料。如果hl
參數設為de
,資源就會包含以下資料:{ "kind": "youtube#video", ... "snippet": { "title": "Playing soccer", "description": "We play soccer in the park on Sundays.", "defaultLanguage": "en", "localized": { "title": "Fußball spielen", "description": "Wir spielen Fußball im Park am Sonntag" } ... } }
不過,如果
hl
參數設為fr
,snippet.localized
物件將包含英文標題和說明,因為英文是資源的預設語言,且無法取得本地化的法文詳細資料。重要事項:hl
參數僅支援可識別 YouTube 網站支援的應用程式語言的值。如要判斷其他語言是否提供本地化文字,您必須擷取資源的localizations
部分並篩選,以判斷本地化文字是否存在。
舉例來說,您需要擷取本地化的完整清單,來判斷本地化文字是否提供阿帕拉契英文版本。
-
擷取資源時,請在
part
參數值中加入localizations
,擷取該資源的所有本地化詳細資料。如果要針對非 YouTube 應用程式目前的語言擷取本地化資料,您必須使用這個方法擷取所有本地化內容,再進行篩選,以判斷是否有所需的本地化資料。
-
-
與本地化文字值相關的錯誤
這個 API 也支援以下本地化文字值的新錯誤:
錯誤類型 錯誤詳情 說明 badRequest (400)
defaultLanguageNotSetError
這個錯誤表示嘗試為資源插入或更新 localizations
物件的要求失敗,因為該資源未設定snippet.defaultLanguage
屬性。channels.update
、channelSections.insert
、channelSections.update
、playlists.insert
、playlists.update
、videos.insert
和videos.update
方法支援此錯誤。badRequest (400)
localizationValidationError
這個錯誤表示資源的 localizations
物件中的其中一個值無法驗證。舉例來說,如果物件包含無效的語言代碼,就可能發生這項錯誤。channels.update
、channelSections.insert
、channelSections.update
、playlists.insert
和playlists.update
方法支援這項錯誤。
2015 年 11 月 4 日
這次更新的修改如下:
-
現有資源和方法的更新
-
search.list
方法的order
參數已更新,提醒您如果依viewCount
排序直播,API 結果會依直播的同時觀看人數排序。 -
search.list
方法的relatedToVideoId
參數已更新,以便您注意,如果已設定該參數,則僅支援part
、maxResults
、pageToken
、regionCode
、relevanceLanguage
、safeSearch
、type
(必須設為video
) 和fields
等參數。本次更新並未反映 API 行為的變更。 -
我們更新了
video
資源snippet.publishedAt
屬性的定義,以指出指定影片發布的日期和時間的屬性值可能與上傳影片的時間不同。例如,如果影片上傳為私人影片,但後來才設為公開,則屬性值會指定影片公開的時間。新版定義也會說明系統如何填入私人和不公開影片的值。這項變更不會影響 API 行為。
-
video
資源的status.publishAt
屬性定義已更新為:- 如果您在呼叫
videos.update
方法時設定了此屬性值,則也必須將status.privacyStatus
屬性值設為private
(即使影片已設為私人影片)。 - 如果請求中排定的影片發布時間在過去,系統會立即發布影片。因此,將
status.publishAt
屬性設為過去的日期和時間的效果,等同於將影片的privacyStatus
從private
變更為public
。
- 如果您在呼叫
-
video
資源的contentDetails.contentRating.cncRating
屬性會指定影片的評級,由法國電影分級委員會 (Commission de classification cinématographique) 評定。這個屬性取代了現已淘汰的contentDetails.contentRating.fmocRating
屬性。 -
channel
資源的 brandingSettings.channel.keywords 定義已更新,正確反映屬性值包含以空格分隔的字串清單,而非以逗號分隔的清單,如先前說明。這項更新不會影響 API 行為。 -
thumbnails.set
方法的說明文件已更新,以如實反映要求內文,其中包含您要上傳且與影片建立關聯的縮圖圖片。要求主體不包含thumbnail
資源。先前說明文件指出,您不應在呼叫這個方法時提供要求主體。本次更新並未反映 API 行為的變更。 -
為反映
activities.list
方法目前不包含新影片留言的相關資源,因此activity
資源的說明已更新。資源的snippet.type
和contentDetails.comment
也已更新。
-
-
新增和更新的錯誤
-
這個 API 現在支援下列錯誤:
錯誤詳細資料 activities.insert
HTTP 回應代碼 badRequest (400)
原因 invalidMetadata
說明 kind
資源與提供的 ID 類型不符。commentThreads.update
comments.insert
comments.update
HTTP 回應代碼 badRequest (400)
原因 commentTextTooLong
說明 所插入或更新的 comment
資源在snippet.topLevelComment.snippet.textOriginal
屬性中包含過多字元。playlistItems.insert
playlistItems.update
HTTP 回應代碼 forbidden (403)
原因 playlistItemsNotAccessible
說明 這項要求無權插入、更新或刪除指定的播放清單項目。 playlists.delete
playlists.insert
playlists.update
HTTP 回應代碼 badRequest (400)
原因 playlistForbidden
說明 作業遭到禁止,或是要求未獲得適當授權。 search.list
HTTP 回應代碼 badRequest (400)
原因 invalidLocation
說明 location
和/或locationRadius
參數值的格式不正確。search.list
HTTP 回應代碼 badRequest (400)
原因 invalidRelevanceLanguage
說明 relevanceLanguage
參數值的格式不正確。subscriptions.insert
HTTP 回應代碼 badRequest (400)
原因 subscriptionForbidden
說明 當以下任一條件皆成立時,就會發生這項錯誤: - 你嘗試建立的訂閱項目已存在
- 已達訂閱數量上限
- 您試圖訂閱自己的頻道,但系統不支援這項功能。
- 您最近建立了太多訂閱項目,必須過幾小時才能重試要求。
videos.update
HTTP 回應代碼 badRequest (400)
原因 invalidDefaultBroadcastPrivacySetting
說明 要求嘗試為預設廣播設定無效的隱私權設定。
-
2015 年 8 月 28 日
這次更新的修改如下:
-
現有資源和方法的更新內容
-
video
資源的statistics.favoriteCount
屬性已淘汰。根據我們的淘汰政策,在這項公告推出至少一年後,您還是可以繼續在
video
資源中納入這項資源。不過,屬性值現在一律設為0
。
-
2015 年 8 月 7 日
這次更新的修改如下:
-
現有資源和方法的更新內容
-
video
資源的snippet.tags[]
屬性定義已更新,可進一步說明 API 伺服器如何計算屬性值的長度。請注意,這項更新不會反映 API 行為的變更。具體來說,定義現在說明如果標記包含空格,API 伺服器會將標記值視為以引號包圍,並將引號計入字元限制。因此,就字元限制而言,Foo-Baz 標記包含七個字元,但 Foo Baz 標記包含九個字元。
-
commentThreads.insert
方法不再支援shareOnGooglePlus
參數,該參數先前會指出是否要將留言和回覆留言一併發布至作者的 Google+ 個人資料。如果要求提交參數,API 伺服器會忽略參數,但會處理其他要求。
-
2015 年 6 月 18 日
這次更新的修改如下:
-
現有資源和方法的更新
-
commentThreads.list
方法的新order
參數會指定 API 回應應列出留言串的順序。會依時間或關聯性排序。預設行為是以時間排序。 -
video
資源的新snippet.defaultAudioLanguage
屬性會指定影片預設音軌的語言。 -
video
資源的contentDetails.licensedContent
屬性定義已更新,清楚說明內容必須是原先上傳至與 YouTube 內容合作夥伴連結的頻道,然後由該合作夥伴聲明版權。這並非實際 API 行為的變更。 -
captions.delete
、captions.download
、captions.insert
、captions.list
和captions.update
方法現在支援onBehalfOfContentOwner
參數,其他幾種方法已支援此參數。使用該方法的要求也必須透過可提供https://www.googleapis.com/auth/youtubepartner
範圍存取權的權杖進行授權。
-
-
新增和更新的錯誤
-
這個 API 現在支援下列錯誤:
錯誤詳細資料 videos.rate
HTTP 回應代碼 badRequest (400)
原因 emailNotVerified
說明 使用者必須驗證電子郵件地址,才能對影片評分。 videos.rate
HTTP 回應代碼 badRequest (400)
原因 videoPurchaseRequired
說明 只有租借影片的使用者可以評分。 -
subscriptions.delete
和subscriptions.insert
方法不再支援accountClosed
和accountSuspended
錯誤。
-
2015 年 4 月 27 日
這次更新的修改如下:
-
新資源和方法
-
針對含有不當內容的影片遭標示為含有不當內容的原因,全新的
videoAbuseReportReason
資源會提供相關資訊。videoAbuseReportReasons.list
方法可讓您擷取影片遭標示為違規的所有原因清單。 -
如要確實檢舉含有不當內容的影片,可以使用新的
videos.reportAbuse
方法。要求的內文包含 JSON 物件,用於指出影片遭檢舉,以及判定影片含有不當內容的原因。您可以透過上述videoAbuseReportReason.list
方法取得有效原因。我們也更新了遷移指南,新增檢舉濫用影片的範例。本次異動後,第 3 版 API 現已支援預定支援的所有 v2 API 功能。這些功能也會在遷移指南中說明。
-
-
現有資源和方法的更新內容
-
search.list
方法的新forDeveloper
篩選器參數會限制搜尋範圍,只擷取透過開發人員應用程式或網站上傳的影片。forDeveloper
參數可以與選用的搜尋參數 (例如q
參數) 搭配使用。在這項功能中,每部上傳的影片都會自動標上與開發人員在 Google Developers Console 中的應用程式相關聯的專案編號。
當搜尋要求之後將
forDeveloper
參數設為true
時,API 伺服器會使用要求的授權憑證來識別開發人員。因此,開發人員可以限定搜尋結果範圍,只顯示透過開發人員自家應用程式或網站上傳的影片,但無法限制透過其他應用程式或網站上傳的影片。這項新功能與第 2 版 API 所支援的開發人員標記功能類似,但不完全相同。
-
channel
資源的全新snippet.country
資源可讓頻道擁有者將頻道與特定國家/地區建立關聯。注意:如要為
channel
資源設定snippet.country
屬性,您實際上需要更新brandingSettings.channel.country
屬性。 -
這個 API 現在支援
channelSection
資源的指定目標。指定頻道版面功能,可用來限制符合特定條件的使用者,瀏覽的內容部分。API 會公開三種指定目標選項。使用者必須符合所有指定條件,才能看到頻道專區。
-
targeting.languages[]
:YouTube 應用程式語言清單。使用者只要選擇其中一種語言,就能查看相應的頻道版面。 -
targeting.regions[]
:YouTube 首選內容地區的清單。只要使用者選取這些區域,以及系統自動選取這些區域的使用者,就可以看到頻道版面。 -
targeting.countries[]
:顯示頻道專區的國家/地區清單。清單中的每個值都是 ISO 3166-1 alpha-2 國家/地區代碼。
-
-
video
資源contentDetails.duration
屬性的定義已修正,以反映該值可反映小時、天等。 -
channelSections.delete
、playlistItems.delete
、playlists.delete
、subscriptions.delete
和videos.delete
方法的說明文件已修正,以反映在成功時,這些方法都會傳回 HTTP204
回應碼 (No Content
)。
-
-
新增和更新的錯誤
-
這個 API 目前支援下列錯誤:
錯誤類型 錯誤詳情 說明 badRequest (400)
targetInvalidCountry
如果插入的 channelSection
資源包含targeting.countries[]
屬性的無效值,channelSections.insert
和channelSections.update
方法會傳回此錯誤。badRequest (400)
targetInvalidLanguage
如果插入的 channelSection
資源包含targeting.languages[]
屬性的無效值,channelSections.insert
和channelSections.update
方法會傳回此錯誤。badRequest (400)
targetInvalidRegion
如果插入的 channelSection
資源包含targeting.regions[]
屬性的無效值,channelSections.insert
和channelSections.update
方法會傳回此錯誤。badRequest (400)
operationNotSupported
如果 API 使用者無法在 snippet.parentId
屬性識別的頂層註解中插入註解,comments.insert
方法會傳回此錯誤。在commentThread
資源中,snippet.canReply
屬性會指出目前的觀眾是否可以回覆該會話串。badRequest (400)
invalidChannelId
如果要求中的 channelId
參數指定無效的管道 ID,search.list
方法就會傳回這個錯誤。badRequest (400)
subscriptionForbidden
如果 API 使用者嘗試訂閱自己的頻道, subscriptions.insert
方法會傳回此錯誤。 -
captions.update
方法不再支援invalidMetadata
和videoNotFound
錯誤。
-
2015 年 4 月 16 日
這次更新的修改如下:
-
遷移指南已更新,說明如何遷移仍在使用第 2 版 API 留言功能的應用程式。
本指南還指出了第 2 版 API 不支援但第 3 版 API 所支援的幾種註解功能。包括:
- 擷取頻道留言
- 擷取與頻道相關的所有留言串,這表示 API 回應可能包含關於頻道或頻道任何影片的留言。
- 更新註解的文字
- 將留言標示為垃圾內容
- 設定留言的管理狀態
-
《訂閱推播通知》指南已更新,是為了反映通知只會推送至 Google PubSubHubBub 中樞,不會同時推送至 Superfeedr 中心 (如先前所述)。
2015 年 4 月 9 日
這次更新的修改如下:
-
API 的全新
commentThread
和comment
資源可讓您擷取、插入、更新、刪除及管理留言。-
commentThread
資源包含 YouTube 留言討論串的相關資訊,其中包含該留言的頂層留言和回覆 (如有)。commentThread
資源可以代表影片或頻道的留言,頂層註解和回覆實際上是位於
commentThread
資源中的巢狀comment
資源。請注意,commentThread
資源不一定包含所有留言回覆,因此如要擷取特定留言的所有回覆,請使用comments.list
方法。此外,部分留言沒有回覆。API 支援下列
commentThread
資源方法:commentThreads.list
:擷取註解討論串清單。這個方法可用來擷取與特定影片或頻道相關聯的留言。commentThreads.insert
:建立新的頂層註解。(請使用comments.insert
方法回覆現有留言)。commentThreads.update
:修改頂層註解。
-
comment
資源包含關於單一 YouTube 留言的資訊。comment
資源可代表對影片或頻道的留言。此外,留言可以是頂層留言,也可以是頂層留言的回覆。API 支援下列
comment
資源方法:comments.list
:擷取註解清單。使用這個方法,即可擷取特定留言的所有回覆。comments.insert
:回覆現有留言。comments.update
– 修改註解。comments.markAsSpam
– 檢舉一或多則垃圾留言。comments.setModerationStatus
:設定一或多則留言的管理狀態。例如,你可以清除一則留言,讓留言公開顯示,或是拒絕不適合顯示的留言。API 要求必須獲得留言所屬頻道或影片的擁有者授權。comments.delete
– 刪除註解。
請注意,呼叫
comments.insert
、comments.update
、comments.markAsSpam
、comments.setModerationStatus
、comments.delete
、commentThreads.insert
和commentThreads.update
方法時必須使用 API 的新https://www.googleapis.com/auth/youtube.force-ssl
範圍 (如 2015 年 4 月 2 日的修訂版本記錄中所述)。 -
-
在全新的「訂閱推播通知」指南中,我們將說明 API 推出的全新推播通知支援 PubSubHubBub,這是伺服器對伺服器的發布/訂閱通訊協定,能處理網路存取資源的作業。當頻道進行下列任一活動時,PubSubHubBub 回呼伺服器即可收到 Atom 動態饋給通知:
- 上傳影片
- 更新影片標題
- 更新影片說明
-
我們也更新了遷移指南,說明系統現在支援推播通知。不過,由於第 2 版 API 支援許多其他類型的推播通知,但在第 3 版 API 中不支援,因此該指南的「已淘汰」一節仍會列出 PubSubHubBub 支援。
-
API 的新
https://www.googleapis.com/auth/youtube.force-ssl
範圍現在是先前支援https://www.googleapis.com/auth/youtube
範圍的任何 API 方法的有效範圍。 -
這個 API 現在支援下列錯誤:
錯誤類型 錯誤詳情 說明 badRequest (400)
invalidRating
如果要求含有 rating
參數的意外值,videos.rate
方法就會傳回此錯誤。 -
subscriptions.insert
方法不再支援subscriptionLimitExceeded
錯誤,該錯誤先前表示提出要求的訂閱者已超出訂閱頻率限制。
2015 年 4 月 2 日
這次更新的修改如下:
-
新的
captions
資源代表 YouTube 字幕軌。字幕軌只能與一部 YouTube 影片建立關聯。 -
另外,遷移指南也已更新,說明如何遷移仍在使用 v2 API 字幕功能的應用程式。
-
API 的新
https://www.googleapis.com/auth/youtube.force-ssl
範圍需要透過 SSL 連線與 API 伺服器進行通訊。這個新範圍會授予與
https://www.googleapis.com/auth/youtube
範圍相同的存取權。事實上,這兩個範圍的功能完全相同,因為 YouTube API 伺服器只能透過 HTTPS 端點使用。因此,即使https://www.googleapis.com/auth/youtube
範圍不需要 SSL 連線,但實際上無法提出 API 要求。呼叫所有
caption
資源的方法時,都需要使用新的範圍。
2015 年 3 月 11 日
這次更新的修改如下:
-
YouTube Data API (v3) 遷移指南中的新分頁包含「v3 API 的新功能」的新分頁,其中列出第 3 版 API 所支援及第 2 版 API 不支援的功能。指南中的其他分頁仍會列出先前相同的功能。舉例來說,說明如何更新頻道內影片宣傳廣告活動資料的新功能也列在「頻道 (個人資料)」分頁下方。
-
YouTube Data API (v3) 遷移指南已更新,指出第 3 版 API 將支援下列第 2 版 API 功能:
-
YouTube Data API (v3) 遷移指南已更新,提醒你,v3 API 將不支援下列 v2 API 功能:
-
擷取影片推薦 – v3 API 不會擷取只包含目前 API 使用者推薦影片的清單。不過,您可以透過呼叫
activities.list
方法並將home
參數值設為true
,使用 v3 API 搜尋推薦影片。在 API 回應中,如果
snippet.type
屬性的值為recommendation
,資源就會對應至推薦的影片。在此情況下,contentDetails.recommendation.reason
和contentDetails.recommendation.seedResourceId
屬性會包含推薦影片的原因。提醒你,我們不保證回覆都會收錄一定數量的推薦影片。 -
擷取新的訂閱影片 - v3 API 不會擷取只含有最近上傳到 API 使用者所訂閱頻道的影片的清單。不過,您可以使用 v3 API 呼叫
activities.list
方法,並將home
參數值設為true
,藉此尋找新的訂閱影片。在 API 回應中,如果
snippet.type
屬性的值為upload
,資源會對應至新的訂閱影片。請注意,我們不保證回覆一定會包含任意數量的新訂閱影片。 -
動態饋給更新推播通知:第 2 版 API 支援推播通知,可使用簡易更新通訊協定 (SUP) 或 PubSubHubbub 監控 YouTube 使用者的使用者活動動態饋給。每當有人訂閱頻道、分享影片、將影片加入最愛、留言或上傳影片時,系統就會提供通知。
v3 API 將支援使用 PubSubHubbub 通訊協定的推播通知,但通知只會涵蓋影片上傳和影片標題或影片說明的更新。
-
頻道位置:v2 API 使用
<yt:location>
標記,識別使用者在頻道 YouTube 公開個人資料中輸入的位置。雖然部分開發人員使用這個欄位將頻道與特定國家/地區建立關聯,但該欄位的資料無法一致地用於這項用途。 -
設定或擷取開發人員標記:第 2 版 API 支援在上傳影片時,為影片與關鍵字或開發人員標記建立關聯。開發人員標記不會顯示給 YouTube 使用者,但影片擁有者可以擷取符合特定開發人員標記的影片。
第 3 版 API 會提供類似 (但不完全相同) 的功能。具體來說,開發人員可以搜尋由其應用程式上傳的影片。針對這項功能,每部上傳的影片都會自動標記與開發人員在 Google Developers Console 中應用程式相關聯的專案編號。隨後開發人員會使用相同的專案編號搜尋影片。
-
依發布日期、觀看次數或評分列出影片:在 v2 API 中,您可以使用
orderby
參數,依位置、時間長度、發布日期、標題和其他值排序播放清單中的影片。在 v3 API 中,播放清單項目通常會依位置遞增順序排序,且無法使用其他排序選項。但有幾個例外情況。系統會自動將新上傳的影片、收藏的影片、喜歡的影片或最近觀看的影片,新增為下列類型的播放清單中的第一個項目 (
snippet.position
=0
)。因此,這些清單會根據項目加入清單的時間,按照最新到最舊項目的順序有效排序。- 使用者上傳內容
- 收藏的影片
- 喜歡的影片
- 觀看記錄
但請注意,系統會將加入「稍後觀看」播放清單的新項目新增為該清單中的最後一個項目,因此該清單就會有效從最舊到最新項目排序。
-
批次處理 – v3 API 支援 v2 API 支援的其中一種批次處理使用案例。v3 API 的
channels.list
、channelSections.list
、guideCategories.list
、playlistItems.list
、playlists.list
、subscriptions.list
、videoCategories.list
和videos.list
方法都支援id
參數,可用於指定以半形逗號分隔的 ID 清單 (影片 ID、頻道 ID 等)。您可以使用這些方法,透過單一要求擷取多項資源的清單。
這些變更生效後,本指南指出在現行 API 版本 (v3) 中,舊版 (v2) API 中即將淘汰的所有功能,
-
2015 年 3 月 4 日
這次更新的修改如下:
-
channelSections.delete
和channelSections.update
方法現在支援onBehalfOfContentOwner
參數,其他幾種方法已經支援此參數。 -
下列屬性及其子項屬性已淘汰:
brandingSettings.image.backgroundImageUrl
brandingSettings.image.largeBrandedBannerImageImapScript
brandingSettings.image.largeBrandedBannerImageUrl
brandingSettings.image.smallBrandedBannerImageImapScript
brandingSettings.image.smallBrandedBannerImageUrl
注意:這些屬性皆未受 API 淘汰政策約束。
-
video
資源的新contentDetails.contentRating.contentDetails.contentRating.djctqRatingReasons
屬性會指出影片獲得 DJCQT (巴西) 分級的原因。 -
這個 API 現在支援下列錯誤:
錯誤類型 錯誤詳情 說明 notFound (404)
channelNotFound
如果要求的 id
參數指定找不到的頻道,channels.update
方法會傳回此錯誤。badRequest (400)
manualSortRequiredinvalidValue
如果要求嘗試設定播放清單項目的位置,但播放清單不是使用手動排序, playlistItems.insert
和playlistItems.update
方法就會傳回此錯誤。舉例來說,播放清單項目可以按照日期或熱門程度排序,您可以從要求主體中傳送的資源中移除snippet.position
元素,即可解決這個錯誤。如要讓播放清單項目在清單中顯示特定位置,請先將播放清單的排序設定更新為「手動」。你可以透過 YouTube 影片管理員調整這項設定。forbidden (403)
channelClosed
如果要求的 channelId
參數指定已關閉的管道,playlists.list
方法會傳回此錯誤。forbidden (403)
channelSuspended
如果要求的 channelId
參數指定某個已遭停權的頻道,playlists.list
方法就會傳回這個錯誤。forbidden (403)
playlistForbidden
如果要求的 id
參數不支援要求,或是要求未經過適當授權,playlists.list
方法就會傳回這項錯誤。notFound (404)
channelNotFound
如果要求的 channelId
參數指定無法找到的管道,playlists.list
方法就會傳回此錯誤。notFound (404)
playlistNotFound
如果要求的 id
參數指定找不到播放清單,playlists.list
方法會傳回此錯誤。notFound (404)
videoNotFound
如果要求的 id
參數指定找不到的影片,videos.list
方法就會傳回這個錯誤。badRequest (400)
invalidRating
如果要求包含 rating
參數的未預期值,videos.rate
方法會傳回此錯誤。
2015 年 3 月 2 日
這次更新的修改如下:
-
search.list
方法現在支援relevanceLanguage
參數,可讓您要求與特定語言最相關的結果。YouTube Data API (v3) 遷移指南也已更新,說明如何使用這個新參數。這個參數解決了目前 API 版本 (v3) 與已淘汰的舊版 (v2) 之間的功能差異。
-
YouTube Data API (第 3 版) 遷移指南也已更新,指出 v2 API 提供的特殊動態饋給和中繼資料欄位已淘汰,這些欄位可用於描述電影、預告片、電視節目、電視季和電視集。
2015 年 1 月 14 日
這次更新的修改如下:
-
YouTube Data API (第 3 版) 遷移指南已更新,說明如何使用第 3 版 API 透過 JavaScript 上傳影片。(詳情請參閱「上傳影片」一節)。這項功能與第 2 版 API 支援的瀏覽器上傳功能相同。請注意,這項移轉指南異動並未反映實際的 API 變更,而是提供新的程式碼範例,讓您透過用戶端 JavaScript 上傳影片。
由於支援使用 JavaScript 用戶端程式庫和 CORS 上傳影片,因此遷移指南不再列出瀏覽器型上傳功能,且該功能可能遭到 v3 API 淘汰。
-
videos.insert
方法的說明文件已更新,加入上述的全新 JavaScript 程式碼範例。YouTube Data API (v3) 的 JavaScript 程式碼範例清單也已更新。
2014 年 11 月 11 日
這次更新的修改如下:
-
呼叫
search.list
方法的配額費用已變更為 100 個單位。重要事項:在許多情況下,您可以使用其他 API 方法來擷取資訊,以較低的配額成本進行。舉例來說,您可以透過下列兩種方式尋找已上傳至 GoogleDevelopers 頻道的影片。
-
配額費用:100 個單位
呼叫
search.list
方法並搜尋GoogleDevelopers
。 -
配額費用:6 個單位
呼叫
channels.list
方法,找出正確的管道 ID。將forUsername
參數設為GoogleDevelopers
,並將part
參數設為contentDetails
。在 API 回應中,contentDetails.relatedPlaylists.uploads
屬性可指定頻道上傳影片的播放清單 ID。接著呼叫
playlistItems.list
方法,並將playlistId
參數設為擷取的 ID,並將part
參數設為snippet
。
-
2014 年 10 月 8 日
這次更新的修改如下:
-
channel
資源包含兩個新屬性:-
status.longUploadsStatus
屬性可指明頻道能否上傳長度超過 15 分鐘的影片。只有在頻道擁有者授權 API 要求時,才會傳回這個屬性。有效的屬性值如下:allowed
:頻道可上傳長度超過 15 分鐘的影片。eligible
:頻道符合上傳長度超過 15 分鐘的資格,但必須先啟用這項功能。disallowed
– 頻道無法上傳長度超過 15 分鐘的影片,或不符合上傳資格。
如需進一步瞭解這些值,請參閱屬性定義。YouTube 說明中心也提供這項功能的詳細資訊。
-
invideoPromotion.useSmartTiming
屬性會指出管道的宣傳廣告活動是否使用「智慧時間」。這項功能會嘗試在較可能獲得點擊的時間點顯示宣傳活動,避免干擾觀看體驗。這項功能還會挑選適用於每部影片的一項宣傳活動。
-
-
video
資源的snippet.title
和snippet.categoryId
屬性定義已更新,以便明確說明 API 處理videos.update
方法呼叫的方式。如果您呼叫該方法來更新video
資源的snippet
部分,則必須為這兩個屬性設定值。如果您嘗試更新
video
資源的snippet
部分,且並未為這兩個屬性設定值,API 會傳回invalidRequest
錯誤。該錯誤的說明也已更新。 -
video
資源的contentDetails.contentRating.oflcRating
屬性能識別紐西蘭電影及文學分類局的影片分級,現在支援兩種全新分級:oflcRp13
和oflcRp16
。這些分別對應至RP13
和RP16
評分。 -
channelBanners.insert
方法現在支援下列錯誤:錯誤類型 錯誤詳情 說明 badRequest
bannerAlbumFull
頻道擁有者的 YouTube 頻道圖片相簿有太多圖片。頻道擁有者應前往 http://photos.google.com,前往相簿頁面,然後從相簿中移除部分圖片。
2014 年 9 月 12 日
這次更新的修改如下:
-
除了指定資源部分的費用外,呼叫
search.list
方法的配額費用已從 1 個單位變更為 2 個單位。
2014 年 8 月 13 日
這次更新的修改如下:
-
subscriptions.insert
方法現在支援下列錯誤:錯誤類型 錯誤詳情 說明 badRequest
subscriptionLimitExceeded
在此要求中找到的訂閱者已超出訂閱頻率限制。過幾小時後,你可以再嘗試訂閱。
2014 年 8 月 12 日
這次更新的修改如下:
-
「將應用程式遷移至 YouTube Data API (v3)」這份新指南說明如何使用 YouTube Data API (v3),執行 YouTube Data API (v2) 中的功能。舊版 API 已於 2014 年 3 月 4 日正式淘汰。本指南旨在協助您將仍使用 v2 API 的應用程式遷移至最新的 API 版本。
2014 年 7 月 8 日
這次更新的修改如下:
-
playlists.insert
方法現在支援下列錯誤:錯誤類型 錯誤詳情 說明 badRequest
maxPlaylistExceeded
如果頻道的播放清單數量已達上限,因此無法建立播放清單,就會發生這個錯誤。
2014 年 6 月 18 日
這次更新的修改如下:
-
每個 API 方法的說明已更新,加入呼叫該方法所產生的配額費用。同樣地,我們更新了
part
參數的定義,指定可在 API 呼叫中擷取的每個部分的配額費用。舉例來說,呼叫subscriptions.insert
方法的配額成本約為 50 個單位。subscription
資源也包含三個部分 (snippet
、contentDetails
和subscriberSnippet
),每個部分的成本為兩個單位。請注意,配額費用可能會在無預警的情況下變動。
-
video
資源現在支援 43 個新的內容分級系統,可識別影片從各國分級機構取得的分級。新支援的評分系統包括:阿根廷、奧地利、比利時、保加利亞、智利 (電視)、智利 (電影)、捷克共和國、哥倫比亞、丹麥、埃及、愛沙尼亞、芬蘭、法國、希臘、香港、冰島、印尼、愛爾蘭、以色列、義大利、肯亞、拉脫維亞、盧森堡、馬來西亞、馬爾地夫、馬爾他、荷蘭、奈及利亞、挪威、秘魯、菲律賓、葡萄牙、羅馬尼亞、新加坡、斯洛伐克、南非、瑞典、瑞士、台灣、泰國和委內瑞拉。
2014 年 5 月 28 日
這次更新的修改如下:
-
search.list
方法現在支援location
和locationRadius
參數,可讓您搜尋與地理位置相關聯的影片。要求必須同時為這兩個參數指定值,才能根據位置擷取結果;如果要求只包含這兩個參數之一,API 就會傳回錯誤。-
location
參數會指定圓形地理區域中心點的經緯度座標。 -
locationRadius
參數會指定影片相關位置的距離範圍上限,如此才能讓系統在搜尋結果中顯示影片。
-
2014 年 5 月 13 日
這次更新的修改如下:
-
已更新
channel
資源的invideoPromotion.items[]
屬性,提醒你,頻道通常只能設定一個促銷商品。如果嘗試插入的宣傳項目過多,API 會傳回tooManyPromotedItems
錯誤,並附上 HTTP400
狀態碼。 -
channelSection
資源現在可以包含幾種新類型精選內容的資訊。channelSection
資源的snippet.type
屬性現在支援以下值:postedPlaylists
:頻道擁有者發布至頻道活動動態消息的播放清單postedVideos
:頻道擁有者發布至頻道活動動態消息的影片subscriptions
:頻道擁有者訂閱的頻道
-
video
資源的新contentDetails.contentRating.ifcoRating
屬性會識別愛爾蘭電影分類辦公室 (Irish Film Classification Office) 接收到的分級。 -
更新
watermark
資源position.cornerPosition
屬性的定義,將浮水印一律顯示在播放器右上角。 -
search.list
方法的q
參數定義已更新,指出查詢字詞可使用布林 NOT (-
) 運算子,排除與特定搜尋字詞相關聯的影片。這個值也可以使用布林 OR (|
) 運算子,找出與多個搜尋字詞中任一字詞相關的影片。 -
系統已更新
pageInfo.totalResults
屬性的定義,以便在search.list
呼叫的 API 回應中傳回值,並指出該值為近似值,可能不代表確切值。此外,最大值為 1,000,000。請不要使用這個值建立分頁連結。請改用nextPageToken
和prevPageToken
屬性值,判斷是否要顯示分頁連結。 -
watermarks.set
和watermarks.unset
方法已更新,以反映 API 會針對這些方法的成功要求傳回 HTTP204
回應碼。
2014 年 5 月 2 日
這次更新的修改如下:
-
新的
i18nLanguage
資源會指出 YouTube 網站支援的應用程式語言。應用程式語言也稱為使用者介面語言。針對 YouTube 網站,系統可根據 Google 帳戶設定、瀏覽器語言或 IP 位置,自動選取應用程式語言,使用者也可以在 YouTube 網站頁尾手動選取所需的 UI 語言。API 支援一個列出支援的應用程式語言的方法。在呼叫
videoCategories.list
和guideCategories.list
等 API 方法時,可使用支援的語言做為hl
參數的值。 -
新的
i18nRegion
資源識別出可讓 YouTube 使用者選取偏好的內容區域。內容區域也稱為內容地區。在 YouTube 網站上,系統會根據 YouTube 網域或使用者的 IP 位置等推論法自動選取內容區域,使用者也可以在 YouTube 網站頁尾手動選取所需的內容區域。這個 API 支援列出支援的內容區域。在呼叫
search.list
、videos.list
、activities.list
和videoCategories.list
等 API 方法時,您可以使用支援的區域代碼做為regionCode
參數的值。
2014 年 4 月 7 日
這次更新的修改如下:
-
新的
channelSection
資源包含頻道選擇推薦的一組影片資訊。舉例來說,您可以在版面中宣傳頻道最新上傳的內容、最熱門的上傳影片,或是一或多個播放清單中的影片。這個 API 支援用於列出、插入、更新或刪除頻道專區的方法。您可以指定特定頻道 ID,或指定一組專屬頻道版面 ID 清單,藉此擷取已驗證使用者頻道的頻道版面清單。
錯誤說明文件也已更新,用來說明 API 專門針對這些新方法支援的錯誤訊息。
-
已更新
video
資源fileDetails
物件的定義,說明只有在影片的processingDetails.fileDetailsAvailability
屬性值為available
時,才會傳回該物件。同樣地,我們也更新了
video
資源的suggestions
物件定義,說明只有在影片的processingDetails.tagSuggestionsAvailability
屬性或其processingDetails.editorSuggestionsAvailability
屬性值為available
時,系統才會傳回該物件。 -
videos.insert
和videos.update
方法的說明文件已更新,反映出呼叫這些方法時可設定status.publishAt
屬性。 -
channel
資源invideoPromotion
物件的定義已更新,說明只有頻道擁有者才能擷取物件。 -
videos.rate
方法的參數清單已更新,以反映該方法實際上不支援onBehalfOfContentOwner
參數。此是說明文件錯誤,因為設定此參數的videos.rate
要求會傳回500
錯誤。
2014 年 3 月 31 日
這次更新的修改如下:
-
video
資源的全新status.publishAt
屬性可讓你指定私人影片的發布日期和時間。影片的隱私權狀態為private
,且影片從未發布過,才能設定這項屬性。這項新屬性不受淘汰政策約束。
2014 年 3 月 13 日
這次更新的修改如下:
-
API 現在支援
channel
資源的contentOwnerDetails
部分。新部分包含與頻道相關聯的 YouTube 合作夥伴相關資料,包括與頻道連結的內容擁有者 ID,以及內容擁有者與頻道連結的日期和時間。請注意,這個新措施不適用廢止政策。 -
說明文件現在列出下列屬性支援的字元長度上限:
資源 屬性 長度上限 channel
invideoPromotion.items[].customMessage
40 個半形字元 video
snippet.title
100 個字元 (或 50 個全形字元) video
snippet.description
5000 個位元組 video
snippet.tags
500 個半形字元,請注意,屬性值是一份清單,清單中項目之間的逗號都會計入限制。 -
channel
資源的brandingSettings.watch.featuredPlaylistId
屬性已淘汰。如果您嘗試設定該值,API 會傳回錯誤。 -
錯誤說明文件現在會指定每種錯誤類型的 HTTP 回應代碼。
-
這個 API 現在支援下列錯誤:
錯誤類型 錯誤詳情 說明 badRequest (400)
invalidCriteria
如果要求指定了無法搭配使用的篩選器參數, channels.list
方法會傳回此錯誤。badRequest (400)
channelTitleUpdateForbidden
如果您嘗試更新管道的 brandingSettings
部分並變更brandingSettings.channel.title
屬性的值,channels.update
方法就會傳回這個錯誤。(請注意,如果省略屬性,API 不會傳回錯誤)。badRequest (400)
invalidRecentlyUploadedBy
如果 invideoPromotion.items[].id.recentlyUploadedBy
屬性指定的頻道 ID 無效,channels.update
方法就會傳回這個錯誤。badRequest (400)
invalidTimingOffset
如果 invideoPromotion
部分指定了無效的時間偏移,channels.update
方法會傳回此錯誤。badRequest (400)
tooManyPromotedItems
如果 invideoPromotion
部分指定的數量超過促銷商品數量上限,channels.update
方法就會傳回這項錯誤。forbidden (403)
promotedVideoNotAllowed
如果 invideoPromotion.items[].id.videoId
屬性指定的是找不到或無法用於宣傳商品的影片 ID,channels.update
方法會傳回此錯誤。forbidden (403)
websiteLinkNotAllowed
如果 invideoPromotion.items[].id.websiteUrl
屬性指定的網址不允許,channels.update
方法會傳回這項錯誤。required (400)
requiredTimingType
如果要求未指定 YouTube 應顯示宣傳項目的預設時間設定, channels.update
方法就會傳回此錯誤。required (400)
requiredTiming
channels.update
方法必須為每個宣傳商品指定invideoPromotion.items[].timing
物件。required (400)
requiredWebsiteUrl
channels.update
方法必須為每個已提升的項目指定invideoPromotion.items[].id.websiteUrl
屬性。badRequest (400)
invalidPublishAt
如果要求中繼資料指定的排定發布時間無效, videos.insert
方法會傳回這個錯誤。
2014 年 3 月 4 日
這次更新的修改如下:
-
YouTube Data API 3.0 版現已受《YouTube API 服務條款》中所述廢止政策的規範。請注意,如果頁面上列出受淘汰政策影響的 API,該頁面會特別排除部分 v3 API 功能必須遵守相關政策。
2013 年 12 月 5 日
這次更新的修改如下:
-
search.list
方法的說明文件已更新,可正確反映您在提交搜尋要求時,不需要僅指定一個篩選器參數的值。您可以為零個篩選器參數或一個篩選器參數設定值。 -
search.list
方法參數的定義已更新,指出如果您也為下列任一參數指定值,則必須將type
參數的值設為video
:eventType
videoCaption
videoCategoryId
videoDefinition
videoDimension
videoDuration
videoEmbeddable
videoLicense
videoSyndicated
videoType
-
上傳的頻道橫幅圖片大小已縮減為 2048 像素 x 1152 像素。(先前最小尺寸為 2120 x 1192 像素)。此外,請注意,
channel
資源說明文件會指定透過 API 放送的所有橫幅圖片的最大尺寸。舉例來說,電視應用程式的brandingSettings.image.bannerTvImageUrl
圖片大小上限為 2120 x 1192 像素,但實際圖片大小則為 2048 x 1152 像素。YouTube 說明中心提供了更多指引,說明如何最佳化頻道圖片,以便在各種裝置上呈現最佳效果。 -
已更新部分
channel
資源屬性定義,以反映下列資訊:brandingSettings.channel.description
屬性的值長度上限為 1000 個半形字元。brandingSettings.channel.featuredChannelsTitle
屬性的長度上限為 30 個半形字元。brandingSettings.channel.featuredChannelsUrls[]
屬性現在最多可列出 100 個頻道。- 如果設定
brandingSettings.channel.unsubscribedTrailer
屬性值,則必須指定頻道擁有者擁有的公開或不公開影片的 YouTube 影片 ID。
-
channels.update
方法現在支援invideoPromotion.items[].promotedByContentOwner
屬性的更新作業。該屬性會指出在顯示促銷活動時,是否要顯示內容擁有者的名稱。只有在使用onBehalfOfContentOwner
參數代表內容擁有者提出屬性值設定 API 要求時,才能設定此屬性。 -
playlistItems.list
和playlistItems.insert
方法現在支援onBehalfOfContentOwner
參數,其他方法也已支援這項參數。 -
contentDetails.contentRating.acbRating
屬性現在可為電影指定澳洲分級委員會 (ACB) 或澳洲通訊及媒體局 (ACMA) 的兒童電視節目分級。 -
新的
contentDetails.contentRating.catvRating
和contentDetails.contentRating.catvfrRating
屬性可分別識別影片在加拿大電視分級制度和法語 Régie du cinéma 分級制度 (魁北克使用) 下的分級。 -
videoCategory
資源的新snippet.assignable
屬性會指出更新的影片或新上傳的影片是否可與該影片類別建立關聯。 -
我們已為下列方法新增程式碼範例:
activities.insert
(前往)channelBanners.insert
(Python)channels.update
(Python)playlistItems.list
(前往)search.list
(前往)thumbnails.set
(Java)videos.insert
(前往)
2013 年 10 月 24 日
這次更新的修改如下:
-
這個 API 包含兩項額外功能,可協助您尋找及推薦直播內容:
搜尋結果中的新
snippet.liveBroadcastContent
屬性會指出影片或頻道資源是否有現場直播內容。有效的屬性值包括upcoming
、active
和none
。-
video
資源的新snippet.liveBroadcastContent
屬性會指出影片是否為即將開始或正在進行的現場直播。以下清單說明屬性可能的值:upcoming
:影片尚未開始的現場直播。active
- 影片正在進行現場直播。none
:影片不是即將播出或正在進行的直播。這是指在 YouTube 上仍可觀看的已播完廣播的屬性值。
-
video
資源的新liveStreamingDetails
屬性是包含直播影片廣播中繼資料的物件。如要擷取這項中繼資料,請在part
參數值的資源部分清單中加入liveStreamingDetails
。中繼資料包含下列新屬性:liveStreamingDetails.actualStartTime
:廣播實際開始的時間。(在廣播的狀態為active
時,就會顯示這個值)。liveStreamingDetails.actualEndTime
:廣播實際結束的時間。(這個值會在廣播結束後出現)。liveStreamingDetails.scheduledStartTime
:預定開始播送的時間。liveStreamingDetails.scheduledEndTime
:播送的結束時間。如果屬性值為空白,或是沒有屬性,則直播會安排無限期開始直播。liveStreamingDetails.concurrentViewers
:觀看直播的觀眾人數。
如要擷取這項中繼資料,請在呼叫
videos.list
、videos.insert
或videos.update
方法時,在part
參數值中加入liveStreamingDetails
。
請注意,我們還在 2013 年 10 月 1 日推出了兩項用於辨識現場直播內容的功能,也就是
search.list
方法的eventType
參數,以及搜尋結果的snippet.liveBroadcastContent
屬性。 -
-
videos.insert
方法現在支援notifySubscribers
參數,該參數指出 YouTube 是否應向訂閱影片頻道的使用者傳送新影片的通知。這個參數的預設值是True
,表示訂閱者會在新上傳影片時收到通知。不過,如果要上傳多部影片的頻道擁有者,建議您將這個值設為False
,避免系統傳送新影片時通知頻道訂閱者。 -
更新
channels.update
方法時可修改的屬性清單,加入invideoPromotion.items[].customMessage
和invideoPromotion.items[].websiteUrl
屬性。此外,清單已經過修改,識別可修改的brandingSettings
屬性。這些brandingSettings
屬性已經可以修改,因此說明文件異動不會反映 API 現有功能的變更。 -
playlists.insert
、playlists.update
和playlists.delete
方法現在支援onBehalfOfContentOwner
參數,已經可支援其他幾種方法。 -
playlists.insert
方法現在支援onBehalfOfContentOwnerChannel
參數,其他方法已支援此參數。 -
video
資源的contentDetails.contentRating.tvpgRating
屬性現在支援pg14
值,對應至TV-14
評分。 -
已修正做為搜尋結果的一部分
snippet.liveBroadcastContent
屬性的定義,以反映live
是有效的屬性值,但active
並非有效的屬性值。 -
video
資源的contentDetails.contentRating.mibacRating
屬性現在支援兩種額外評分:mibacVap
(VAP) - 兒童應由成人陪同觀賞。mibacVm6
(V.M.6) - 僅限 6 歲以上觀眾觀看。mibacVm12
(V.M.12) – 限年滿 12 歲的觀眾觀看。
-
channel
資源的新invideoPromotion.items[].promotedByContentOwner
屬性會指出在顯示宣傳活動時,是否要顯示內容擁有者的名稱。只有在代表內容擁有者提出設定值的 API 要求時,才能設定這個欄位。詳情請參閱onBehalfOfContentOwner
參數。
2013 年 10 月 1 日
這次更新的修改如下:
-
channel
資源的新auditDetails
物件包含頻道資料,多頻道聯播網 (MCN) 會在判斷是否接受或拒絕特定頻道時評估這些資料。請注意,任何擷取這項資源部分的 API 要求都必須提供包含https://www.googleapis.com/auth/youtubepartner-channel-audit
範圍的授權權杖。此外,當 MCN 決定接受或拒絕頻道時,或在提出代碼核發後的兩週內,你就必須先撤銷使用該範圍的所有權杖。 -
channel
資源的invideoPromotion.items[].id.type
屬性現在支援recentUpload
值,表示所宣傳的項目是指定頻道最近上傳的影片。根據預設,頻道會與設定影片內宣傳資料的頻道相同。不過,只要將新的
invideoPromotion.items[].id.recentlyUploadedBy
屬性值設為該頻道的頻道 ID,就能宣傳其他頻道最近上傳的影片。 -
channel
資源包含三個新屬性 (brandingSettings.image.bannerTvLowImageUrl
、brandingSettings.image.bannerTvMediumImageUrl
、brandingSettings.image.bannerTvHighImageUrl
),用於指定電視應用程式頻道頁面上橫幅圖片的網址。 -
搜尋結果中的新
snippet.liveBroadcastContent
屬性會指出影片或頻道資源是否有現場直播內容。有效的屬性值為upcoming
、active
和none
。- 對於
video
資源,如果值為upcoming
,表示影片是尚未開始的直播,如果值為active
,表示影片是正在進行的直播。 - 如果是
channel
資源,值為upcoming
表示頻道已安排尚未開始的直播,值為acive
表示頻道正在進行現場直播。
- 對於
-
在
watermark
資源中,targetChannelId
屬性已從物件變更為字串。targetChannelId
屬性現在會指定該值本身,而不是浮水印圖片所連結頻道 YouTube 頻道 ID 的子屬性。因此,該資源的targetChannelId.value
屬性已遭移除。 -
thumbnails.set
方法現在支援onBehalfOfContentOwner
參數,其他方法已支援此參數。 -
search.list
方法現在支援eventType
參數,該參數會限制搜尋只傳回活動、即將進行或已完成的廣播事件。 -
新的
contentDetails.contentRating.mibacRating
屬性可識別影片從義大利文化遺產、文化活動和旅遊部 (MiBACT) 獲得的分級。 -
這個 API 現在支援下列錯誤:
錯誤類型 錯誤詳情 說明 badRequest
invalidImage
如果提供的圖片內容無效, thumbnails.set
方法會傳回此錯誤。forbidden
videoRatingDisabled
如果影片擁有者已停用該影片的評分功能, videos.rate
方法就會傳回這個錯誤。
2013 年 8 月 27 日
這次更新的修改如下:
-
新的
watermark
資源可識別在播放指定頻道影片時顯示的圖片。您也可以指定圖片所連結的目標頻道,以及時間詳細資料,以決定浮水印在影片播放期間的時機,以及顯示的時間長度。watermarks.set
方法會上傳並設定頻道的浮水印圖片。watermarks.unset
方法會刪除頻道的浮水印圖片。錯誤說明文件會描述 API 專門針對
watermarks.set
和watermarks.unset
方法支援的錯誤訊息。 -
channel
資源的新statistics.hiddenSubscriberCount
屬性含有布林值,表示是否要隱藏頻道的訂閱人數。因此,如果頻道的訂閱人數可以公開顯示,則屬性值為false
。 -
playlists.list
方法現在支援onBehalfOfContentOwner
和onBehalfOfContentOwnerChannel
參數。這兩種參數已經支援其他幾種方法。 -
videos.list
方法現在支援regionCode
參數,可識別應擷取圖表的內容區域。這個參數只能與chart
參數搭配使用。參數值為 ISO 3166-1 alpha-2 國家/地區代碼。 -
error documentation
說明下列新的常見要求錯誤,如果使用多種 API 方法,就有可能發生這種錯誤:錯誤類型 錯誤詳情 說明 forbidden
insufficientPermissions
為請求提供的 OAuth 2.0 權杖相關聯的範圍不足,無法存取所要求的資料。
2013 年 8 月 15 日
這次更新的修改如下:
-
channel
資源的invideoPromotion
物件包含下列全新和更新後的屬性:-
API 現已支援指定網站做為宣傳項目的功能。如要這樣做,請將
invideoPromotion.items[].id.type
屬性值設為website
,並使用新的invideoPromotion.items[].id.websiteUrl
屬性指定網址。您也可以使用新的invideoPromotion.items[].customMessage
屬性定義促銷活動要顯示的自訂訊息。連結可以是關聯網站、商家網站或社群網站。如要進一步瞭解如何為內容啟用連結,請參閱 YouTube 說明中心的相關網站和商家網站操作說明。
加入宣傳連結,即表示您同意這些連結不得將流量重新導向至未授權的網站,且符合 YouTube 的 AdWords 政策、YouTube 廣告政策、YouTube《社群規範》和《YouTube 服務條款》。
-
與影片播放期間顯示宣傳項目的時間設定相關的屬性已重新結構化:
-
invideoPromotion.timing
物件已移至invideoPromotion.items[].timing
。這個物件現在可讓您自訂invideoPromotion.items[]
清單中每個宣傳項目的時間資料。 -
新的
invideoPromotion.defaultTiming
物件會指定促銷活動的預設時間設定。這些設定會定義促銷項目在頻道任一部影片播放期間顯示的時機。您可以使用invideoPromotion.items[].timing
物件,為任何指定的宣傳項目覆寫預設時間。 -
新的
invideoPromotion.items[].timing.durationMs
屬性可指定促銷活動應顯示的時間長度 (以毫秒為單位)。invideoPromotion.defaultTiming
物件也包含durationMs
欄位,用於指定宣傳項目的預設顯示時間長度。
-
-
invideoPromotion.items[].type
和invideoPromotion.items[].videoId
屬性都已移至invideoPromotion.items[].id
物件。
-
-
subscriptions.list
方法現在支援onBehalfOfContentOwner
和onBehalfOfContentOwnerChannel
參數。這兩種參數已經支援其他幾種方法。 -
在
thumbnails.set
要求的 API 回應中,kind
屬性值已從youtube#thumbnailListResponse
變更為youtube#thumbnailSetResponse
。 -
已為下列方法新增程式碼範例:
channels.update
(Java、Python)playlists.insert
(.NET、PHP)subscriptions.insert
(PHP、Python)thumbnails.set
(PHP、Python)videos.insert
(PHP)videos.list
(PHP)videos.rate
(Python)videos.update
(Java、PHP、Python)
請注意,
playlistItems.insert
方法的 Python 範例也已移除,因為該範例所示的功能現在由videos.rate
方法處理。 -
error documentation
說明下列新的要求內容錯誤,任何支援mine
要求參數的 API 方法都可能發生這個錯誤:錯誤類型 錯誤詳情 說明 badRequest
invalidMine
如果已驗證的使用者是 YouTube 合作夥伴,您就無法在請求中使用 mine
參數。您應移除mine
參數、移除onBehalfOfContentOwner
參數來驗證 YouTube 使用者,或提供onBehalfOfContentOwnerChannel
參數 (如果有呼叫的方法可用) 做為合作夥伴的管道之一。
2013 年 8 月 8 日
這次更新的修改如下:
-
YouTube Data API 入門指南指南中的配額用量一節已更新,將反映影片上傳的配額費用從約 1,6000 個單位變更為約 1600 個單位。
2013 年 7 月 30 日
這次更新的修改如下:
-
在
channelBanner
資源中,kind
屬性的值已從youtube#channelBannerInsertResponse
變更為youtube#channelBannerResource
。系統會在回應channelBanners.insert
要求時傳回此資源。 -
channel
資源的新brandingSettings.channel.profileColor
屬性會指定醒目顏色,以補足頻道的內容。屬性值是井字號 (#
) 後面接著六個字元的十六進制字串,例如#2793e6
。 -
API 現在支援指定訂閱是適用於頻道所有的活動,或只適用於新上傳的影片。
subscription
資源的新contentDetails.activityType
屬性會識別訂閱者會收到通知的活動類型。有效的屬性值為all
和uploads
。 -
videos.list
方法支援新的參數,可擷取 YouTube 上最熱門影片的排行榜:chart
參數可指定要擷取的圖表。目前唯一支援的值是mostPopular
。請注意,chart
參數是篩選器參數,也就是說,您無法在同一項要求中使用其他篩選器參數 (id
和myRating
) 與該參數搭配使用。videoCategoryId
參數代表應擷取圖表的影片類別。這個參數只能與chart
參數搭配使用。根據預設,圖表不侷限於特定類別。
-
video
資源的新topicDetails.relevantTopicIds[]
屬性提供與影片或相關內容相關的 Freebase 主題 ID 清單。片中可能會提及或出現這類主題。 -
video
資源的recordingDetails.location.elevation
屬性已重新命名為recordingDetails.location.altitude
,而fileDetails.recordingLocation.location.elevation
屬性則已重新命名為fileDetails.recordingLocation.location.altitude
。 -
video
資源的contentDetails.contentRating
物件會指定影片在各種分級配置 (包括 MPAA 分級、TVPG 分級等) 下收到的分級。API 現在支援每個分級系統,可支援影片尚未分級的分級值。請注意,在 MPAA 分級中,「未分級」的分級經常用於識別未剪輯的電影版本,而該電影的剪輯版本取得的是官方分級。 -
video
資源的新contentDetails.contentRating.ytRating
屬性可識別年齡限制內容。如果 YouTube 發現影片含有不適合未滿 18 歲使用者的內容,屬性值會是ytAgeRestricted
。如果缺少這個屬性,或是屬性值為空白,表示系統尚未將內容標示為年齡限制。 -
channels.list
方法的mySubscribers
參數已淘汰。使用subscriptions.list
方法及其mySubscribers
參數,擷取已驗證使用者頻道的訂閱者清單。 -
channelBanners.insert
、channels.update
、videos.getRating
和videos.rate
方法現在都支援onBehalfOfContentOwner
參數。這個參數表示已驗證的使用者是參數值中指定的內容擁有者。 -
channels.update
方法的說明文件已更新,反映出該方法可用於更新channel
資源的brandingSettings
物件及其子項屬性。說明文件現在也列出可為channel
資源的invideoPromotion
物件設定的更新屬性清單。 -
error documentation
說明下列新的錯誤:錯誤類型 錯誤詳情 說明 forbidden
accountDelegationForbidden
這類錯誤並非特定 API 方法特有。表示已驗證的使用者無權代表指定的 Google 帳戶處理事務。 forbidden
authenticatedUserAccountClosed
這個錯誤並非針對特定 API 方法所造成。這表示已驗證的使用者 YouTube 帳戶已關閉。如果使用者是代表其他 Google 帳戶執行動作,則這個錯誤表示其他帳戶已經關閉。 forbidden
authenticatedUserAccountSuspended
這個錯誤並非針對特定 API 方法所造成。這表示已驗證的使用者 YouTube 帳戶已遭停權。如果使用者是代表其他 Google 帳戶執行操作,則這項錯誤表示該帳戶已遭到停權。 forbidden
authenticatedUserNotChannel
這個錯誤並非針對特定 API 方法所造成。這表示 API 伺服器無法識別與 API 要求相關聯的管道。如果要求已獲授權,且使用 onBehalfOfContentOwner
參數,請一併設定onBehalfOfContentOwnerChannel
參數。forbidden
cmsUserAccountNotFound
這個錯誤並非針對特定 API 方法所造成。CMS 使用者不得代表指定的內容擁有者採取行動。 notFound
contentOwnerAccountNotFound
這個錯誤並非針對特定 API 方法所造成。找不到指定的內容擁有者帳戶。 badRequest
invalidPart
這類錯誤並非特定 API 方法特有。要求的 part
參數會指定無法同時寫入的部分。badRequest
videoChartNotFound
要求指定不受支援或無法使用的影片圖表時, videos.list
方法會傳回此錯誤。notFound
videoNotFound
videos.update
方法會傳回這個錯誤,表示找不到您要更新的影片。請檢查要求主體中id
屬性的值,確保值正確無誤。
2013 年 6 月 10 日
這次更新的修改如下:
-
channels.list
方法的新forUsername
參數可讓您指定 YouTube 使用者名稱,藉此擷取頻道的相關資訊。 -
activities.list
方法現在支援regionCode
參數,可指示 API 傳回與指定國家/地區相關的結果。如果授權使用者之前的 YouTube 活動資訊不足,無法產生活動動態消息,YouTube 就會採用這個值。 -
播放清單資源現在包含
snippet.tags
屬性。資源只會傳回給擷取自己播放清單相關資料的授權使用者。授權使用者也可以在呼叫playlists.insert
或playlists.update
方法時設定播放清單標記。 -
onBehalfOfContentOwner
參數先前支援channels.list
和search.list
方法,現在也支援videos.insert
、videos.update
和videos.delete
方法。請注意,如果您在呼叫videos.insert
方法時使用這個參數,請求也必須為新的onBehalfOfContentOwnerChannel
參數指定值,以識別要新增影片的頻道。頻道必須連結至onBehalfOfContentOwner
參數指定的內容擁有者。這個參數表示要求的授權憑證可識別 YouTube CMS 使用者,該使用者會代表參數值中指定的內容擁有者行事。使用者驗證的 CMS 帳戶必須連結至指定的 YouTube 內容擁有者。
這個參數適用於擁有及管理許多不同 YouTube 頻道的內容合作夥伴。有了這個參數,合作夥伴只需驗證一次,就能取得所有影片和頻道資料,不必為每個頻道提供驗證憑證。
針對此版本,參數現在可讓內容合作夥伴在合作夥伴擁有的任一 YouTube 頻道中插入、更新或刪除影片。
-
error documentation
說明下列新的錯誤:錯誤類型 錯誤詳情 說明 forbidden
insufficientCapabilities
這類錯誤並非特定 API 方法特有。這表示呼叫 API 的 CMS 使用者沒有足夠的權限,無法執行要求的作業。這個錯誤與使用 onBehalfOfContentOwner
參數有關,幾種 API 方法都支援此參數。unauthorized
authorizationRequired
當要求使用 home
參數但未獲得適當授權時,activities.list
方法會傳回此錯誤。 -
您已經使用資源的
id
屬性指定頻道 ID,因此channels
資源中的invideoPromotion.channelId
屬性已遭移除。 -
新的使用頻道 ID 指南說明瞭 API 如何使用頻道 ID。如果開發人員是從舊版 API 遷移,且擁有的應用程式需要為
default
使用者要求內容,或需要每個 YouTube 頻道都有專屬使用者名稱,這份指南就特別實用。
2013 年 5 月 22 日
這次更新的修改如下:
-
新的
channelBanners.insert
方法可讓您上傳橫幅圖片,日後可使用channel
資源的新brandingSettings.image.bannerExternalUrl
屬性,將其設為頻道的橫幅圖片。 -
channels.update
方法的說明文件已更新,列出可在呼叫方法時修改的屬性。 -
video
資源說明文件不再將unspecified
列為suggestions.processingErrors[]
、suggestions.processingHints[]
、suggestions.processingWarnings[]
和suggestions.editorSuggestions[]
屬性的有效屬性值。 -
videos.list
方法的maxResults
參數現在的預設值是5
。 -
error documentation
現在會列出channelBanners.insert
和subscriptions.list
方法的錯誤。此頁面也會列出channels.update
方法的多個新錯誤。
2013 年 5 月 14 日
這次更新的修改如下:
2013 年 5 月 10 日
這次更新的修改如下:
-
YouTube 不再識別實驗性 API 功能和服務。因此我們現在提供即將受到淘汰政策影響的 YouTube API 清單。
2013 年 5 月 8 日
這次更新的修改如下:
-
管道資源現在支援
inVideoPromotion
物件,該物件包含與頻道相關聯的促銷廣告活動相關資訊。頻道可以使用影片內宣傳廣告活動,在頻道影片播放期間,在影片播放器中顯示宣傳影片的縮圖。如要擷取這項資料,請在
channels.list
要求的part
參數值中加入invideoPromotion
。 -
新的
channels.update
方法可用來更新頻道的影片內宣傳廣告活動資料。請注意,此方法只支援更新channel
資源的invideoPromotion
部分,目前尚不支援更新該資源的其他部分。
2013 年 5 月 2 日
這次更新的修改如下:
-
頻道資源現在支援
status.isLinked
屬性,這表示頻道資料識別的是已連結至 YouTube 使用者名稱或 Google+ 帳戶的使用者。擁有其中一個連結的使用者,就已擁有公開的 YouTube 身分,而這也是上傳影片等多項操作的必要條件。 -
訂閱資源現在支援
subscriberSnippet
部分。這個物件會封裝訂閱者頻道的片段資料。 -
API 現在支援
videos.getRating
方法,可擷取已驗證使用者給予一或多部影片清單的評分。 -
videos.list
方法的新myRating
參數可讓您擷取已驗證使用者評分為like
或dislike
的影片清單。myRating
參數和id
參數現在都是篩選器參數,也就是說,API 要求必須確切指定其中一個參數。(先前,id
參數是該方法的必要參數)。如果要求嘗試擷取影片評分資訊,但並未取得適當授權,這個方法會傳回
forbidden
錯誤。 -
隨著
myRating
參數的推出,videos.list
方法也已更新為支援分頁。不過請注意,只有使用myRating
參數的要求才支援該分頁參數。(使用id
參數的要求不支援分頁參數和資訊)。-
maxResults
參數會指定 API 可在結果集中傳回的影片數量上限,而pageToken
參數則會標示要擷取的結果集中特定頁面。 -
youtube#videoListResponse
資源會在videos.list
要求的回應中傳回,現在包含pageInfo
物件,其中包含結果總數和目前結果集中包含的結果數量等詳細資料。youtube#videoListResponse
資源也可以包含nextPageToken
和prevPageToken
屬性,每個屬性都會提供符記,可用於擷取結果集中的特定網頁。
-
-
videos.insert
方法支援下列新參數:autoLevels
:將這個參數值設為true
,即可指示 YouTube 自動改善影片的亮度和色彩。stabilize
:將這個參數值設為true
,即可指示 YouTube 調整影片,移除因相機動作而產生的晃動。
-
已將
channelTitle
屬性新增至下列資源的snippet
:playlistItem
:這個屬性會指定新增播放清單項目的頻道名稱。playlist
:屬性可指定建立播放清單的頻道名稱。subscription
:這個屬性會指定訂閱的頻道名稱。
-
已為下列方法新增程式碼範例:
activities.insert
(Ruby)playlistItems.list
(.NET)search.list
(.NET)subscriptions.insert
(Java、Ruby)videos.insert
(.NET、Ruby)
-
subscriptions.list
方法的新mySubscribers
參數可讓您擷取目前已驗證使用者的訂閱者清單。這個參數只能用於適當授權的要求。注意:這項功能旨在取代
channels.list
方法目前支援的mySubscribers
參數。該參數即將淘汰。 -
在
video
資源中,屬性值unspecified
不再是下列任何屬性的可能值: -
含有非預期參數的 API 要求現在會傳回
badRequest
錯誤,且回報的錯誤原因為unexpectedParameter
。 -
當播放清單包含允許的項目數量上限更新時,
playlistItems.insert
方法會傳回錯誤。錯誤現已回報為forbidden
錯誤,錯誤原因為playlistContainsMaximumNumberOfVideos
。
2013 年 4 月 19 日
這次更新的修改如下:
-
新的
videos.rate
方法可讓使用者設定影片的like
或dislike
評分,或是移除影片的評分。錯誤說明文件也已經更新,列出 API 為回應
videos.rate
方法呼叫時可能傳回的錯誤。 -
API 說明文件現已將縮圖圖片識別為獨立資源,全新的
thumbnails.set
方法可讓您將自訂影片縮圖上傳至 YouTube,然後為影片設定縮圖。錯誤說明文件也已經更新,列出 API 為回應
thumbnails.set
方法呼叫時可能傳回的錯誤。請注意,這項異動不會真正影響會傳回縮圖圖片的現有資源。縮圖圖片會以與先前相同的方式在這些資源中傳回,不過說明文件現在會列出 API 可能傳回的不同縮圖大小名稱。
-
channel
資源的新brandingSettings
部分可識別頻道頻道頁面和影片觀賞頁面的設定、文字和圖片。 -
playlistItem
資源包含下列新屬性:-
新的
status
物件會封裝播放清單項目的狀態資訊,status.privacyStatus
屬性則用於識別播放清單項目的隱私權狀態。
-
-
video
資源包含下列新屬性:-
status.publicStatsViewable
屬性會指明觀賞頁面中的延伸影片統計資料是否公開顯示。根據預設,您可以查看這些統計資料,且即使將屬性值設為false
,系統仍會公開顯示影片的觀看次數和評分等統計資料。您可以在呼叫videos.insert
或videos.update
方法時設定此屬性的值。 -
contentDetails.contentRating
物件封裝了影片在各種評分系統中獲得的分級。下表列出 YouTube 支援的分級制度,並提供與各分級制度相關聯的資源連結。屬性定義會指出每個系統支援的分級值。
-
-
playlistItems.update
方法的說明文件已更新,以反映必須在傳送做為要求主體的資源中指定snippet.resourceId
屬性。 -
search.list
方法現在支援下列功能:-
新的
forMine
參數會限制搜尋作業,只擷取已驗證使用者的影片。 -
order
參數現在支援依標題 (order=title
) 的字母順序或影片數量遞減排序結果 (order=videoCount
)。 -
新的
safeSearch
參數會指出搜尋結果是否應包含受限內容。
-
-
videos.insert
方法支援數種新錯誤,如下表所示:錯誤類型 錯誤詳情 說明 badRequest
invalidCategoryId
snippet.categoryId
屬性指定的類別 ID 無效。使用videoCategories.list
方法擷取支援的類別。badRequest
invalidRecordingDetails
metadata specifies invalid recording details.
badRequest
invalidVideoGameRating
要求中繼資料指定的電玩遊戲分級無效。 badRequest
invalidVideoMetadata
要求中繼資料無效。 -
onBehalfOfContentOwner
參數已從videos.update
和videos.delete
方法支援的參數清單中移除。
2013 年 3 月 12 日
這次更新的修改如下:
-
channelTitle
屬性已新增至下列資源的snippet
: -
search.list
方法支援下列新參數:-
channelType
參數可讓您限制搜尋頻道,以便擷取所有頻道或只擷取節目。 -
您可以使用
videoType
參數限制影片搜尋,只擷取所有影片,或只擷取電影或節目集數。
-
-
已更新
video
資源的recordingDetails
部分的定義,是為了注意,只有已設定影片的地理位置資料或錄製時間,才會傳回影片的物件。 -
playlistItems.update
方法現在會傳回invalidSnippet
錯誤,如果 API 要求未指定有效的程式碼片段,就會傳回該錯誤。 -
有些 API 方法支援 YouTube 內容合作夥伴專用的新參數。YouTube 內容合作夥伴包括電影和電視節目公司、唱片公司,以及其他在 YouTube 上發布內容的內容創作者。
-
onBehalfOfContentOwner
參數代表要求的授權憑證可識別 YouTube CMS 使用者,這些使用者皆代表參數值中指定的內容擁有者。使用者驗證的 CMS 帳戶必須連結至指定的 YouTube 內容擁有者。這個參數適用於擁有及管理許多不同 YouTube 頻道的內容合作夥伴。此參數讓這些合作夥伴只要驗證一次,便可存取其所有的影片和頻道資料,而不需要為每個頻道提供驗證憑證。
channels.list
、search.list
、videos.delete
、videos.list
和videos.update
方法都支援這個參數。 -
channels.list
方法支援的managedByMe
參數會指示 API 傳回onBehalfOfContentOwner
參數指定的內容擁有者擁有的所有頻道。 -
search.list
方法支援的forContentOwner
參數會指示 API 將搜尋結果限制為僅包含onBehalfOfContentOwner
參數指定的內容擁有者所擁有的資源。
-
2013 年 2 月 25 日
這次更新的修改如下:
-
這個 API 支援
video
資源的多個新部分和屬性:-
新的
fileDetails
、processingDetails
和suggestions
部分會向影片擁有者提供有關上傳影片的資訊。這類資料對於支援上傳影片的應用程式非常實用,包括:- 處理狀態和進度
- 處理影片時發生的錯誤或其他問題
- 縮圖圖片是否可用
- 改善影片或中繼資料品質的建議
- 原始上傳至 YouTube 檔案的詳細資料
只有影片擁有者才能擷取所有這些部分。以下清單簡要說明這些新部分,
video
資源說明文件則定義了每個部分包含的所有屬性。-
fileDetails
物件包含上傳至 YouTube 的影片檔案相關資訊,包括檔案解析度、時間長度、音訊和視訊編解碼器、串流位元率等等。 -
processingProgress
物件包含 YouTube 處理上傳影片檔案的進度資訊。物件的屬性可識別目前的處理狀態,並預估 YouTube 處理影片所需的剩餘時間。這個部分也會指出影片是否提供不同類型的資料或內容,例如檔案詳細資料或縮圖圖片。這個物件的用途是輪詢,讓影片上傳者可以追蹤 YouTube 處理上傳影片檔案的過程。
-
suggestions
物件包含建議,可找出可改善上傳影片品質或中繼資料的機會。
-
contentDetails
部分包含四個新屬性。系統可能會使用未經驗證的要求擷取這些屬性。dimension
:說明影片是否提供 2D 或 3D 模式。definition
:說明影片提供標準畫質或高畫質。caption
:指出影片是否提供字幕。licensedContent
:指出影片是否含有 YouTube 內容合作夥伴聲明擁有著作權的內容。
-
status
部分包含兩個新屬性。插入或更新影片時,影片擁有者可以設定這兩個屬性的值。這些屬性也可以透過未經驗證的請求擷取。embeddable
:說明影片是否能嵌入其他網站。license
:指定影片授權。有效值為creativeCommon
和youtube
。
-
-
part
參數的定義已針對videos.list
、videos.insert
和videos.update
方法進行更新,以便列出上述新加入的部分,以及不小心遺漏的recordingDetails
部分。 -
channel
資源的新contentDetails.googlePlusUserId
屬性會指定與頻道相關聯的 Google+ 個人資料 ID。這個值可用於產生 Google+ 個人資料的連結。 -
每個縮圖圖片物件現在都會指定圖片的寬度和高度。縮圖圖片目前會在
activity
、channel
、playlist
、playlistItem
、search result
、subscription
和video
資源中傳回。 -
playlistItems.list
現在支援videoId
參數,可與playlistId
參數搭配使用,只擷取代表指定影片的播放清單項目。如果播放清單中找不到該參數識別的影片,API 就會傳回
notFound
錯誤。 -
已移除
channel
資源的snippet.channelId
屬性。資源的id
屬性提供相同的值。
2013 年 1 月 30 日
這次更新的修改如下:
2013 年 1 月 16 日
這次更新的修改如下:
-
程式碼範例現在適用於下方清單顯示的方法和語言:
activities.insert
- JavaplaylistItems.insert
- PythonplaylistItems.list
– Java、JavaScript、PHP、Python、Rubyplaylists.insert
- Java、JavaScript、Pythonsearch.list
- Java、JavaScript、Python、Rubyvideos.insert
– Java
-
activity
資源現在可以回報channelItem
動作,如果 YouTube 將影片新增至自動產生的 YouTube 頻道,就會發生此動作。(YouTube 會透過演算法找出在 YouTube 網站上特別熱門的主題,並自動為這些主題產生頻道)。 -
下列
search.list
參數已更新:q
參數不再指定為篩選條件,也就是說 ....relatedToVideo
參數已重新命名為relatedToVideoId
。published
參數已替換為兩個新參數publishedAfter
和publishedBefore
,說明如下。
-
search.list
方法支援下列新參數:參數名稱 值 說明 channelId
string
傳回指定頻道建立的資源。 publishedAfter
datetime
傳回建立時間晚於指定時間的資源。 publishedBefore
datetime
傳回在指定時間之前建立的資源。 regionCode
string
傳回指定國家/地區的資源。 videoCategoryId
string
篩選影片搜尋結果,只顯示與指定影片類別相關聯的影片。 videoEmbeddable
string
篩選影片搜尋結果,只顯示可在網頁嵌入式播放器中播放的影片。將參數值設為 true
,即可只擷取可嵌入的影片。videoSyndicated
string
篩選影片搜尋結果,只顯示可在 YouTube.com 以外播放的影片。將參數值設為 true
即可只擷取聯播影片。 -
有些 API 資源支援新屬性。下表列出資源及其新屬性:
資源 屬性名稱 值 說明 activity
contentDetails.playlistItem.playlistItemId
string
YouTube 指派的播放清單項目 ID,用於識別播放清單中的項目。 activity
contentDetails.channelItem
object
包含已新增至管道的資源相關資訊的物件。只有在 snippet.type
為channelItem
時,才會出現這個屬性。activity
contentDetails.channelItem.resourceId
object
這個物件會指出新增至管道的資源。與其他 resourceId
屬性一樣,它包含kind
屬性,可指定資源類型,例如影片或播放清單。同時也包含videoId
、playlistId
等數種屬性的其中之一,用來指定該資源的專屬識別 ID。channel
status
object
這個物件封裝了頻道隱私權狀態的相關資訊。 channel
status.privacyStatus
string
頻道的隱私設定。有效值為 private
和public
。playlist
contentDetails
object
這個物件包含播放清單內容的中繼資料。 playlist
contentDetails.itemCount
unsigned integer
播放清單中的影片數量。 playlist
player
object
這個物件包含用於在嵌入式播放器中播放播放清單的資訊。 playlist
player.embedHtml
string
<iframe>
標記,用於嵌入播放播放清單的影片播放器。video
recordingDetails
object
這個物件封裝了可識別或描述影片錄製地點和時間的資訊。 video
recordingDetails.location
object
這個物件包含與影片相關的地理位置資訊。 video
recordingDetails.location.latitude
double
緯度度數。 video
recordingDetails.location.longitude
double
經度度數。 video
recordingDetails.location.elevation
double
位於地球上方的海拔高度 (以公尺為單位)。 video
recordingDetails.locationDescription
string
影片錄製地點的文字說明。 video
recordingDetails.recordingDate
datetime
影片的錄製日期和時間。指定這個值時採用 ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ
) 格式。 -
數個 API 方法的說明文件現在會指出必須在要求主體中指定,或是根據要求主體值進行更新的屬性。下表列出這些方法,以及必要或可修改的屬性。
注意:其他方法的說明文件可能已經列出必要和可修改的屬性。
方法 屬性 activities.insert
必要屬性: snippet.description
snippet.description
contentDetails.bulletin.resourceId
playlists.update
必要屬性: id
playlistItems.update
必要屬性: id
videos.update
必要屬性: id
-
如果您嘗試建立或更新的播放清單,其名稱與同一個頻道中現有的播放清單相同,API 就不會再回報
playlistAlreadyExists
錯誤。 -
多個 API 方法支援新的錯誤類型。下表列出方法和新支援的錯誤:
方法 錯誤類型 錯誤詳情 說明 guideCategories.list
notFound
notFound
找不到 id
參數指定的指南類別。請使用 guideCategories.list 方法擷取有效值的清單。playlistItems.delete
forbidden
playlistItemsNotAccessible
要求未獲得刪除指定播放清單項目的適當授權。 videoCategories.list
notFound
videoCategoryNotFound
找不到 id
參數所識別的影片類別。使用 videoCategories.list 方法,擷取有效值的清單。