回溯相容性指南

每個 YouTube Data API 要求都可以指定 YouTube 用於處理該要求的 API 版本。如果要求未指定 API 版本，YouTube 會使用支援最舊的 API 版本來處理該要求。目前支援的最新版本目前為 1。請注意 API 版本號碼的下列特性：

  • YouTube 得為特定 API 版本進行更新，但該版本沒有指派新的版本號碼。這些回溯相容的更新可能包括選用的 API 功能、錯誤修正，或兩者皆有。

  • API 版本號碼會遞增，代表有與舊有 API 版本不相容的變更。

本文件定義回溯相容性指南，說明特定 API 版本 (上述第一個項目) 的更新內容。這份指南旨在說明以下類型的 API 功能：

  • 這些指南會識別可能改變的 API 功能，即使您並未修改應該用來處理 API 要求的 API 版本也沒問題。您的程式碼應在不中斷的情況下處理這些變更。舉例來說，如果 YouTube 在 API 回應中加入新的 XML 標記，您的程式碼就會忽略這些標記。

  • 這些規範也定義了 YouTube 在更新特定 API 版本時不打算變更的 API 功能。也就是說，只有在 YouTube 發布新的 API 版本時，您的程式碼應該才會有變更，而且您的程式碼不必試圖處理這類變更。

關於這份文件

本文件包含以下章節：

  • 「API 要求」一節定義與 HTTP 要求標頭、API 要求參數、XML 元素名稱 (顯示在 API 要求中) 和格式不正確的 API 要求相關的回溯相容性指南。

  • API 回應一節定義與 XML 元素名稱 (在 API 回應中所示) 相關的回溯相容性指南，以及 XML 標記和屬性在 API 回應中的顯示順序。

  • 「最佳做法」一節列出了將 YouTube API 整合至用戶端應用程式的建議做法。

API 要求

不打算改變的功能

  • 現有的要求參數。

  • 現有的參數值，含有列舉值或這些參數含義。

  • API POST (插入) 或 PUT (更新) 要求中使用的 XML 元素名稱。

  • 各類型 API 要求所需的 HTTP 要求標頭集，也就是說，YouTube 無意新增必要的 HTTP 要求標頭，也不會變更現有的選用要求標頭。

  • 忽略 API 要求中不支援的參數，除非要求使用 strict 參數指示 YouTube 拒絕包含無效要求參數的 API 要求。

功能可能隨時變動

  • YouTube 可能會新增選用要求參數。

  • 針對含有列舉值的現有參數，YouTube 可能會新增新的值。

  • 如果有效參數包含無效參數值，YouTube 可以拒絕您的要求。因此，如果剖析邏輯經過修正，已經因格式過於寬鬆而予以接受的要求，可能會遭到拒絕。

  • YouTube 可能會新增選用的 HTTP 要求標頭。

  • YouTube 可能會在插入或更新資源時變更 (儲存) 保留的資訊。但這類決策不會影響或變更對應 API 要求的語法。

  • YouTube 可能會變更可瀏覽類別組合，或者可以指派新上傳影片的一組類別。

  • 我們會隨時移除或變更未記錄的功能。

API 回應

不打算改變的功能

  • 現有的 XML 標記名稱。

  • 按照媒體 RSS 規格，判斷該規格中定義的元素順序，且會在動態饋給項目中多次出現。例如，如果某個項目包含多個 <media:thumbnail> 標記，則會按照重要性排序。

  • <category> 標記的 term 屬性值，用於識別動態饋給或資訊提供項目所描述的商品項目類型。在 <feed> 或 <entry> 標記中，<id> 標記會指定項目識別的專屬資源，<category> 標記則能指定項目描述的資源類型。對這個 <category> 標記而言，配置屬性的值為 http://schemas.google.com/g/2005#kind，而字詞屬性的值則會指出動態消息項目是否描述影片、播放清單連結、訂閱、聯絡人或其他實體類型。

功能可能隨時變動

  • YouTube 可能會在 API 回應中新增 XML 標記。

  • YouTube 可能會在現有的 XML 標記中加入新屬性。

  • 現有的 API 標記可能會以不同的值重複。舉例來說，YouTube 可以新增具有不同 type 值的 <media:restriction> 新標記，或以另一個 scheme 和 role 新增 <media:credit> 標記。

  • API 回應中的 XML 標記和屬性順序可能會變動。

  • 您可從 API 回應中移除選用子標記。

  • 我們會隨時移除或變更未記錄的功能。

