管理乐曲资产

注意：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

本文档的其余部分将介绍当 shareIds 和 viewIds 用作参数或属性值时，各个 API 方法会如何处理这些 ID。由于 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。

创建资源后，您可以使用本文档其余部分讨论的任一方法来检索、更新或删除资源。

assets.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，并且授权该请求的内容所有者仅拥有 1 项与该数据视图 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，并且授权该请求的内容所有者只有 1 份已关联到相应视图 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，而授权该请求的内容所有者仅拥有 1 份已关联到相应数据视图 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 仅用于组合素材资源。其他类型的素材资源不会使用双层模型来管理素材资源数据。

assets.update 和 assets.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 关联的录音。响应最多可包含 1 项资源。
  • 如果 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 会返回一个列表，其中每个条目都包含为与该乐曲视图关联的任何乐曲份额提供的最新所有权数据集。