Dieses Dokument bietet einen Überblick über die Medien-API von Video Cloud.
Die Medien-API ist eine REST-basierte API für den Zugriff auf die Inhalte und Metadaten Ihres Video Cloud-Kontos. Da die Medien-API auf REST basiert, ist der Zugriff darauf von zahlreichen Komponenten Ihrer Webanwendungen aus möglich, also nicht nur mittels Client, sondern beispielsweise auch über dynamisch generierte Webseiten und serverseitige Synchronisierungsprozesse.
Um nicht autorisierten Zugriff auf die Metadaten im Konto zu verhindern, schützt Video Cloud den Zugriff auf die API mit Token, die bei API-Aufrufen als Parameter übergeben werden. Ebenso wie andere webbasierte APIs werden Token für Sie von Video Cloud generiert und von Ihnen geschützt.
Zunächst benötigen Sie die Token für Ihr Konto. Die Medien-API ist für Video Cloud Express-Kunden, die die Pläne mit den Monatsbeiträgen in Höhe von 99 bzw. 199 US-Dollar verwenden, nicht verfügbar. Lesetoken für die Lesemethoden der Medien-API sind für Video Cloud Express-Kunden verfügbar, die den Plan mit einem Monatsbeitrag von 499 US-Dollar nutzen, und die vollständige Medien-API ist für Video Cloud Pro- und Enterprise-Kunden verfügbar.
In diesem Überblick lernen Sie die Medien-API kennen und erhalten folgende Informationen:
Funktionen der Medien-API
REST (oder Representational State Transfer) ist eine Standardmethode für den Zugriff auf Daten, die in einem Remotesystem über HTTP gespeichert sind. REST ist mit SOAP verwandt und stellt eine der Technologien zum Betrieb von Webdiensten dar. Die Hauptaufgabe dieser Methode besteht in der Abstraktion der Ergebnisse des Remotesystems bei der Übertragung des Status (oder der Informationen). Der Code muss nur das Format der zurückgesendeten Daten identifizieren können.
Die Medien-API schließt Lese- und Schreibmethoden ein.
- Die Lese-API besteht aus einem Satz von Methoden, die eine Reihe von Anfragen auf den (aus Leistungsgründen zwischengespeicherten) Servern ausführen und Datensätze in DTOs (Data Transfer Objects) zurückgeben. Beispiel: Eine API-Methode ist
find_all_videos, von der eine Liste von VideoDTOs zurückgegeben wird, wobei jedes VideoDTO die Metadaten für ein bestimmtes Video enthält. Die Rückgabedaten werden entweder als JSON-Zeichenfolgen oder als MRSS-formatierte XML formatiert. JSON (JavaScript Object Notation) ist eine einfache Möglichkeit zur Übertragung komplexer Objekte als Zeichenfolgen, und nahezu jede heutige Sprache kann eine große Anzahl von öffentlich verfügbaren Bibliotheken verarbeiten, um JSON-Zeichenfolgen in systemeigenen Objekten zu analysieren. MRSS (Media Really Simple Syndication) ist ein RSS-Modul, das für das Syndizieren von Multimediadateien (Audio-, Video- und Bilddateien) in RSS-Feeds verwendet wird.
- Die Schreib-API besteht aus einer Gruppe von Methoden, die Videos und Wiedergabelisten erstellen, aktualisieren oder löschen. Eine Schreib-API-Methode ist zum Beispiel
create_video, mit der Sie eine Videodatei und ihre zugehörigen Metadaten übergeben und ein Video im Video Cloud-Konto erstellen können.
Aufrufen von Medien-API-Methoden
Bei Methodenaufrufen mithilfe von REST handelt es sich grundsätzlich um HTTP GET-Anforderungen (für Lesemethoden) oder POST-Anforderungen (für Schreibmethoden) an eine bestimmte URL auf Servern von Video Cloud. Die Anforderung schließt den Namen der aufgerufenen Methode sowie die Eingabeargumente ein, die als Parameter in der URL übergeben werden. Der Text der HTTP-Antwort beinhaltet die Ergebnisse des HTTP-Aufrufs als JSON-Zeichenfolge oder als MRSS-formatiertes XML-Objekt. Für alle Medien-API-Aufrufe wird die Basis-URL verwendet (http://api.brightcove.com/services). Der Zugriff auf Video Cloud-Dienste über IP-Adressen wird nicht unterstützt und sollte unter allen Umständen vermieden werden. Video Cloud-IP-Adressen können jederzeit ohne Vorankündigung geändert werden. Änderungen können Fehler von Systemen nach sich ziehen, die versuchen, über IP-Adressen auf die Dienste zuzugreifen.
Wichtiger Hinweis für japanische Publisher
Wenn Sie Kunde unseres japanischen Joint Ventures Brightcove KK sind, müssen Sie zum Zugreifen auf die Medien-API eine andere URL verwenden. Alle Medien-API-Aufrufe müssen mit http://api.brightcove.co.jp anstelle von http://api.brightcove.com beginnen.
Methodenaufrufe erfordern ebenfalls ein Token. Video Cloud stellt Token für Konten aus. Mit Token erhalten Sie bei Verwendung der API Zugriff auf Ihr Konto. In der API sind separate Token für Lese- und Schreibmethoden enthalten. Sie fügen das Token als URL-Parameter an den Aufruf an, z. B. token=[tokenString], wobei tokenString das URL-codierte Token ist. Medien-API-Token enden im Allgemeinen mit mindestens einem Punkt (.). Schließen Sie die Punkte ein, wenn Sie die API-Token verwenden, da diese beim Ausschneiden und Einfügen leicht verloren gehen können. Sie können die API-Token auf der Seite „Kontoinformationen: Kontoeinstellungen: API-Verwaltung“ in Video Cloud Studio anzeigen und verwalten. Diese Seite beinhaltet auch eine Schaltfläche zum Versenden eines Tokens per E-Mail oder zum Kopieren eines Tokens in die Zwischenablage. Weitere Informationen zu Token finden Sie unter Verwalten von Token der Medien-API.
Beispiel: Um alle Videos im Konto abzurufen, wird eine HTTP-Anforderung gestellt, die folgendermaßen aussieht:
http://api.brightcove.com/services/library?command=find_all_videos
&token=0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.
Dies ist eine Arbeitsanforderung, die Sie hier testen können. Die Ergebnisse des Aufrufausdrucks sind schnell sichtbar. Hierbei handelt es sich um einen rohen Methodenaufruf. Die Daten, die Sie zurückerhalten, sind weder verarbeitet noch formatiert. In den Beispielen werden Methoden aufgezeigt, mit denen die zurückgegebenen Daten den Anforderungen einer Anwendung entsprechend gestaltet werden können. (Hinweis: Für diesen Aufruf wird ein Demokonto verwendet. Damit Sie Ihr Konto verwenden können, ersetzen Sie Ihr Lesetoken im &token-Argument.)
Wichtiger Hinweis für japanische Publisher
Einbeziehen der API in die Anwendung
Da es sich bei Medien-API-Anforderungen um einfache HTTP-Aufrufe handelt, können sie überall in die Anwendung eingebunden werden. Jede verbreitete Websprache (server- oder clientseitig) verfügt über eine Syntax für HTTP-Anforderungen. Mithilfe dieser Syntax werden API-Aufrufe in Anwendungen eingeschlossen. Darüber hinaus haben Entwickler mit fundierten Video Cloud-Kenntnissen Software Development Kits (SDKs) für die gängigsten weborientierten Sprachen erstellt, die Sie als systemeigene Klassen in Ihre Anwendungen einbinden können, um den einfachen API-Zugriff zu ermöglichen. In den Video Cloud-SDKs finden Sie eine aktuelle Liste mit verfügbaren Medien-API-SDKs. Besuchen Sie zudem Open Source @ Brightcove, eine Community-unterstützte Initiative zum Hosten zahlreicher Anwendungen, SDKs und Tools für die Video Cloud-Plattform an einer zentralen Stelle.
Es besteht die Möglichkeit, dass die Anforderung nach Bedarf (On-Demand) erfolgt, zum Beispiel, wenn eine Seite geladen wird, ein Benutzer auf eine Schaltfläche klickt oder wenn ein anderes Ereignis eintritt. Schließen Sie dazu die HTTP-Anforderung in eine Funktion ein, und rufen Sie sie als Reaktion auf ein programmgesteuertes Ereignis, wie ein onClick-Ereignis, auf. Außerdem muss die Antwort behandelt werden, und wenn Sie nicht JavaScript verwenden, analysieren Sie die JSON-Zeichenfolge oder die MRSS-Ausgabe in systemeigenen Objekten, damit Sie mit den Daten arbeiten können. JSON gibt Daten nicht zuverlässig in einer bestimmten Reihenfolge zurück; es wird empfohlen, einen JSON-Parser zu verwenden, um die Felder zu ermitteln, die Sie verwenden möchten.
Mit den API-Schreibmethoden kann eine Clientanwendung erstellt werden, mit der das Video Cloud-Konto in das Content-Management-System integriert wird. Sie können auch eine Desktopanwendung schreiben, die lokal ausgeführt wird und keinen Server zwischen dem Client und Video Cloud benötigt. Eine andere mögliche Architektur beinhaltet einen Flash-Client, wobei der HTTP-Stapel von Flash verwendet wird. Sie können auch Adobe AIR, den neuen Desktopclient von Adobe, verwenden, um eine Flash-basierte Desktopuploadanwendung zu erstellen.
API-Parameter
Die grundlegenden API-Leseaufrufe wie find_all_videos können mit zusätzlichen Parametern optimiert werden. In den API-Referenzinformationen wird der vollständige Satz aufgelistet. Hier finden Sie dagegen einen Überblick über einige der möglichen Aktionen, die Sie ausführen können:
- Anzeigen der Suchergebnisse auf Seiten. Sie können Seiten mit Daten zurückgeben, wenn Sie zahlreiche Ergebnisse erwarten. Sie können die Seitenanzahl festlegen und auswählen, dass eine bestimmte Seite zurückgegeben werden soll. Die maximale Seitenanzahl beträgt im Allgemeinen 100. Wenn Sie die Anzahl nicht festlegen, werden die Ergebnisse auf insgesamt 100 Seiten zurückgegeben.
- Auswählen von Feldern für den Rückgabesatz. In den meisten Verwendungsfällen werden nur bestimmte Datenfelder wie das Namen- und das Kurzbeschreibungsfeld benötigt. Sie können die API zwingen, nur diese Felder zurückzugeben, um die Aufrufzeit zu optimieren.
- Sortierung. Sie können eine Sortierreihenfolge angeben, die für den Rückgabesatz übernommen werden soll, zum Beispiel alphabetisch, nach Erstellungs-, Veröffentlichungs- und Änderungsdatum oder nach der Anzahl der Wiedergaben in den vergangenen Wochen bzw. der gesamten Anzahl der Wiedergaben.
Für die grundlegenden API-Schreibaufrufe wie create_video werden Parameter verwendet, mit denen die Metadaten für das Video, das Sie erstellen, hinzugefügt werden. Es stehen außerdem API-Schreibmethoden zum Erstellen, Aktualisieren und Löschen von Wiedergabelisten und zum Erstellen von Cue-Points, Bildern und Logo-Overlays zur Verfügung.
Arbeiten mit JSON
Wenn Sie JSON-Zeichenfolgen verwenden, greifen Sie auf die entsprechende JSON-Syntax zurück. Zeichenfolgenwerte sind in Anführungszeichen eingeschlossen, Zahlen und boolesche Werte hingegen nicht. Bei create_video, token und filename handelt es sich um Zeichenfolgen, bei create_multiple_renditions hingegen um einen booleschen Wert:
{"method": "create_video",
"params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
"video" : {"id":38,"name":"Cookies!","shortDescription":"yumyumyumyum tasty!"},
"filename":"miamiMoon.mov",
"create_multiple_renditions" : true}}
Lesen Sie die Medien-API-Referenzinformationen, um die richtige Signatur für jede verwendete Methode sowie Medien-API-Beispiele zu ermitteln. Weitere Informationen zu JSON finden Sie unter json.org.
Zwischenspeicherung
Zur Leistungssteigerung werden API-Aufrufe auf Video Cloud-Servern gespeichert. Wenn ein Aufruf erfolgt, überprüft Video Cloud zuerst den Cache. Wenn der Aufruf nicht zwischengespeichert wurde oder der Cache abgelaufen ist, wird der Aufruf direkt an die Datenbank geleitet, und Video Cloud sendet die Ergebnisse zurück und führt außerdem eine Zwischenspeicherung durch. Der Cache läuft nach 5 Minuten ab. Wenn Sie zusätzliche Aufrufe in diesem Fenster ausführen, stammen die Ergebnisse aus dem Cache und nicht aus der Datenbank.
Bei der Zwischenspeicherung werden keine Änderungen berücksichtigt, die Sie ggf. mithilfe von Video Cloud Studio oder des Batch-Uploads an der Bibliothek vornehmen. An der Bibliothek vorgenommene Änderungen, die sich auf einen Aufruf auswirken würden, werden bis zum Ablauf des Cache nicht in den Ergebnissen des Aufrufs angezeigt. Berücksichtigen Sie dies, wenn Sie den Code testen. Die API funktioniert möglicherweise ordnungsgemäß, auch wenn die korrekten Ergebnisse nicht angezeigt werden.
Fehlerbehandlung
Die API versucht, häufige Fehler zu erfassen, zum Beispiel eine nicht vorhandene video_id, und sie auf codegerechte Art zu behandeln. Die meisten Fehler werden als JSON-Zeichenfolgen mit einem Fehlerparameter zurückgegeben, der folgendermaßen aussieht:
{"error": "Beim Verarbeiten Ihrer Anforderung ist ein unbekannter Fehler aufgetreten. ","Code":100}
Wenn die Ausgabe MRSS ist, werden Fehler in ein <error>-Element eingeschlossen, das einen Fehlercode und eine Fehlermeldung beinhaltet.
Soweit möglich sollten Fehler vom Code immer benutzerfreundlich behandelt werden, anstatt den Endbenutzer mit komplizierten Meldungen oder leeren Seiten zu konfrontieren. Durch Behandlung des „Fehler“-Parameters des Ergebnisobjekts (nach einer JSON-Analyse der Antwort) erfahren Sie, wo möglicherweise Fehler aufgetreten sind, damit Sie entsprechend darauf reagieren und eine Fehlermeldung für den Endbenutzer programmieren können.
Fehlermeldungen, die von der Medien-API zurückgegeben werden, schließen einen numerischen Fehler ein, mit dem Fehler nach Typ klassifiziert werden. Weitere Informationen finden Sie in den Referenzinformationen zu den Fehlermeldungen.
Tokenverwaltung und -sicherheit
Schützen Sie Ihr Token vor Missbrauch – es bietet Zugriff auf die Bibliothek. Dies ist besonders wichtig, wenn Sie clientseitige API-Aufrufe betrachten. Alle Webbesucher können die Option „Quelle anzeigen“ auswählen und dadurch das API-Token sehen, mit dem Sie die Metadaten möglicherweise einschließlich direkter Links zu Ihren Ressourcen abrufen können.
In Medien-API: Leitfaden zur Sicherheit finden Sie weitere Details und Strategien zur Tokensicherheit.
Einschränkungen der Medien-API
Im Allgemeinen können alle Aktionen, die mit einem Video oder einer Wiedergabeliste im Video Cloud Studio-Medienmodul ausgeführt werden können, auch mit den Medien-Schreib-APIs ausgeführt werden. Es gibt einige Ausnahmen. Die folgenden Eigenschaften von Videos können mithilfe der Medien-Schreib-APIs festgelegt und geändert werden:
- Flag für virale Syndikation
- Bumper
- „Force Ad Request“-Flag
Medien-API-Beispiele
Wir haben zahlreiche Medien-API-Beispiele erstellt, um verschiedene Methoden zur Verwendung der Medien-API zu präsentieren. In den Medien-API-Referenzinformationen sind ebenfalls Verwendungsbeispiele enthalten.
Verwandte Informationen
Sie haben nun einen Überblick über die Medien-API und können ergänzend auch die sonstige Dokumentation zur Medien-API lesen:
