管理樂曲資產

注意：YouTube Content ID API 為 YouTube 內容合作夥伴使用，並未開放所有開發人員或所有 YouTube 使用者存取。如果 Google API 控制台顯示的服務中沒有 YouTube Content ID API，請參閱 YouTube 說明中心，進一步瞭解 YouTube 合作夥伴計畫。

注意：本指南中的資訊僅適用於樂曲資產。

在 YouTube 版權管理系統中，資產代表一項智慧財產。YouTube 可識別不同類型的資產，例如電影、音樂影片、錄音內容和樂曲。

不過，樂曲擁有權和權利非常複雜，YouTube 對樂曲資產會採用兩層式資產模型。這個模型的設計宗旨如下：

  • 每個錄音內容都會與樂曲建立關聯。
  • 內容擁有者通常需要將同一首歌曲或樂曲的發布擁有權套用至不同的錄音內容。

本文概述 YouTube 的樂曲資產模型。並說明在 YouTube Content ID API 方法中使用兩種樂曲資產的方式。

瞭解樂曲資產模型

YouTube 的資產模型定義了兩種樂曲資產的表示法：

  • 詞曲持份代表特定發布商提供的樂曲資產相關資訊。因此，詞曲持份只能識別單一發布商為樂曲提供的中繼資料、擁有權和政策資料。

    一個詞曲持份可以與多個錄音內容建立關聯。

  • 組成檢視畫面代表錄音中內嵌的樂曲資產。每個錄音內容都只會對應至一個樂曲檢視畫面，而樂曲檢視畫面則代表 YouTube 顯示的樂曲相關標準資訊組合。系統會根據所有相關聯的詞曲持份資產資料，決定樂曲觀看次數的中繼資料、擁有權資料和政策。

    樂曲檢視畫面可以對應至零或多個詞曲持份。不過，如果樂曲有多位擁有者，樂曲持份就只會對應至多個樂曲持份。

    請注意，API 可供單一內容擁有者代表一個樂曲的多位擁有者，因此擁有該樂曲的多個持份。例如，數位權利集結網站可能會獲得不同地域對於相同樂曲的權利。匯集商會擁有代表這些權利的不同實體，而這些實體會對應到 YouTube 模型中的不同詞曲持份。不同的詞曲持份仍可能連結至相同的樂曲資料檢視。

下圖說明瞭這個模型。在圖表中：

  • 圓圈屬於錄音內容。
  • 正方形是樂曲觀看次數。
  • 三角形是樂曲持份。每個三角形顏色都代表不同的內容擁有者。正方形中的小三角形會顯示哪些資料合併後，會產生 YouTube 顯示的樂曲相關標準資訊。YouTube 會利用這些資料來計算樂曲的擁有權和政策。

這張圖表顯示錄音、樂曲觀看次數和詞曲持份之間的關係。

兩種資產 ID

YouTube 會為樂曲持份和樂曲觀看次數指派 ID，而且兩者都會視為資產 ID。但在 API 中無法互換。因此，本文件其他部分會使用 shareId 和 viewId 這兩個詞彙來分別參照指派給樂曲持份和樂曲檢視畫面的 ID。

一般來說，在擷取或更新針對資產提供的資訊時，您需要使用 shareId。如要擷取 YouTube 針對資產顯示的一組標準資訊，您將使用 viewId。

當您回到上一節的圖表時，會發現錄音和樂曲觀看次數會以數字標示 (SR1、CV1 等)。這些數字代表錄音內容和樂曲觀看次數之間的 1:1 關係。因此，如要擷取特定錄音內容中樂曲的一組標準資訊，可以使用 viewId 當做該樂曲使用。

另一方面，詞曲持份會以字母 (CSb 等) 標示。這些字母代表不同的內容擁有者。因此，如果你是綠色內容擁有者，並想擷取先前為樂曲資產提供的中繼資料或擁有權資料，可以使用 shareId 擷取這項資訊。

在 API 方法中使用資產 ID