最佳做法

  • 使用 <id> 標記值識別項目。

  • 使用 self 連結擷取項目。

  • 使用 edit 連結來編輯或更新項目。

  • 為影片項目使用 <yt:videoid> 標記值，以取得 YouTube 用來識別該部影片的專屬值。請勿剖析連結中的影片 ID。

  • 使用在 <link>、<content> 和 <gd:feedLink> 標記中識別的網址來瀏覽動態饋給。YouTube 支援有限的一組網址，您可以放心建立這類網址來擷取特定動態饋給。除了下方列出的動態饋給網址之外，請勿建立自己的動態饋給網址，因為這可能會意外停止運作。

    • /feeds/api/videos/<videoid>
    • /feeds/api/users/default
    • /feeds/api/users/default/uploads
    • /feeds/api/users/default/favorites
    • /feeds/api/users/default/contacts
    • /feeds/api/users/default/inbox
    • /feeds/api/users/default/playlists
    • /feeds/api/users/default/subscriptions
    • /feeds/api/users/default/newsubscriptionvideos
    • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (詳情請參閱參考指南)

  • 請勿嘗試在 API 回應中剖析網址中的數字或英數字元識別碼。API 回應含有特定 ID 的標記，可連結到 YouTube 網站上的資源，例如影片 ID (<yt:videoid>) 和使用者名稱 (<name> 和 <media:credit>).

  • 如要提交 API 要求來插入 (POST) 或更新資訊 (PUT) 資訊，請使用要求中的 XML 回應來判斷要求中有哪些標記值確實是由 YouTube 儲存。如同 API 要求的回溯相容性指南所述，YouTube 在插入或更新資源時變更的資訊 (商店) 可能會保留這些資訊，意味著系統可能會忽略要求中的部分標記。

  • 擷取 XML 資訊提供時，請儲存無法辨識的 XML 標記和與資訊提供項目相關的屬性 (如果應用程式允許使用者更新該項目)。如果使用者更新資源，則更新要求中應含有任何無法辨識的標記和屬性。這可確保您的應用程式在更新資源時，不會不小心刪除與新 API 功能相關的資訊。

    以下為最佳做法：

    1. 您的應用程式可讓使用者更新影片說明。
    2. 您的應用程式使用 API 擷取影片項目，但無法辨識這個項目中的其中一個標記。
    3. 使用者修改影片說明。
    4. 您的應用程式必須將完整影片項目傳回 API。項目必須包含步驟 2 中無法辨識的標記；否則可能會刪除這個值。

  • 顯示標記值之前，請確認標記存在且包含非空值。

  • 如上所述，YouTube 可能會為現有的標記或屬性含有列舉值的屬性新增值。根據規則，您的程式碼應剖析具有列舉值的一組 XML 元素的值，然後定義適用於這些值的操作。即使只為該元素列舉一個值，建議採取這項做法。

    例如，<media:credit> 標記可用來識別影片的擁有者。標記 role 屬性的唯一記錄值是 uploader，表示影片是由 YouTube 合作夥伴上傳。根據這項最佳做法建議，應用程式應先驗證標記 role 屬性的值是否確實為 uploader，然後再識別對應的使用者為影片擁有者。(這項措施能確保 YouTube 為影片新增其他類型的抵免額 (例如原創者) 時，無法正確識別您的影片擁有者。)

    • 如果標記含有列舉值，您不認得該標記的值，則應該略過標記出現的完整 <entry>。

    • 假使您無法辨識 scheme 屬性值為 http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat 的 <category> 標記 term 屬性值，則請忽略訂閱資訊提供項目。該特定標記會識別項目所識別的訂閱類型。如果您的應用程式無法辨識訂閱類型，則不應顯示該項目的相關資訊。

    • 如果其他屬性有一組列舉列舉的值，但您無法辨識該屬性的值，則您應忽略出現該屬性的標記。

  • 應用程式程式碼應該隨時會顯示 yt:error 訊息。如果 API 作業失敗，應用程式應找出錯誤，並向使用者顯示有意義的訊息。

  • YouTube 可能會隨時新增新的影片分類類別。YouTube 可能也會更新或淘汰現有的類別。如要擷取現有類別檔案，請前往 http://gdata.youtube.com/schemas/2007/categories.cat。

    • 如果您的應用程式可讓使用者依類別瀏覽影片或上傳影片，每週會擷取更新過的類別檔案。

    • 如果您的應用程式可讓使用者按照類別瀏覽影片，而且如果 API 傳回空白資訊提供以回應類別搜尋，則擷取更新的類別檔案。

    • 如果您的應用程式允許使用者上傳影片，請一併擷取更新的類別檔案，然後再上傳影片，並確認與上傳影片相關聯的類別仍可供指派。詳情請參閱參考指南。(請注意，如果您嘗試將影片指派至不可指派的類別，API 會傳回錯誤訊息，<code> 標記的值為 deprecated)。

  • 在 API 回應中使用 <link> 標記，以識別資訊提供中前一個及/或下一頁的分頁連結。詳情請參閱參考指南中的「分頁結果」一節。