Gerenciamento de recursos de composição

Observação: a API Content ID do YouTube é destinada a parceiros de conteúdo do YouTube e não pode ser acessada por todos os desenvolvedores ou usuários do YouTube. Se você não encontrar a API Content ID do YouTube como um dos serviços listados no Console de APIs do Google, consulte a Central de Ajuda do YouTube para saber mais sobre o Programa de Parcerias do YouTube.

Observação:as informações neste guia se aplicam especificamente aos recursos de composição.

No sistema de gerenciamento de direitos do YouTube, um recurso representa uma obra de propriedade intelectual. O YouTube reconhece diferentes tipos de recursos, como filmes, videoclipes, gravações de som e composições.

No entanto, devido à natureza complexa da propriedade e dos direitos de composição, o YouTube usa um modelo de recursos de dois níveis. O modelo foi projetado para considerar o seguinte:

• Toda gravação de som é associada a uma composição.
• Os proprietários do conteúdo muitas vezes precisam aplicar a propriedade dos direitos de publicação da mesma música ou composição para diferentes gravações de som.

Este documento fornece uma visão geral do modelo de recurso de composição do YouTube. Ela também explica como os dois tipos de recursos de composição são usados nos métodos da API Content ID do YouTube.

Noções básicas sobre o modelo do recurso de composição

O modelo de recurso do YouTube define duas representações diferentes de recursos de composição:

• Uma cota de composição representa as informações que um editor específico fornece sobre um recurso de composição. Assim, uma cota de composição identifica somente os metadados, a propriedade e os dados de política que o único editor fornece para a composição.

  Uma cota de composição pode ser associada a muitas gravações de som.

• Uma visualização de composição representa o recurso de composição incorporado a uma gravação de som. Cada gravação de som é mapeada exatamente para uma visualização de composição, e a visualização de composição representa o conjunto canônico de informações que o YouTube exibe sobre uma composição. Os metadados, os dados de propriedade e a política da visualização de composição são determinados usando dados de todos os recursos de cota de composição associados.

  Uma visualização de composição pode ser mapeada para zero ou mais cotas de composição. No entanto, uma visualização de composição só é mapeada para várias cotas de composição quando uma composição tem vários proprietários.

  É possível que um único proprietário de conteúdo usando a API represente vários proprietários de uma composição e, portanto, tenha várias cotas dessa composição. Por exemplo, um agregador de direitos digitais pode ter os direitos sobre a mesma composição de partes diferentes em territórios distintos. O agregador teria entidades distintas que representam esses direitos, o que seria mapeado para diferentes cotas de composição no modelo do YouTube. As diferentes cotas de composição ainda podem estar vinculadas às mesmas visualizações de composição.

No diagrama a seguir, ilustramos esse modelo. No diagrama:

• Círculos são gravações de som.
• Quadrados são visualizações de composição.
• Triângulos são cotas de composição. Cada cor de triângulo representa um proprietário de conteúdo diferente. Os triângulos pequenos dentro dos quadrados mostram quais dados foram mesclados para gerar o conjunto canônico de informações que o YouTube exibe sobre uma composição. O YouTube usa esses dados para calcular a propriedade e a política de uma composição.

Dois tipos de IDs de recursos

O YouTube atribui IDs a cotas de composição e visualizações de composição, e ambos são considerados IDs de recursos. No entanto, eles não são intercambiáveis na API. Com isso em mente, o restante deste documento usa os termos shareId e viewId para se referir aos IDs atribuídos às cotas e visualizações de composição, respectivamente.

Em geral, ao recuperar ou atualizar informações que você fornece sobre um recurso, você usará um shareId. Se estiver recuperando o conjunto canônico de informações que o YouTube exibe sobre um recurso, você usará um viewId.

O diagrama na seção anterior mostra que as gravações de som e visualizações de composição estão marcadas com números (SR₁, CV₁ etc.). Os números refletem a relação direta entre gravações de som e visualizações de composição. Portanto, se você quiser extrair o conjunto canônico de informações sobre a composição em uma gravação de som específica, use o método viewId.

Por outro lado, as cotas de composição são marcadas com letras (CS_b etc.). As letras representam diferentes proprietários de conteúdo. Portanto, se você for o proprietário do conteúdo verde e quiser recuperar os metadados ou dados de propriedade fornecidos para um recurso de composição, use shareId para recuperar essas informações.

Uso de IDs de recursos em métodos de API

O restante deste documento explica como métodos individuais da API processam shareIds e viewIds quando esses IDs são usados como valores de parâmetros ou propriedades. Como os métodos da API estão listados em ordem alfabética, pode ser útil percorrer primeiro as etapas típicas associadas à criação de um recurso de composição e vinculá-lo a uma gravação de som.

1. Chame o método assets.insert para criar um recurso de composição. A resposta da API é um recurso asset em que a propriedade id é um shareId.

2. Chame o método ownership.update para definir os dados de propriedade para a cota de composição. Defina o parâmetro assetId do método como o shareId da etapa 1.

3. Chame o método assetMatchPolicy.update para definir dados de política para a cota de composição. A política é aplicada aos vídeos reivindicados que contêm a composição. Defina o parâmetro assetId do método como o shareId da etapa 1.

4. Chame o método assetRelationships.insert para identificar gravações de som que contêm a composição. No recurso assetRelationship que você está inserindo, defina a propriedade parentAssetId como o ID do recurso da gravação de som. Defina a propriedade childAssetId como o shareId da etapa 1.

5. Se você armazenar um mapeamento de viewIds para shareIds, poderá recuperar o viewId chamando o método assetRelationships.list e definindo o parâmetro assetId como o ID do recurso da gravação de som. Uma relação no conjunto de resultados identificará o código do recurso da gravação de som como parentAssetId. Nessa relação, o childAssetId identifica o viewId que é mapeado para o shareId obtido na etapa 1.

Depois que o recurso for criado, você pode usar qualquer um dos métodos discutidos no restante deste documento para recuperar informações sobre ele, atualizá-lo ou excluí-lo.

assets.get/assets.list

Os métodos assets.get e assets.list recuperam informações sobre um recurso ou uma lista de recursos. Os dois métodos aceitam o mesmo conjunto de parâmetros de solicitação.

Três desses parâmetros, fetchMatchPolicy, fetchMetadata e fetchOwnership, usam os valores effective e mine para indicar se você quer recuperar o conjunto canônico de dados sobre o recurso ou se quer recuperar os dados fornecidos sobre ele. Esses valores são um resquício do antigo modelo de recurso de composição do YouTube, que tratava uma visualização de composição e suas cotas de composição como uma única entidade.

No entanto, os valores ainda são suportados no modelo de duas camadas, e o conteúdo da resposta da API depende do valor do parâmetro e se as solicitações estão fornecendo shareIds ou viewIds. O método assets.get usa o parâmetro assetId para especificar o ID do recurso, enquanto o método assets.list usa o parâmetro id.

A lista abaixo explica como os valores de parâmetro de solicitação afetam o conteúdo das respostas da API para esses dois métodos.

• fetchMatchPolicy
  • Se o ID do recurso (parâmetro id ou assetId) especificar um shareId:
    • Se o parâmetro fetchMatchPolicy for mine, a resposta da API vai conter a política que o proprietário do conteúdo que autoriza a solicitação de API definida para a cota de composição.
    • Se o parâmetro fetchMatchPolicy for effective, a API retornará um erro 400.
  • Se o ID do recurso especificar um viewId:
    • Se o parâmetro fetchMatchPolicy for mine e o proprietário do conteúdo que autoriza a solicitação tiver apenas uma cota de composição vinculada ao ID da visualização, a API retornará a política de correspondência definida para essa cota.
    • Se o parâmetro fetchMatchPolicy for mine e o proprietário do conteúdo que autoriza a solicitação tiver várias cotas de composição vinculadas ao ID da visualização, a API vai retornar um erro 400.
    • Se o parâmetro fetchMatchPolicy for effective, a API vai retornar a política de correspondência canônica para a visualização de composição. Essa política considera as políticas de correspondência de todas as cotas de composição vinculadas à viewId, independentemente de quais proprietários de conteúdo são os proprietários desses compartilhamentos.
• fetchMetadata
  • Se o ID do recurso especificar um shareId:
    • Se o parâmetro fetchMetadata for mine, a resposta da API vai conter os metadados do recurso que o proprietário do conteúdo que autoriza a solicitação de API definiu para a cota de composição.
    • Se o parâmetro fetchMetadata for effective, a API retornará um erro 400.
  • Se o ID do recurso especificar um viewId:
    • Se o parâmetro fetchMetadata for mine e o proprietário do conteúdo que autoriza a solicitação tiver apenas uma cota de composição vinculada ao ID da visualização, a API retornará os metadados definidos para essa cota.
    • Se o parâmetro fetchMetadata for mine e o proprietário do conteúdo que autoriza a solicitação tiver várias cotas de composição vinculadas ao ID da visualização, a API vai retornar um erro 400.
    • Se o parâmetro fetchMetadata for effective, a API vai retornar o conjunto canônico de metadados para a visualização de composição. Esses metadados representam os metadados do recurso fornecidos para todas as cotas de composição vinculadas ao viewId, independentemente de quais proprietários de conteúdo são os proprietários dessas cotas.
