Kompositionsinhalte verwalten

Hinweis: Die YouTube Content ID API ist für die Verwendung durch YouTube-Inhaltspartner vorgesehen und nicht für alle Entwickler oder YouTube-Nutzer zugänglich. Wenn die YouTube Content ID API nicht als einer der in der Google API Console aufgeführten Dienste angezeigt wird, findest du in der YouTube-Hilfe weitere Informationen zum YouTube-Partnerprogramm.

Hinweis: Die Informationen in diesem Leitfaden gelten speziell für Kompositionsinhalte.

Im Rechteverwaltungssystem von YouTube repräsentiert ein Inhalt ein Stück geistigen Eigentums. YouTube erkennt verschiedene Arten von Inhalten wie Filme, Musikvideos, Tonaufnahmen und Kompositionen.

Da Eigentumsrechte und Rechte an Kompositionen komplex sind, verwendet YouTube für Kompositionsinhalte jedoch ein zweistufiges Asset-Modell. Das Modell berücksichtigt Folgendes:

  • Jede Tonaufnahme ist einer Komposition zugeordnet.
  • Rechteinhaber müssen die Verlagsrechte für denselben Song oder dieselbe Komposition oft auf verschiedene Tonaufnahmen anwenden.

Dieses Dokument bietet eine Übersicht über das Asset-Modell von YouTube für Kompositionen. Außerdem wird erläutert, wie die beiden Arten von Kompositionsinhalten in YouTube Content ID API-Methoden verwendet werden.

Das Asset-Modell für die Komposition

Das Inhaltsmodell von YouTube definiert zwei verschiedene Darstellungen von Kompositionsinhalten:

  • Ein Anteil an möglichen Kompositionen bezieht sich auf die Informationen, die ein bestimmter Publisher zu einem Kompositions-Asset bereitstellt. Auf diese Weise werden bei einer geteilten Komposition nur die Metadaten, Eigentumsrechte und Richtliniendaten angegeben, die ein einzelner Publisher für die Komposition bereitstellt.

    Eine geteilte Komposition kann mit vielen Tonaufnahmen verknüpft sein.

  • Eine Kompositionsansicht stellt das Kompositions-Asset dar, das in eine Tonaufnahme eingebettet ist. Jede Tonaufnahme wird genau einer Kompositionsansicht zugeordnet, und die Kompositionsansicht stellt die kanonischen Informationen dar, die YouTube zu einer Komposition anzeigt. Die Metadaten, Daten zu Eigentumsrechten und die Richtlinie der Kompositionsansicht werden anhand von Daten aus allen verknüpften Assets von geteilten Kompositionen ermittelt.

    Eine Kompositionsansicht kann null oder mehr geteilten Kompositionen zugeordnet werden. Eine Kompositionsansicht wird jedoch nur dann mehreren geteilten Kompositionen zugeordnet, wenn eine Komposition mehrere Rechteinhaber hat.

    Es ist möglich, dass ein einzelner Rechteinhaber das API für mehrere Rechteinhaber einer Komposition verwendet und daher mehrere Anteile an dieser Komposition besitzt. Ein Aggregator digitaler Rechte könnte beispielsweise Rechte an derselben Komposition von verschiedenen Parteien in verschiedenen Gebieten erwerben. Der Aggregator hätte separate Entitäten, die diese Rechte repräsentieren, und die verschiedenen geteilten Kompositionen im YouTube-Modell zugeordnet. Die unterschiedlichen geteilten Kompositionen können weiterhin mit denselben Kompositionsaufrufen verknüpft werden.

Das folgende Diagramm veranschaulicht dieses Modell. Das Diagramm zeigt Folgendes:

  • Kreise sind Tonaufnahmen.
  • Quadrate sind Kompositionsansichten.
  • Dreiecke sind geteilte Kompositionen. Jede Dreieckfarbe steht für einen anderen Rechteinhaber. Die kleinen Dreiecke innerhalb der Quadrate zeigen an, welche Daten zusammengeführt werden, um die kanonischen Informationen zu generieren, die YouTube zu einer Komposition anzeigt. YouTube verwendet diese Daten, um Eigentumsrechte und Richtlinien für eine Komposition zu berechnen.

Diagramm, das die Beziehungen zwischen Tonaufnahmen, Aufrufen von Kompositionen und geteilten Kompositionen zeigt

Zwei Arten von Inhalts-IDs

YouTube weist geteilten Kompositionen und Kompositionen IDs zu. Beide werden als Inhalts-IDs betrachtet. Sie sind jedoch in der API nicht austauschbar. Daher werden im Rest dieses Dokuments die Begriffe shareId und viewId für die IDs verwendet, die geteilten Kompositionen bzw. Kompositionsansichten zugewiesen sind.

Im Allgemeinen verwendest du ein shareId, wenn du Informationen abrufst oder aktualisierst, die du zu einem Asset angibst. Wenn du die kanonischen Informationen abrufen möchtest, die YouTube zu einem Inhalt anzeigt, verwendest du eine viewId.

Wenn du dir das Diagramm im vorherigen Abschnitt ansiehst, siehst du, dass die Tonaufnahmen und die Kompositionsansichten mit Zahlen gekennzeichnet sind (SR1, CV1 usw.). Die Zahlen spiegeln die 1:1-Beziehung zwischen Tonaufnahmen und Aufrufen von Kompositionen wider. Wenn du also die kanonischen Informationen über die Komposition in einer bestimmten Tonaufnahme abrufen möchtest, verwende viewId für diese Komposition.

Geteilte Kompositionen werden dagegen mit Buchstaben gekennzeichnet (CSb usw.). Die Buchstaben stehen für unterschiedliche Rechteinhaber. Wenn du also der grüne Rechteinhaber bist und die Metadaten oder Daten zu Eigentumsrechten abrufen möchtest, die du für einen Kompositionsinhalt bereitgestellt hast, kannst du diese Informationen mit shareId abrufen.

Asset-IDs in API-Methoden verwenden

Im weiteren Verlauf dieses Dokuments wird erläutert, wie einzelne API-Methoden shareIds und viewIds verarbeiten, wenn diese IDs als Parameter- oder Attributwerte verwendet werden. Da die API-Methoden alphabetisch aufgeführt sind, empfiehlt es sich, zuerst die typischen Schritte für das Erstellen eines Kompositions-Assets und das Verknüpfen mit einer Tonaufnahme durchzugehen.

  1. Rufe die Methode assets.insert auf, um ein Kompositions-Asset zu erstellen. Die API-Antwort ist eine asset-Ressource, in der das Attribut id ein shareId ist.

  2. Rufe die Methode ownership.update auf, um Daten zu Eigentumsrechten für die geteilte Komposition festzulegen. Legen Sie den Parameter assetId der Methode auf den in Schritt 1 abgerufenen shareId fest.

  3. Rufe die Methode assetMatchPolicy.update auf, um Richtliniendaten für die geteilte Komposition festzulegen. Die Richtlinie wird auf Videos mit Ansprüchen angewendet, die die Komposition enthalten. Legen Sie den Parameter assetId der Methode auf den in Schritt 1 abgerufenen shareId fest.

  4. Rufe die Methode assetRelationships.insert auf, um Tonaufnahmen zu identifizieren, die die Komposition enthalten. Stelle in der assetRelationship-Ressource, die du einfügst, die parentAssetId-Eigenschaft auf die Asset-ID der Tonaufnahme ein. Legen Sie das Attribut childAssetId auf den in Schritt 1 abgerufenen shareId fest.

  5. Wenn du eine Zuordnung von viewIds zu shareIds speicherst, kannst du die viewId abrufen, indem du die Methode assetRelationships.list aufrufst und den Parameter assetId auf die Asset-ID der Tonaufnahme festlegst. Eine Beziehung in der Ergebnismenge identifiziert die Inhalts-ID der Tonaufnahme als parentAssetId. In dieser Beziehung identifiziert childAssetId den viewId, der dem in Schritt 1 abgerufenen shareId zugeordnet ist.

Nachdem das Asset erstellt wurde, können Sie mit einer der im weiteren Verlauf dieses Dokuments beschriebenen Methoden Informationen zum Asset abrufen, aktualisieren oder löschen.

Assets.get/assets.list

Die Methoden assets.get und assets.list rufen Informationen zu einem Asset oder eine Liste von Assets ab. Beide Methoden unterstützen denselben Satz von Anfrageparametern.

Drei dieser Parameter – fetchMatchPolicy, fetchMetadata und fetchOwnership – verwenden die Werte effective und mine, um anzugeben, ob du die kanonischen Daten über das Asset abrufen möchtest oder ob du die Daten abrufen möchtest, die du zu dem Asset bereitgestellt hast. Diese Werte stammen aus dem alten Asset-Modell von YouTube, bei dem eine Kompositionsansicht und ihre geteilten Kompositionen als eine Einheit behandelt werden.

Im zweistufigen Modell werden die Werte jedoch weiterhin unterstützt und der Inhalt der API-Antwort hängt sowohl vom Parameterwert als auch davon ab, ob die Anfragen shareIds oder viewIds bereitstellen. Bei der Methode assets.get wird der Parameter assetId verwendet, um die Asset-ID anzugeben. Bei der Methode assets.list wird der Parameter id verwendet.

In der folgenden Liste wird erläutert, wie Anfrageparameterwerte den Inhalt der API-Antworten für diese beiden Methoden beeinflussen.

  • fetchMatchPolicy
    • Wenn die Asset-ID (Parameter id oder assetId) einen shareId angibt:
      • Wenn der fetchMatchPolicy-Parameter mine lautet, enthält die API-Antwort die Richtlinie, die der Rechteinhaber, der die API-Anfrage autorisiert, für die geteilte Komposition festgelegt hat.
      • Wenn der fetchMatchPolicy-Parameter effective ist, gibt die API den Fehler 400 zurück.
    • Wenn die Asset-ID einen viewId angibt:
      • Wenn der fetchMatchPolicy-Parameter mine lautet und der Rechteinhaber, der die Anfrage autorisiert, nur eine geteilte Komposition besitzt, die mit der ID der Datenansicht verknüpft ist, gibt die API die Abgleichsrichtlinie zurück, die für diese geteilte Komposition festgelegt wurde.
      • Wenn der fetchMatchPolicy-Parameter mine lautet und der Rechteinhaber, der die Anfrage autorisiert, mehrere geteilte Kompositionen besitzt, die mit der ID der Datenansicht verknüpft sind, gibt die API den Fehler 400 zurück.
      • Wenn der fetchMatchPolicy-Parameter effective lautet, gibt die API die kanonische Abgleichsrichtlinie für die Kompositionsansicht zurück. Diese Abgleichsrichtlinie berücksichtigt die Abgleichsrichtlinien aller geteilten Kompositionen, die mit viewId verknüpft sind, unabhängig davon, welche Rechteinhaber Inhaber der geteilten Kompositionen sind.
  • fetchMetadata
    • Wenn die Asset-ID einen shareId angibt:
      • Wenn der fetchMetadata-Parameter mine lautet, enthält die API-Antwort die Asset-Metadaten, die der Rechteinhaber, der die API-Anfrage autorisiert, für die geteilte Komposition festgelegt hat.
      • Wenn der fetchMetadata-Parameter effective ist, gibt die API den Fehler 400 zurück.
    • Wenn die Asset-ID einen viewId angibt:
      • Wenn der fetchMetadata-Parameter mine lautet und der Rechteinhaber, der die Anfrage autorisiert, nur eine geteilte Komposition besitzt, die mit der ID der Datenansicht verknüpft ist, gibt die API die Metadaten zurück, die für diese geteilte Komposition festgelegt wurden.
      • Wenn der fetchMetadata-Parameter mine lautet und der Rechteinhaber, der die Anfrage autorisiert, mehrere geteilte Kompositionen besitzt, die mit der ID der Datenansicht verknüpft sind, gibt die API den Fehler 400 zurück.
      • Wenn der fetchMetadata-Parameter effective lautet, gibt die API den kanonischen Metadatensatz für die Kompositionsansicht zurück. Diese Metadaten berücksichtigen die Asset-Metadaten, die für alle geteilten Kompositionen bereitgestellt werden, die mit viewId verknüpft sind, unabhängig davon, welche Rechteinhaber die geteilten Kompositionen haben.
  • fetchOwnership
    • Wenn die Asset-ID einen shareId angibt:
      • Wenn der fetchOwnership-Parameter mine lautet, enthält die API-Antwort die Daten zu Eigentumsrechten, die der Rechteinhaber, der die API-Anfrage autorisiert, für die geteilte Komposition festgelegt hat.
      • Wenn der fetchOwnership-Parameter effective ist, gibt die API den Fehler 400 zurück.
    • Wenn die Asset-ID einen viewId angibt:
      • Wenn der fetchOwnership-Parameter mine lautet und der Rechteinhaber, der die Anfrage autorisiert, nur eine geteilte Komposition besitzt, die mit der ID der Datenansicht verknüpft ist, gibt die API die Daten zu Eigentumsrechten zurück, die für diese geteilte Komposition festgelegt wurden.
      • Wenn der fetchOwnership-Parameter mine lautet und der Rechteinhaber, der die Anfrage autorisiert, mehrere geteilte Kompositionen besitzt, die mit der ID der Datenansicht verknüpft sind, gibt die API den Fehler 400 zurück.
      • Wenn der fetchOwnership-Parameter effective lautet, gibt die API die kanonischen Daten zu Eigentumsrechten für die Kompositionsansicht zurück. Diese Daten berücksichtigen die Daten zu Eigentumsrechten aller geteilten Kompositionen, die mit viewId verknüpft sind, unabhängig davon, welche Rechteinhaber Inhaber der geteilten Kompositionen sind.
  • fetchOwnershipConflicts
    • Wenn die Asset-ID einen shareId angibt, gibt die API eine 400-Fehlerantwort zurück.
    • Wenn die Asset-ID einen viewId angibt, gibt die API eine Liste der eigentumsrechtlichen Konflikte in Verbindung mit der Kompositionsansicht zurück.

assets.insert

Mit dieser Methode wird eine asset-Ressource erstellt. YouTube weist eine ID zu, um diese Ressource eindeutig zu identifizieren. Diese ID, die als Wert des Attributs id in der API-Antwort zurückgegeben wird, ist ein shareId.

Hinweis:shareIds und viewIds werden nur für Kompositions-Assets verwendet. Bei anderen Arten von Assets wird kein zweistufiges Modell für die Verwaltung von Asset-Daten verwendet.

„assets.update“ und „assets.patch“

Mit diesen Methoden werden Metadaten für ein Asset aktualisiert. In beiden Anfragen gibt der Parameter assetId das zu aktualisierende Asset an. Außerdem ist der Anfragetext in beiden Anfragen eine asset-Ressource, bei der der Attributwert id mit dem Parameterwert assetId übereinstimmen muss.

  • Wenn der Parameter assetId und das Attribut id einen shareId angeben, aktualisiert die API-Anfrage die angegebene geteilte Komposition.
  • Wenn der Parameter assetId und das Attribut id eine viewId angeben und der Rechteinhaber, der die Anfrage autorisiert, nur eine geteilte Komposition besitzt, die mit dieser viewId verknüpft ist, wird diese geteilte Komposition von der API-Anfrage aktualisiert.
  • Wenn der Parameter assetId und das Attribut id eine viewId angeben und der Rechteinhaber, der die Anfrage autorisiert, mehrere geteilte Kompositionen besitzt, die mit dieser viewId verknüpft sind, gibt die API-Anfrage den Fehler 400 zurück.

assetMatchPolicy.get

Diese Methode gibt die Abgleichsrichtlinie zurück, die für einen bestimmten Inhalt definiert wurde. Der Parameter assetId der Anfrage identifiziert das Asset.

  • Wenn der assetId-Parameter eine shareId angibt, enthält die API-Antwort die Inhaltsmetadaten, die der Rechteinhaber, der die API-Anfrage autorisiert, für die geteilte Komposition festgelegt hat.
  • Wenn der assetId-Parameter eine viewId angibt, gibt die API den kanonischen Metadatensatz für die Kompositionsansicht zurück. Diese Metadaten berücksichtigen die Asset-Metadaten, die für alle geteilten Kompositionen bereitgestellt werden, die mit viewId verknüpft sind, unabhängig davon, welche Rechteinhaber die geteilten Kompositionen haben.

assetMatchPolicy.update und assetMatchPolicy.patch

