Cómo administrar activos de composición

Nota: La API de Content ID de YouTube se diseñó para que la usen los socios de contenido de YouTube, por lo que no todos los desarrolladores ni todos los usuarios de YouTube pueden acceder a ella. Si la API de Content ID de YouTube no aparece como uno de los servicios enumerados en la Consola de API de Google, consulta el Centro de ayuda de YouTube para obtener más información sobre el Programa de socios de YouTube.

Nota: La información de esta guía se aplica específicamente a los activos de composición.

En el sistema de administración de derechos de YouTube, un activo representa una pieza de propiedad intelectual. YouTube reconoce distintos tipos de activos, como películas, videos musicales, grabaciones de sonido y composiciones.

Sin embargo, debido a la naturaleza compleja de los derechos y la propiedad de una composición, YouTube utiliza un modelo de activo de dos niveles para los elementos de composición. El modelo está diseñado para considerar lo siguiente:

  • Cada grabación de sonido se asocia con una composición.
  • A menudo, los propietarios del contenido deben aplicar la propiedad de los derechos de publicación de la misma canción o composición a diferentes grabaciones de sonido.

Este documento proporciona una descripción general del modelo de activos de composición de YouTube. También explica cómo se usan los dos tipos de elementos de composición en los métodos de la API de Content ID de YouTube.

Comprende el modelo de elementos de composición

El modelo de elementos de YouTube define dos representaciones diferentes de los elementos de composición:

  • El porcentaje de composición representa la información que proporciona un editor en particular sobre un activo de composición. Por lo tanto, un porcentaje de composición solo identifica los metadatos, la propiedad y los datos de políticas que proporciona ese publicador único para la composición.

    Un porcentaje de composición se puede asociar con muchas grabaciones de sonido.

  • Una vista de composición representa el activo de composición que está incorporado en una grabación de sonido. Cada grabación de sonido se asigna a exactamente una vista de composición, y la vista de composición representa el conjunto canónico de información que YouTube muestra sobre una composición. Los metadatos, los datos de propiedad y la política de la vista de composición se determinan con los datos de todos los activos de porcentaje de composición asociados.

    Una vista de composición puede asignarse a cero o más porcentajes de composición. Sin embargo, una vista de composición solo se asigna a varios porcentajes de composición cuando una composición tiene varios propietarios.

    Ten en cuenta que un solo propietario del contenido puede usar la API para representar a varios propietarios de una composición y, por lo tanto, poseer varias partes de esa composición. Por ejemplo, un agregador de derechos digitales podría obtener derechos sobre la misma composición de distintas partes en distintos territorios. El agregador tendría entidades discretas que representan esos derechos, que se asignarían a diferentes porcentajes de composición en el modelo de YouTube. Los diferentes porcentajes de composición aún podrían vincularse a las mismas vistas de composición.

En el siguiente diagrama, se ilustra este modelo: En el diagrama:

  • Los círculos son grabaciones de sonido.
  • Los cuadrados son vistas de composición.
  • Los triángulos son porcentajes de composición. Cada color de triángulo representa un propietario del contenido diferente. Los pequeños triángulos dentro de los cuadrados muestran qué datos se combinan para generar el conjunto canónico de información que YouTube muestra sobre una composición. YouTube utiliza estos datos para calcular la propiedad y la política de una composición.

Diagrama en el que se muestran las relaciones entre las grabaciones de sonido, las vistas de composición y los porcentajes de composición.

Dos tipos de ID de activos

YouTube asigna ID a los porcentajes de composición y las vistas de composición, y ambos se consideran ID de activos. Sin embargo, no son intercambiables en la API. Con esto en mente, en el resto de este documento, se usan los términos shareId y viewId para hacer referencia a los ID asignados a los porcentajes de composición y las vistas de composición, respectivamente.

En general, cuando recuperes o actualices la información que proporcionas sobre un recurso, usarás un shareId. Si quieres recuperar el conjunto canónico de información que YouTube muestra sobre un activo, usarás un viewId.

Si revisas el diagrama de la sección anterior, verás que las grabaciones de sonido y las vistas de composición están marcadas con números (SR1, CV1, etcétera). Las cifras reflejan la relación 1:1 entre las grabaciones de sonido y las vistas de composición. Por lo tanto, si quieres recuperar el conjunto canónico de información sobre la composición en una grabación de sonido en particular, debes usar viewId para esa composición.

Por otro lado, los porcentajes de composición están marcados con letras (CSb, etcétera). Las letras representan diferentes propietarios de contenido. Por lo tanto, si eres el propietario del contenido verde y quieres recuperar los metadatos o los datos de propiedad que proporcionaste para un activo de composición, debes usar shareId para recuperar esa información.

Cómo usar los ID de activos en los métodos de la API

En el resto de este documento, se explica cómo los métodos individuales de la API manejan shareIds y viewIds cuando esos IDs se usan como valores de parámetros o propiedades. Dado que los métodos de la API se enumeran alfabéticamente, puede resultar útil repasar primero los pasos típicos asociados con la creación de un activo de composición y su vinculación a una grabación de sonido.

  1. Llama al método assets.insert para crear un activo de composición. La respuesta de la API es un recurso asset en el que la propiedad id es un shareId.

  2. Llama al método ownership.update para establecer los datos de propiedad del porcentaje de composición. Establece el parámetro assetId del método en el shareId que obtuviste en el paso 1.

  3. Llama al método assetMatchPolicy.update para establecer los datos de la política del porcentaje de composición. La política se aplica a los videos reclamados que contienen la composición. Establece el parámetro assetId del método en el shareId que obtuviste en el paso 1.

  4. Llama al método assetRelationships.insert para identificar las grabaciones de sonido que contienen la composición. En el recurso assetRelationship que insertas, establece la propiedad parentAssetId en el ID del activo de la grabación de sonido. Establece la propiedad childAssetId en el shareId que obtuviste en el paso 1.

  5. Si almacenas una asignación de viewIds en shareIds, puedes recuperar viewId llamando al método assetRelationships.list y estableciendo el parámetro assetId en el ID del activo de la grabación de sonido. Una relación en el conjunto de resultados identificará el ID del activo de la grabación de sonido como parentAssetId. En esa relación, el childAssetId identifica el viewId que se asigna al shareId obtenido en el paso 1.

Después de crear el recurso, puedes usar cualquiera de los métodos analizados en el resto de este documento para recuperar información sobre él, actualizarlo o borrarlo.

assets.get/assets.list

Los métodos assets.get y assets.list recuperan información sobre un recurso o una lista de elementos. Ambos métodos admiten el mismo conjunto de parámetros de solicitud.

Tres de esos parámetros (fetchMatchPolicy, fetchMetadata y fetchOwnership) usan los valores effective y mine para indicar si deseas recuperar el conjunto canónico de datos sobre el recurso o si quieres recuperar los datos que proporcionaste sobre el recurso. Estos valores son un vestigio del antiguo modelo de activos de composición de YouTube, en el que se consideraba una vista de composición y sus porcentajes de composición como una sola entidad.

Sin embargo, los valores aún son compatibles con el modelo de dos niveles, y el contenido de la respuesta a la API depende tanto del valor del parámetro como de si las solicitudes proporcionan shareIds o viewIds. Ten en cuenta que el método assets.get usa el parámetro assetId para especificar el ID del activo, mientras que el método assets.list usa el parámetro id.

En la siguiente lista, se explica cómo los valores de los parámetros de solicitud afectan el contenido de las respuestas de la API para estos dos métodos.

  • fetchMatchPolicy
    • Si el ID del activo (parámetro id o assetId) especifica un shareId, haz lo siguiente:
      • Si el parámetro fetchMatchPolicy es mine, la respuesta de la API contiene la política que establece el propietario del contenido que autoriza la solicitud a la API establecida para el porcentaje de composición.
      • Si el parámetro fetchMatchPolicy es effective, la API muestra un error 400.
    • Si el ID del activo especifica un viewId, haz lo siguiente:
      • Si el parámetro fetchMatchPolicy es mine, y el propietario del contenido que autoriza la solicitud posee solo un porcentaje de composición vinculado al ID de vista, la API muestra la política de coincidencias que se estableció para ese porcentaje de composición.
      • Si el parámetro fetchMatchPolicy es mine, y el propietario del contenido que autoriza la solicitud posee varios porcentajes de composición vinculados al ID de vista, la API muestra un error 400.
      • Si el parámetro fetchMatchPolicy es effective, la API muestra la política de coincidencias canónica para la vista de composición. Esa política de coincidencias contempla las políticas de coincidencias de todos los porcentajes de composición vinculados a viewId, independientemente de los propietarios del contenido que posean esos porcentajes.
  • fetchMetadata
    • Si el ID del activo especifica un shareId, haz lo siguiente:
      • Si el parámetro fetchMetadata es mine, la respuesta de la API contiene los metadatos del activo que el propietario del contenido autoriza al conjunto de la solicitud a la API para el porcentaje de composición.
      • Si el parámetro fetchMetadata es effective, la API muestra un error 400.
    • Si el ID del activo especifica un viewId, haz lo siguiente:
      • Si el parámetro fetchMetadata es mine, y el propietario del contenido que autoriza la solicitud posee solo un porcentaje de composición vinculado al ID de vista, la API muestra los metadatos establecidos para ese porcentaje de composición.
      • Si el parámetro fetchMetadata es mine, y el propietario del contenido que autoriza la solicitud posee varios porcentajes de composición vinculados al ID de vista, la API muestra un error 400.
      • Si el parámetro fetchMetadata es effective, la API muestra el conjunto canónico de metadatos para la vista de composición. Esos metadatos incluyen los metadatos del activo proporcionados para todos los porcentajes de composición vinculados a viewId, independientemente de los propietarios de contenido que sean propietarios de esos elementos compartidos.
  • fetchOwnership
    • Si el ID del activo especifica un shareId, haz lo siguiente:
      • Si el parámetro fetchOwnership es mine, la respuesta de la API contiene los datos de propiedad que el propietario del contenido autoriza al conjunto de solicitudes a la API para el porcentaje de composición.
      • Si el parámetro fetchOwnership es effective, la API muestra un error 400.
    • Si el ID del activo especifica un viewId, haz lo siguiente:
      • Si el parámetro fetchOwnership es mine, y el propietario del contenido que autoriza la solicitud posee solo un porcentaje de composición vinculado al ID de vista, la API muestra los datos de propiedad establecidos para ese porcentaje de composición.
      • Si el parámetro fetchOwnership es mine, y el propietario del contenido que autoriza la solicitud posee varios porcentajes de composición vinculados al ID de vista, la API muestra un error 400.
      • Si el parámetro fetchOwnership es effective, la API muestra los datos de propiedad canónicos de la vista de composición. Esos datos representan los datos de propiedad de todos los porcentajes de composición vinculados a viewId, independientemente de los propietarios del contenido que posean esos porcentajes.
  • fetchOwnershipConflicts
    • Si el ID del elemento especifica un shareId, la API muestra una respuesta de error 400.
    • Si el ID del activo especifica un viewId, la API muestra una lista de conflictos de propiedad asociados con la vista de composición.

assets.insert

Este método crea un recurso asset y YouTube asigna un ID para identificarlo de manera única. Ese ID, que se muestra como el valor de la propiedad id en la respuesta de la API, es un shareId.

Nota: Recuerda que shareIds y viewIds solo se usan para activos de composición. Otros tipos de elementos no usan un modelo de dos niveles para administrar los datos de elementos.

assets.update y assets.patch