本文件的其餘部分說明個別 API 方法如何處理 shareIds 和 viewIds 做為參數或屬性值使用時。由於 API 方法按字母順序排列，因此建議您先瞭解建立樂曲資產，並將該資產連結至錄音的常見步驟。

  1. 呼叫 assets.insert 方法以建立樂曲資產。API 回應是 asset 資源，其中 id 屬性為 shareId。

  2. 呼叫 ownership.update 方法來設定樂曲持份的擁有權資料。將方法的 assetId 參數設為在步驟 1 中取得的 shareId。

  3. 呼叫 assetMatchPolicy.update 方法來設定詞曲持份的政策資料。這項政策會套用至含有樂曲的已聲明版權影片。將方法的 assetId 參數設為在步驟 1 中取得的 shareId。

  4. 呼叫 assetRelationships.insert 方法，即可識別含有樂曲的錄音檔。在您要插入的 assetRelationship 資源中，將 parentAssetId 屬性設為錄音的資產 ID。將 childAssetId 屬性設為在步驟 1 中取得的 shareId。

  5. 如果您將 viewIds 與 shareIds 的對應關係儲存，可以呼叫 assetRelationships.list 方法，並將 assetId 參數設為錄音的資產 ID，藉此擷取 viewId。結果集中有一項關係，會將錄音的資產 ID 識別為 parentAssetId。在關係中，childAssetId 會識別與步驟 1 中取得的 shareId 對應的 viewId。

建立資產後，您可以使用本文件其他章節討論的方法，擷取、更新或刪除資產。

asset.get/assets.list

assets.get 和 assets.list 方法會擷取資產或資產清單的相關資訊。這兩種方法都可支援同一組要求參數。

其中三個參數 (fetchMatchPolicy、fetchMetadata 和 fetchOwnership) 使用 effective 和 mine 值，說明您要擷取資產的標準資料組，還是想擷取你提供的資產相關資料。這些值是 YouTube 舊樂曲資產模型的一大管控，可將樂曲觀看次數和樂曲持份視為單一實體。

不過，雙層模型仍會支援這些值，且 API 回應的內容取決於參數值以及要求是否提供 shareIds 或 viewIds。請注意，assets.get 方法會使用 assetId 參數指定資產 ID，而 assets.list 方法則使用 id 參數。

下表說明要求參數值如何影響這兩種方法的 API 回應內容。

  • fetchMatchPolicy
    • 如果資產 ID (id 或 assetId 參數) 指定了 shareId：
      • 如果 fetchMatchPolicy 參數為 mine，API 回應會包含內容擁有者授權為樂曲持份設定的 API 要求所適用的政策。
      • 如果 fetchMatchPolicy 參數為 effective，API 就會傳回 400 錯誤。
    • 如果資產 ID 指定了 viewId：
      • 如果 fetchMatchPolicy 參數為 mine，且在授權要求時，內容擁有者只擁有一個連結至觀看 ID 的詞曲持份，則 API 會傳回為該詞曲持份設定的比對政策。
      • 如果 fetchMatchPolicy 參數為 mine，且在授權要求時，擁有連結至資料檢視 ID 的多個樂曲持份，則 API 會傳回 400 錯誤。
      • 如果 fetchMatchPolicy 參數為 effective，API 會傳回組合檢視畫面的標準比對政策。凡是連結至 viewId 的樂曲持份，都會計入比對政策，不論其內容擁有者是否擁有這些持份。
  • fetchMetadata
    • 如果資產 ID 指定了 shareId：
      • 如果 fetchMetadata 參數為 mine，API 回應會包含資產中繼資料，而內容擁有者有權為樂曲持份設定 API 要求。
      • 如果 fetchMetadata 參數為 effective，API 就會傳回 400 錯誤。
    • 如果資產 ID 指定了 viewId：
      • 如果 fetchMetadata 參數為 mine，且在授權要求時，內容擁有者只擁有一個連結至觀看 ID 的詞曲持份，則 API 會傳回為該樂曲持份設定的中繼資料。
      • 如果 fetchMetadata 參數為 mine，且在授權要求時，擁有連結至資料檢視 ID 的多個樂曲持份，則 API 會傳回 400 錯誤。
      • 如果 fetchMetadata 參數為 effective，API 會傳回樂曲檢視畫面的標準中繼資料組合。這個中繼資料彙整了與 viewId 連結的所有樂曲持份，無論其內容擁有者是否擁有這些持份。
  • fetchOwnership
    • 如果資產 ID 指定了 shareId：
      • 如果 fetchOwnership 參數是 mine，則 API 回應會包含內容擁有者為樂曲持份設定的 API 要求所設的擁有權資料。
      • 如果 fetchOwnership 參數為 effective，API 就會傳回 400 錯誤。
    • 如果資產 ID 指定了 viewId：
      • 如果 fetchOwnership 參數為 mine，且在授權要求時，內容擁有者只擁有一個連結至觀看 ID 的詞曲持份，則 API 會傳回為該樂曲持份設定的擁有權資料。
      • 如果 fetchOwnership 參數為 mine，且在授權要求時，擁有連結至資料檢視 ID 的多個樂曲持份，則 API 會傳回 400 錯誤。
      • 如果 fetchOwnership 參數為 effective，API 會傳回組合檢視畫面的標準擁有權資料。凡是與 viewId 連結的所有樂曲持份，都會計入這些資料的擁有權資料，不論這些持份的擁有者為何。
  • fetchOwnershipConflicts
    • 如果資產 ID 指定 shareId，API 會傳回 400 錯誤回應。
    • 如果資產 ID 指定 viewId，API 會傳回與樂曲檢視畫面相關的擁有權衝突清單。

assets.insert

這個方法會建立 asset 資源，而 YouTube 會指派一個專屬 ID，用於識別該資源。這個 ID 是在 API 回應中做為 id 屬性的值傳回，也就是 shareId。

注意：提醒您，shareIds 和 viewIds 只能用於組合素材資源。其他類型的資產不使用雙層式模型來管理資產資料。

asset.update 和 asset.patch

這些方法會更新資產的中繼資料。在兩項要求中，assetId 參數都會識別要更新的資產。此外，在這兩種要求中，要求主體都是 asset 資源，其中 id 的屬性值必須與 assetId 參數值相符。

  • 如果 assetId 參數和 id 屬性指定 shareId，API 要求就會更新指定的樂曲持份。
  • 如果 assetId 參數和 id 屬性指定 viewId，且在授權這項要求的內容擁有者只擁有一個連結至該 viewId 的詞曲持份，API 要求就會更新該詞曲持份。
  • 如果 assetId 參數和 id 屬性指定 viewId，且在授權這項要求的內容擁有者擁有連結至該 viewId 的多個樂曲持份時，API 要求就會傳回 400 錯誤。

assetMatchPolicy.get

這個方法會傳回指定資產定義的比對政策。要求的 assetId 參數可識別資產。

  • 如果 assetId 參數指定 shareId，API 回應會包含資產中繼資料，而內容擁有者有權為樂曲持份設定 API 要求。
  • 如果 assetId 參數指定 viewId，API 就會傳回組合檢視畫面的標準中繼資料組合。這個中繼資料彙整了與 viewId 連結的所有樂曲持份，無論其內容擁有者是否擁有這些持份。

assetMatchPolicy.update 和 assetMatchPolicy.patch

這些方法會更新特定資產的比對政策。要求的 assetId 參數可識別資產。

  • 如果 assetId 參數指定 shareId，API 要求就會更新該詞曲持份的比對政策。
  • 如果 assetId 參數指定 viewId，且在授權要求時，內容擁有者只擁有一個連結至該 viewId 的詞曲持份，API 要求就會更新該詞曲持份的比對政策。
  • 如果 assetId 參數指定 viewId，且在授權要求時，擁有連結至該 viewId 的多個樂曲持份，API 要求就會傳回 400 錯誤。

assetRelationships.list

這個方法會傳回指定資產的資產關係清單。要求的 assetId 參數可識別資產。

  • 如果 assetId 參數指定 shareId，API 回應會包含已連結的錄音資產清單。清單可能包含多個項目。在每個 assetRelationship 資源中，錄音的資產 ID 為 parentAssetId，shareId 則是 childAssetId。
  • 如果 assetId 參數指定 viewId，API 回應會識別連結至該 viewId 的錄音。回應中最多只能含有一項資源。
  • 如果 assetId 參數識別出錄音資產，API 回應可以包含多個關係。
    • 如果錄音的資產 ID 是回傳 assetRelationship 資源中的 parentAssetId，則 childAssetId 會識別與該錄音連結的樂曲檢視畫面 (viewId)。每項錄音內容都有一種這類關係。
    • 如果錄音的資產 ID 是 childAssetId，parentAssetId 就會識別含有該錄音內容的影片，例如音樂影片或 Art Track 影片。每項錄音內容都有多種這種關係。