Mit diesen Methoden wird die Abgleichsrichtlinie für einen bestimmten Inhalt aktualisiert. Der Parameter assetId der Anfrage identifiziert das Asset.

  • Wenn der assetId-Parameter eine shareId angibt, aktualisiert die API-Anfrage die Abgleichsrichtlinie für diese geteilte Komposition.
  • Wenn der assetId-Parameter eine viewId angibt und der Rechteinhaber, der die Anfrage autorisiert, nur eine geteilte Komposition besitzt, die mit dieser viewId verknüpft ist, aktualisiert die API-Anfrage die Abgleichsrichtlinie für diese geteilte Komposition.
  • Wenn der assetId-Parameter eine viewId angibt und der Rechteinhaber, der die Anfrage autorisiert, mehrere geteilte Kompositionen besitzt, die mit dieser viewId verknüpft sind, gibt die API-Anfrage den Fehler 400 zurück.

assetRelationships.list

Diese Methode gibt eine Liste von Asset-Beziehungen für einen bestimmten Inhalt zurück. Der Parameter assetId der Anfrage identifiziert das Asset.

  • Wenn der Parameter assetId eine shareId angibt, enthält die API-Antwort eine Liste der verknüpften Tonaufnahmen-Assets. Die Liste kann mehrere Elemente enthalten. In jeder assetRelationship-Ressource ist die Asset-ID der Tonaufnahme der parentAssetId und die shareId ist die childAssetId.
  • Wenn der assetId-Parameter eine viewId angibt, identifiziert die API-Antwort die mit dieser viewId verknüpfte Tonaufnahme. Die Antwort enthält maximal eine Ressource.
  • Wenn der assetId-Parameter einen Tonaufnahmeninhalt identifiziert, kann die API-Antwort mehrere Beziehungen enthalten.
    • Wenn die Inhalts-ID der Tonaufnahme die parentAssetId in einer zurückgegebenen assetRelationship-Ressource ist, identifiziert die childAssetId die Kompositionsansicht (viewId), die mit dieser Tonaufnahme verknüpft ist. Jede Tonaufnahme hat genau eine solche Beziehung.
    • Wenn die Asset-ID der Tonaufnahme childAssetId ist, identifiziert die parentAssetId ein Video, das die Tonaufnahme enthält, z. B. ein Musikvideo oder ein Art-Track-Video. Jede Tonaufnahme kann mehrere solcher Beziehungen haben.

assetRelationships.insert

Mit dieser Methode wird eine Beziehung zwischen zwei Assets erstellt. Mit dieser Methode kannst du angeben, dass du der Rechteinhaber eines Anteils der Komposition bist, die mit einer Tonaufnahme verknüpft ist.

Lege in der assetRelationship-Ressource im Anfragetext das Attribut parentAssetId auf die Asset-ID der Tonaufnahme fest. Legen Sie das Attribut childAssetId auf shareId fest.

assetSearch.list

Mit dieser Methode wird basierend auf den Asset-Metadaten nach Assets gesucht. Die API-Antwort enthält eine Liste von assetSearch-Ressourcen, in der das Attribut id jeder Ressource eine Asset-ID identifiziert. Der Wert der Eigenschaft id ist eine Asset-ID.

  • Wenn die Ressource assetSearch eine Zusammensetzung identifiziert, ist der Attributwert id ein shareId.

assetShares.list

Diese Methode gibt eine Zuordnung von Kompositionsaufrufen zu geteilten Kompositionen zurück. Der Parameter assetId der Anfrage kann einen viewId- oder shareId-Wert angeben.

  • Wenn der Parameter assetId einen viewId angibt, enthält die API-Antwort eine Liste von assetShare-Ressourcen. Jede Ressource identifiziert eine geteilte Komposition, die mit der angegebenen Kompositionsansicht verknüpft ist und dem Rechteinhaber gehört, der die Anfrage autorisiert.

    Die API-Antwort kann mehrere assetShare-Ressourcen enthalten. Der häufige Anwendungsfall, in dem eine viewId mehreren shareIds zugeordnet wird, die demselben Rechteinhaber gehören, wird im Abschnitt Informationen zum Asset-Modell der Komposition dieses Dokuments beschrieben.

  • Wenn der Parameter assetId einen shareId angibt, enthält die API-Antwort eine Liste von assetShare-Ressourcen. Jede Ressource identifiziert eine Kompositionsansicht, die mit der angegebenen geteilten Komposition verknüpft ist. Die Antwort enthält eine Ressource für jede Tonaufnahme, mit der die geteilte Komposition verknüpft ist. Jede Tonaufnahme ist mit genau einer Kompositionsansicht verknüpft.