Estos métodos actualizan los metadatos de un activo. En ambas solicitudes, el parámetro assetId identifica el recurso que se actualiza. Además, en ambas solicitudes, el cuerpo de la solicitud es un recurso asset en el que el valor de la propiedad id debe coincidir con el valor del parámetro assetId.

  • Si el parámetro assetId y la propiedad id especifican un shareId, la solicitud a la API actualiza el porcentaje de composición especificado.
  • Si el parámetro assetId y la propiedad id especifican un viewId, y el propietario del contenido que autoriza la solicitud solo posee un porcentaje de composición vinculado a ese viewId, la solicitud a la API actualizará ese porcentaje de composición.
  • Si el parámetro assetId y la propiedad id especifican un viewId, y el propietario del contenido que autoriza la solicitud posee varios porcentajes de composición vinculados a ese viewId, la solicitud a la API muestra un error 400.

assetMatchPolicy.get

Este método muestra la política de coincidencias definida para un elemento especificado. El parámetro assetId de la solicitud identifica el recurso.

  • Si el parámetro assetId especifica un shareId, la respuesta de la API contiene los metadatos del activo que el propietario del contenido autoriza al conjunto de solicitudes a la API para el porcentaje de composición.
  • Si el parámetro assetId especifica un viewId, la API muestra el conjunto canónico de metadatos para la vista de composición. Esos metadatos incluyen los metadatos del activo proporcionados para todos los porcentajes de composición vinculados a viewId, independientemente de los propietarios de contenido que sean propietarios de esos elementos compartidos.

assetMatchPolicy.update y assetMatchPolicy.patch

Estos métodos actualizan la política de coincidencias de un elemento especificado. El parámetro assetId de la solicitud identifica el recurso.

  • Si el parámetro assetId especifica un shareId, la solicitud a la API actualiza la política de coincidencias para ese porcentaje de composición.
  • Si el parámetro assetId especifica un viewId, y el propietario del contenido que autoriza la solicitud solo posee un porcentaje de composición vinculado a ese viewId, la solicitud a la API actualizará la política de coincidencias de ese porcentaje de composición.
  • Si el parámetro assetId especifica un viewId, y el propietario del contenido que autoriza la solicitud posee varios porcentajes de composición vinculados a ese viewId, la solicitud de la API mostrará un error 400.

assetRelationships.list

Este método muestra una lista de relaciones de elementos para un elemento especificado. El parámetro assetId de la solicitud identifica el recurso.

  • Si el parámetro assetId especifica un shareId, la respuesta de la API contiene una lista de activos de grabación de sonido vinculados. La lista puede contener varios elementos. En cada recurso assetRelationship, el ID del activo de la grabación de sonido es parentAssetId, y shareId es childAssetId.
  • Si el parámetro assetId especifica un viewId, la respuesta de la API identifica la grabación de sonido vinculada a ese viewId. La respuesta contiene como máximo un recurso.
  • Si el parámetro assetId identifica un activo de grabación de sonido, la respuesta de la API puede contener varias relaciones.
    • Si el ID del activo de la grabación de sonido es parentAssetId en un recurso assetRelationship que se muestra, childAssetId identifica la vista de composición (viewId) vinculada a esa grabación de sonido. Cada grabación de sonido tiene exactamente una relación de este tipo.
    • Si el ID del activo de la grabación de sonido es childAssetId, parentAssetId identifica un video que contiene la grabación de sonido, como un video musical o un video de pista con portada. Cada grabación de sonido puede tener varias de esas relaciones.

assetRelationships.insert

Este método crea una relación entre dos elementos. Puedes llamar a este método para indicar que posees una parte de la composición vinculada a una grabación de sonido.

En el recurso assetRelationship del cuerpo de la solicitud, establece la propiedad parentAssetId con el ID del activo de la grabación de sonido. Establece la propiedad childAssetId en shareId.

assetSearch.list

Este método busca elementos según los metadatos de elementos. La respuesta de la API contiene una lista de recursos assetSearch, en la que la propiedad id de cada recurso identifica un ID de elemento. El valor de la propiedad id es, de hecho, un ID de activo.

  • Si el recurso assetSearch identifica una composición, el valor de la propiedad id será shareId.

assetShares.list