assetRelationships.insert

這個方法會在兩個資產之間建立關係。可以呼叫此方法來表明您擁有與錄音相連結的樂曲持份。

在要求主體的 assetRelationship 資源中，將 parentAssetId 屬性設為錄音的資產 ID。將 childAssetId 屬性設為 shareId。

assetSearch.list

這個方法會根據資產中繼資料搜尋資產。API 回應包含 assetSearch 資源清單，其中每個資源的 id 屬性都可用來識別資產 ID。id 屬性值實際上是資產 ID。

  • 如果 assetSearch 資源識別了組合，則 id 屬性值將為 shareId。

assetShares.list

這個方法會傳回樂曲檢視畫面的對應，以及組合持份。要求的 assetId 參數可以指定 viewId 或 shareId。

  • 如果 assetId 參數指定 viewId，則 API 回應會包含 assetShare 資源清單。每項資源都會識別一個連結至指定樂曲檢視畫面的詞曲持份，且擁有權屬於授權要求的內容擁有者。

    API 回應可包含多個 assetShare 資源。關於一個 viewId 對應至多個由同一內容擁有者擁有的 shareIds，請參閱本文件的「瞭解樂曲資產模型」一節。

  • 如果 assetId 參數指定 shareId，則 API 回應會包含 assetShare 資源清單。每個資源都會識別與指定樂曲持份相關聯的樂曲檢視畫面。回應中會針對每個詞曲持份連結的錄音內容提供一項資源。(每段錄音內容只會連結至一個樂曲觀看次數)。

claimSearch.list

這個方法會傳回符合指定搜尋條件的聲明清單。方法的 assetId 參數可讓您搜尋與特定資產相關的版權聲明。

  • 如果 API 要求指定了 shareId，API 就會傳回 400 回應代碼。

  • 如果 API 要求指定 viewId，API 會傳回與指定樂曲檢視畫面相關的版權聲明清單，且只會對應至一個錄音資產。

metadataHistory.list

這個方法會傳回所有針對資產提供的中繼資料清單，不受內容擁有者提供的資料影響。要求的 assetId 參數可識別要擷取哪個資產的資產。

  • 如果 API 要求指定了 shareId，API 就會傳回該詞曲持份的最新中繼資料組合。

  • 如果 API 要求指定 viewId，API 會傳回清單，其中每個項目都包含一組最新一組中繼資料，用於任何連結至該樂曲檢視畫面的樂曲持份。

ownership.get

這個方法會傳回指定資產的擁有權資料。要求的 assetId 參數可識別資產。

  • 如果 assetId 參數指定 shareId，API 回應就會包含內容擁有者為詞曲持份授予 API 要求集的擁有權資料。
  • 如果 assetId 參數指定 viewId，API 就會傳回組合檢視畫面的標準擁有權資料組合。回應匯總了針對 viewId 連結的所有詞曲持份提供的擁有權資料，無論這些持份的擁有者為何。

擁有權.update 和擁有權.patch

這些方法會更新特定資產的擁有權資料，要求的 assetId 參數可識別資產。

  • 如果 assetId 參數指定 shareId，API 要求就會更新該詞曲持份的擁有權資料。
  • 如果 assetId 參數指定 viewId，且在授權要求時，內容擁有者只擁有一個連結至該 viewId 的詞曲持份，則 API 要求會更新該詞曲持份的擁有權資料。
  • 如果 assetId 參數指定 viewId，且在授權要求時，擁有連結至該 viewId 的多個樂曲持份，API 要求就會傳回 400 錯誤。

ownershipHistory.list

這個方法會傳回一份清單，列出對資產提供的所有擁有權資料，不受內容擁有者提供的資料影響。要求的 assetId 參數可識別要擷取哪個資產的資產。

  • 如果 API 要求指定 shareId，API 會傳回該詞曲持份的最新擁有權資料組合。

  • 如果 API 要求指定 viewId，API 會傳回清單，其中每個項目都包含一組最新的擁有權資料組合，該資料會針對連結至該樂曲檢視表的任何樂曲持份提供資料。