Asset-Labels verwenden

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.

Mit Inhaltslabeln kannst du Inhalte benutzerdefinierte Kategorien zuweisen. Hierdurch wird die Organisation deiner Inhaltsbibliothek erleichtert. Du kannst basierend auf ihren Labeln nach Inhalten suchen, wodurch zudem Anwendungsfälle erleichtert werden, bei der die Aktualisierung bestimmter Gruppen von Inhalten erforderlich ist.

In diesem Leitfaden wird erläutert, wie die YouTube Content ID API verwendet wird, um eine Reihe gängiger Funktionen für Labels auszuführen. Mehrere Abschnitte dieses Leitfadens enthalten Beispiele, die auf den Google APIs Explorer verweisen und Daten darin darstellen, sodass Sie jede Abfrage testen können.

Asset-Labels erstellen

Die API unterstützt zwei Möglichkeiten zum Erstellen von Asset-Labels:

  • Rufen Sie die Methode assetLabels.insert auf. Der Anfragetext ist eine assetLabel-Ressource, in der das Attribut labelName den eindeutigen Namen des neuen Labels angibt. Die API gibt den HTTP-Antwortcode 409 (Conflict) zurück, wenn bereits ein Label mit diesem Namen vorhanden ist.

    Die folgende Abfrage ruft die Methode assetLabels.insert auf, um ein neues Label mit dem Namen Explorer Test zu erstellen. Der Text der Beispielanfrage lautet:

    {
  "labelName": "Explorer Test"
}

    In der Anfrage werden keine Abfrageparameter festgelegt. Wenn dein Google-Konto jedoch mit mehreren Rechteinhaberkonten verknüpft ist, musst du auch einen Wert für den Parameter onBehalfOfContentOwner festlegen.

    [no parameters set]

  • Rufe die Methode assets.update auf, um die Labels für ein Asset zu aktualisieren. Lege in der Anfrage das Attribut label[] der Ressource asset auf eine Liste der Labels fest, die mit dem Asset verknüpft sind. Die API erstellt automatisch neue Asset-Labels für alle Labels in der Liste, die zuvor nicht explizit als assetLabel-Ressourcen erstellt wurden.

Asset-Labels eines Rechteinhabers auflisten

Rufe die Methode assetLabels.list auf, um eine Liste der Asset-Labels eines Rechteinhabers abzurufen.

  • Standardmäßig gibt die API alle Asset-Labels für den Rechteinhaber zurück.
  • Wenn du einen Wert für den Abfrageparameter labelPrefix festlegst, gibt die API nur die Asset-Labels des Rechteinhabers zurück, die mit dem angegebenen String beginnen.

Mit der folgenden Abfrage wird die Methode assetLabels.list aufgerufen, um alle Labels für einen Rechteinhaber abzurufen. Hinweis: Wenn dein Google-Konto mit mehreren Rechteinhaberkonten verknüpft ist, musst du einen Wert für den Parameter onBehalfOfContentOwner festlegen. Andernfalls gibt die Anfrage den Fehler 400 (Bad Request) zurück.

[no parameters set]

Die folgende Abfrage ruft dieselbe Methode auf, setzt den Wert des labelPrefix-Parameters jedoch auf news. Daher gibt die API nur Labels zurück, die mit diesem String beginnen.

labelPrefix=news

Labels eines Assets aktualisieren

Du kannst die Labels eines Assets aktualisieren, indem du beim Aufrufen der Methode assets.update den Wert der Eigenschaft label[] festlegst. Wenn Sie ein Asset aktualisieren, wird die vorherige Labelliste entfernt und durch die Liste ersetzt, die in der API-Anfrage gesendet wurde. Wenn Sie die vorherige Labelliste beibehalten möchten, sollten Sie also die assets.list-Methode verwenden, um die ursprüngliche Liste der Labels abzurufen, und dann den Wert des label[]-Attributs ändern. Wenn der Eigenschaftswert leer ist, entfernt die API die Labels, die zuvor mit dem Asset verknüpft waren.

Du kannst dasselbe Label mit mehreren Assets und mehrere Labels mit demselben Asset verknüpfen. Labels können Leerstellen enthalten. Dies bedeutet, dass ein einzelnes Label mehr als nur ein Wort enthalten kann. Unzulässige Zeichen sind spitze Klammern, Kommas, Doppelpunkte und vertikale Striche (|). Jedes Label muss mindestens 2 Byte lang sein und darf nicht länger als 30 Byte sein. Jeder Rechteinhaber kann bis zu 30 Labels zu einem Inhalt hinzufügen. Die maximale Gesamtlänge aller Labels für einen Inhalt beträgt 500 Byte.

Inhalte anhand von Labels suchen

Wenn du eine Liste der Assets abrufen möchtest, die mit einem Label oder einer Gruppe von Labels verknüpft sind, rufe die Methode assetSearch.list auf. Verwende dabei den Abfrageparameter labels, um eine durch Kommas getrennte Liste von Asset-Labels anzugeben.

  • Standardmäßig gibt die API eine Liste der Inhalte zurück, die alle angegebenen Asset-Labels haben.
  • Wenn in deiner API-Anfrage der includeAnyProvidedLabel-Parameter auf true gesetzt wird, gibt die API alle Assets zurück, die mit mindestens einem der angegebenen Labels übereinstimmen.