Este método muestra una asignación de vistas de composición a los porcentajes de composición. El parámetro assetId de la solicitud puede especificar una viewId o una shareId.

  • Si el parámetro assetId especifica un viewId, la respuesta de la API contendrá una lista de recursos assetShare. Cada recurso identifica un porcentaje de composición vinculado a la vista de composición especificada y que pertenece al propietario del contenido que autoriza la solicitud.

    La respuesta de la API puede contener varios recursos assetShare. El caso de uso común en el que un viewId se asigna a varios shareIds que pertenecen al mismo propietario del contenido se describe en la sección Comprende el modelo de elementos de composición de este documento.

  • Si el parámetro assetId especifica un shareId, la respuesta de la API contendrá una lista de recursos assetShare. Cada recurso identifica una vista de composición asociada con el porcentaje de composición especificado. La respuesta contendrá un recurso por cada grabación de sonido a la que esté vinculado el porcentaje de composición. (Cada grabación de sonido está vinculada a exactamente una vista de composición).

claimSearch.list

Este método muestra una lista de reclamos que coinciden con los criterios de búsqueda especificados. El parámetro assetId del método te permite buscar reclamos asociados con un activo en particular.

  • Si la solicitud a la API especifica un shareId, la API muestra un código de respuesta 400.

  • Si la solicitud a la API especifica un viewId, la API muestra una lista de reclamos asociados con la vista de composición especificada, que se asigna a exactamente un activo de grabación de sonido.

metadataHistory.list

Este método muestra una lista de todos los metadatos proporcionados para un elemento, independientemente del propietario del contenido que proporcionó los datos. El parámetro assetId de la solicitud identifica el recurso para el cual se recuperan los datos.

  • Si la solicitud a la API especifica un shareId, la API muestra el conjunto de metadatos más reciente para ese porcentaje de composición.

  • Si la solicitud a la API especifica un viewId, la API muestra una lista en la que cada entrada contiene el último conjunto de metadatos proporcionado para cualquier porcentaje de composición vinculado a esa vista de composición.

ownership.get

Este método muestra los datos de propiedad definidos para un elemento especificado. El parámetro assetId de la solicitud identifica el recurso.

  • Si el parámetro assetId especifica un shareId, la respuesta de la API contiene los datos de propiedad que el propietario del contenido autoriza al conjunto de solicitudes a la API para el porcentaje de composición.
  • Si el parámetro assetId especifica un viewId, la API muestra el conjunto canónico de datos de propiedad de la vista de composición. La respuesta sintetiza los datos de propiedad proporcionados para todos los porcentajes de composición vinculados al viewId, independientemente de los propietarios del contenido que posean esos porcentajes.

propiedad.update y propiedad.patch

Estos métodos actualizan los datos de propiedad de un elemento específico. El parámetro assetId de la solicitud identifica el recurso.

  • Si el parámetro assetId especifica un shareId, la solicitud a la API actualiza los datos de propiedad de ese porcentaje de composición.
  • Si el parámetro assetId especifica un viewId, y el propietario del contenido que autoriza la solicitud solo posee un porcentaje de composición vinculado a ese viewId, la solicitud a la API actualizará los datos de propiedad de ese porcentaje de composición.
  • Si el parámetro assetId especifica un viewId, y el propietario del contenido que autoriza la solicitud posee varios porcentajes de composición vinculados a ese viewId, la solicitud de la API mostrará un error 400.

ownershipHistory.list

Este método muestra una lista de todos los datos de propiedad de un elemento, independientemente del propietario del contenido que los proporcionó. El parámetro assetId de la solicitud identifica el recurso para el cual se recuperan los datos.

  • Si la solicitud a la API especifica un shareId, la API muestra el conjunto más reciente de datos de propiedad para ese porcentaje de composición.

  • Si la solicitud a la API especifica un viewId, la API muestra una lista en la que cada entrada contiene el conjunto más reciente de datos de propiedad proporcionados para cualquier porcentaje de composición vinculado a esa vista de composición.