claimSearch.list

Diese Methode gibt eine Liste von Ansprüchen zurück, die den angegebenen Suchkriterien entsprechen. Mit dem assetId-Parameter der Methode kannst du nach Ansprüchen suchen, die mit einem bestimmten Inhalt verknüpft sind.

  • Wenn in der API-Anfrage ein shareId angegeben wird, gibt die API einen 400-Antwortcode zurück.

  • Wenn in der API-Anfrage ein viewId angegeben wird, gibt die API eine Liste von Ansprüchen zurück, die mit der angegebenen Kompositionsansicht verknüpft sind, die genau einem Tonaufnahmen-Asset zugeordnet ist.

metadataHistory.list

Diese Methode gibt eine Liste aller für einen Inhalt bereitgestellten Metadaten zurück, unabhängig davon, welcher Rechteinhaber die Daten bereitgestellt hat. Der Parameter assetId der Anfrage gibt das Asset an, für das Daten abgerufen werden.

  • Wenn in der API-Anfrage ein shareId angegeben wird, gibt die API den neuesten Satz an Metadaten für diese geteilte Komposition zurück.

  • Wenn in der API-Anfrage ein viewId angegeben wird, gibt die API eine Liste zurück, in der jeder Eintrag den neuesten Satz von Metadaten für jede geteilte Komposition enthält, die mit dieser Kompositionsansicht verknüpft ist.

ownership.get

Diese Methode gibt die Daten zu Eigentumsrechten zurück, die für einen bestimmten Inhalt definiert wurden. Der Parameter assetId der Anfrage identifiziert das Asset.

  • Wenn der assetId-Parameter eine shareId angibt, enthält die API-Antwort die Daten zu Eigentumsrechten, die der Rechteinhaber, der die API-Anfrage autorisiert, für die geteilte Komposition festgelegt hat.
  • Wenn der assetId-Parameter eine viewId angibt, gibt die API den kanonischen Satz von Daten zu Eigentumsrechten für die Kompositionsansicht zurück. In der Antwort werden die Daten zu Eigentumsrechten für alle geteilten Kompositionen zusammengetragen, die mit viewId verknüpft sind, unabhängig davon, welche Rechteinhaber die Eigentumsrechte besitzen.

owner.update und ownership.patch

Mit diesen Methoden werden die Daten zu Eigentumsrechten für einen bestimmten Inhalt aktualisiert. Der Parameter assetId der Anfrage identifiziert das Asset.

  • Wenn der assetId-Parameter eine shareId angibt, aktualisiert die API-Anfrage die Daten zu Eigentumsrechten für diese geteilte Komposition.
  • Wenn der assetId-Parameter eine viewId angibt und der Rechteinhaber, der die Anfrage autorisiert, nur eine geteilte Komposition besitzt, die mit dieser viewId verknüpft ist, aktualisiert die API-Anfrage die Daten zu Eigentumsrechten für diese geteilte Komposition.
  • Wenn der assetId-Parameter eine viewId angibt und der Rechteinhaber, der die Anfrage autorisiert, mehrere geteilte Kompositionen besitzt, die mit dieser viewId verknüpft sind, gibt die API-Anfrage den Fehler 400 zurück.

ownershipHistory.list

Diese Methode gibt eine Liste aller Daten zu Eigentumsrechten zurück, die für einen Inhalt bereitgestellt wurden, unabhängig davon, welcher Rechteinhaber die Daten bereitgestellt hat. Der Parameter assetId der Anfrage gibt das Asset an, für das Daten abgerufen werden.

  • Wenn in der API-Anfrage ein shareId angegeben wird, gibt die API die neuesten Daten zu Eigentumsrechten für diese geteilte Komposition zurück.

  • Wenn in der API-Anfrage ein viewId angegeben wird, gibt die API eine Liste zurück, in der jeder Eintrag den neuesten Satz von Daten zu Eigentumsrechten für eine geteilte Komposition enthält, die mit dieser Kompositionsansicht verknüpft ist.