• fetchOwnership
  • Se o ID do recurso especificar um shareId:
    • Se o parâmetro fetchOwnership for mine, a resposta da API vai conter os dados de propriedade que o proprietário do conteúdo que autoriza a solicitação de API definiu para a cota de composição.
    • Se o parâmetro fetchOwnership for effective, a API retornará um erro 400.
  • Se o ID do recurso especificar um viewId:
    • Se o parâmetro fetchOwnership for mine e o proprietário do conteúdo que autoriza a solicitação tiver apenas uma cota de composição vinculada ao ID da visualização, a API retornará os dados de propriedade definidos para essa cota.
    • Se o parâmetro fetchOwnership for mine e o proprietário do conteúdo que autoriza a solicitação tiver várias cotas de composição vinculadas ao ID da visualização, a API vai retornar um erro 400.
    • Se o parâmetro fetchOwnership for effective, a API vai retornar os dados de propriedade canônicos para a visualização de composição. Esses dados representam os dados de propriedade de todas as cotas de composição vinculadas à viewId, independentemente de quais proprietários do conteúdo são os proprietários das cotas.
• fetchOwnershipConflicts
  • Se o ID do recurso especificar shareId, a API retornará uma resposta de erro 400.
  • Se o ID do recurso especificar um viewId, a API retornará uma lista de conflitos de propriedade associados à visualização de composição.

assets.insert

Esse método cria um recurso asset, e o YouTube atribui um ID para identificá-lo de forma exclusiva. Esse ID, que é retornado como o valor da propriedade id na resposta da API, é um shareId.

Observação:shareIds e viewIds são usados apenas para recursos de composição. Outros tipos de recursos não usam um modelo de duas camadas para gerenciar dados de recursos.

assets.update e assets.patch

Esses métodos atualizam os metadados de um recurso. Nas duas solicitações, o parâmetro assetId identifica o recurso que está sendo atualizado. Além disso, em ambas as solicitações, o corpo da solicitação é um recurso asset em que o valor da propriedade id precisa corresponder ao valor do parâmetro assetId.

• Se o parâmetro assetId e a propriedade id especificarem um shareId, a solicitação de API vai atualizar a cota de composição especificada.
• Se o parâmetro assetId e a propriedade id especificarem uma viewId, e o proprietário do conteúdo que autoriza a solicitação tiver apenas uma cota de composição vinculada a esse viewId, a solicitação de API vai atualizar essa cota.
• Se o parâmetro assetId e a propriedade id especificarem um viewId, e o proprietário do conteúdo que autoriza a solicitação tiver várias cotas de composição vinculadas a esse viewId, a solicitação de API vai retornar um erro 400.

assetMatchPolicy.get

Esse método retorna a política de correspondência definida para um recurso especificado. O parâmetro assetId da solicitação identifica o recurso.

• Se o parâmetro assetId especificar um shareId, a resposta da API conterá os metadados do recurso que o proprietário do conteúdo que autoriza a solicitação de API definida para a cota de composição.
• Se o parâmetro assetId especificar um viewId, a API vai retornar o conjunto canônico de metadados para a visualização de composição. Esses metadados representam os metadados do recurso fornecidos para todas as cotas de composição vinculadas ao viewId, independentemente de quais proprietários de conteúdo são os proprietários dessas cotas.

assetMatchPolicy.update e assetMatchPolicy.patch

Esses métodos atualizam a política de correspondência para um recurso especificado. O parâmetro assetId da solicitação identifica o recurso.

• Se o parâmetro assetId especificar um shareId, a solicitação de API vai atualizar a política de correspondência dessa cota de composição.
• Se o parâmetro assetId especificar um viewId e o proprietário do conteúdo que autoriza a solicitação tiver apenas uma cota de composição vinculada a essa viewId, a solicitação de API vai atualizar a política de correspondência dessa cota.
• Se o parâmetro assetId especificar um viewId e o proprietário do conteúdo que autoriza a solicitação tiver várias cotas de composição vinculadas a esse viewId, a solicitação de API vai retornar um erro 400.

assetRelationships.list

Esse método retorna uma lista de relações de recursos para um recurso especificado. O parâmetro assetId da solicitação identifica o recurso.

• Se o parâmetro assetId especificar um shareId, a resposta da API incluirá uma lista de recursos de gravação de som vinculados. A lista pode conter vários itens. Em cada recurso assetRelationship, o ID do recurso de gravação de som é parentAssetId, e shareId é o childAssetId.
• Se o parâmetro assetId especificar um viewId, a resposta da API identificará a gravação de som vinculada a esse viewId. A resposta contém no máximo um recurso.
• Se o parâmetro assetId identificar um recurso de gravação de som, a resposta da API poderá conter várias relações.
  • Se o ID do recurso da gravação de som for o parentAssetId em um recurso assetRelationship retornado, o childAssetId identificará a visualização de composição (viewId) vinculada a essa gravação. Cada gravação de som tem exatamente uma dessas relações.
  • Se o ID do recurso da gravação de som for childAssetId, o parentAssetId vai identificar um vídeo que contém a gravação, como um vídeo de música ou um vídeo com arte da capa. Cada gravação de som pode ter várias dessas relações.

assetRelationships.insert

Esse método cria uma relação entre dois recursos. Você chamaria esse método para indicar que tem uma parte da composição vinculada a uma gravação de som.

No recurso assetRelationship no corpo da solicitação, defina a propriedade parentAssetId como o ID do recurso da gravação de som. Defina a propriedade childAssetId como shareId.

assetSearch.list

Esse método pesquisa recursos com base nos metadados do recurso. A resposta da API contém uma lista de recursos assetSearch, em que a propriedade id de cada recurso identifica um ID. O valor da propriedade id é, na verdade, um ID de recurso.

• Se o recurso assetSearch identificar uma composição, o valor da propriedade id será um shareId.

assetShares.list

Esse método retorna um mapeamento de visualizações de composição para cotas de composição. O parâmetro assetId da solicitação pode especificar um viewId ou um shareId.

• Se o parâmetro assetId especificar um viewId, a resposta da API terá uma lista de recursos assetShare. Cada recurso identifica uma cota de composição vinculada à visualização de composição especificada e que pertence ao proprietário do conteúdo que autoriza a solicitação.

  A resposta da API pode conter vários recursos assetShare. O caso de uso comum em que uma viewId é mapeada para várias shareIds que pertencem ao mesmo proprietário do conteúdo está descrito na seção Conceitos básicos sobre o modelo de recurso de composição deste documento.

• Se o parâmetro assetId especificar um shareId, a resposta da API terá uma lista de recursos assetShare. Cada recurso identifica uma visualização de composição associada à cota de composição especificada. A resposta vai conter um recurso para cada gravação de som vinculada à cota de composição. Cada gravação de som está vinculada a exatamente uma visualização de composição.

claimSearch.list

Este método retorna uma lista de reivindicações que correspondem aos critérios de pesquisa especificados. O parâmetro assetId do método permite pesquisar reivindicações associadas a um recurso específico.

• Se a solicitação de API especificar um shareId, a API retornará um código de resposta 400.

• Se a solicitação de API especificar um viewId, a API retornará uma lista de reivindicações associadas à visualização de composição especificada, que é mapeada para exatamente um recurso de gravação de som.

metadataHistory.list

Esse método retorna uma lista de todos os metadados fornecidos para um recurso, independentemente de qual proprietário de conteúdo forneceu os dados. O parâmetro assetId da solicitação identifica o recurso para o qual os dados estão sendo recuperados.

• Se a solicitação de API especificar um shareId, a API vai retornar o conjunto de metadados mais recente dessa cota de composição.

• Se a solicitação de API especificar um viewId, a API vai retornar uma lista em que cada entrada contém o conjunto mais recente de metadados fornecidos para qualquer cota de composição vinculada a essa visualização.

ownership.get

Esse método retorna os dados de propriedade definidos para um recurso especificado. O parâmetro assetId da solicitação identifica o recurso.

• Se o parâmetro assetId especificar um shareId, a resposta da API conterá os dados de propriedade que o proprietário do conteúdo que autoriza a solicitação de API definida para a cota de composição.
• Se o parâmetro assetId especificar um viewId, a API vai retornar o conjunto canônico de dados de propriedade para a visualização de composição. A resposta sintetiza os dados de propriedade fornecidos para todas as cotas de composição vinculadas à viewId, independentemente de quais proprietários de conteúdo são os proprietários dessas cotas.

propriedade.update e propriedade.patch

Esses métodos atualizam os dados de propriedade de um recurso especificado. O parâmetro assetId da solicitação identifica o recurso.

• Se o parâmetro assetId especificar um shareId, a solicitação de API vai atualizar os dados de propriedade dessa cota de composição.
• Se o parâmetro assetId especificar um viewId e o proprietário do conteúdo que autoriza a solicitação tiver apenas uma cota de composição vinculada a esse viewId, a solicitação de API vai atualizar os dados de propriedade dessa cota.
• Se o parâmetro assetId especificar um viewId e o proprietário do conteúdo que autoriza a solicitação tiver várias cotas de composição vinculadas a esse viewId, a solicitação de API vai retornar um erro 400.

ownershipHistory.list

Esse método retorna uma lista de todos os dados de propriedade fornecidos para um recurso, independentemente de qual proprietário do conteúdo forneceu os dados. O parâmetro assetId da solicitação identifica o recurso para o qual os dados estão sendo recuperados.

• Se a solicitação de API especificar um shareId, a API vai retornar o conjunto mais recente de dados de propriedade dessa cota de composição.

• Se a solicitação de API especificar um viewId, a API retornará uma lista em que cada entrada contém o conjunto mais recente de dados de propriedade fornecidos para qualquer cota de composição vinculada a essa visualização.