Überblick: CMS-API

In diesem Thema erhalten Sie einen Überblick über die CMS-API. Das CMS API Bietet nicht zwischengespeicherten Lesezugriff auf die Daten. Dies ist wichtig für zeitkritische Veröffentlichungsworkflows, da Sie mithilfe von Änderungen an Videos und Wiedergabelisten vornehmen CMS API und lesen Sie schnell die Daten, um zu überprüfen, ob sie korrekt sind.

API-Referenz

Siehe auch die API-Referenz.

Allgemeine Informationen

Basis-URL

Die Basis-URL für die CMS API ist:

        https://cms.api.brightcove.com/v1

Account-Pfad

In jedem Fall werden Anfragen für eine bestimmte gestellt Video Cloud Konto. Sie fügen also immer den Begriff accounts gefolgt von Ihrer Konto-ID zur Basis-URL hinzu:

        https://cms.api.brightcove.com/v1/accounts/{account_id}

Authentifizierung

Für die Authentifizierung von Anfragen ist Folgendes erforderlich Authorization header:

        Authorization: Bearer {access_token}

Das access_token ist ein temporäres OAuth2-Zugriffstoken, das von der abgerufen werden muss Brightcove OAuth Bedienung. Weitere Informationen finden Sie in der Übersicht über Brightcove OAuth.

Die einfachste Möglichkeit, Client-Anmeldeinformationen zu erstellen, ist über die Brightcove Studio-Admin-Seiten. Detaillierte Anweisungen finden Sie unter Anmeldeinformationen für die API-Authentifizierung verwalten

Betrieb

Wenn Sie Client-Anmeldeinformationen anfordern, müssen Sie die Art des Kontozugriffs oder der gewünschten Vorgänge angeben. Im Folgenden finden Sie eine Liste der derzeit unterstützten Operationen für CMS API:

  • Videodaten:

    video-cloud/video/read
    video-cloud/video/create
    video-cloud/video/update
    video-cloud/video/delete
    oder
    video-cloud/video/all
    video-cloud/video/assets/delete (Wird nur benötigt, wenn Sie digitale Master löschen möchten - beachten Sie, dass Sie kann nicht Erhalten Sie diese Berechtigung, wenn Sie Anmeldeinformationen in Studio erstellen. Dies muss über die OAuth-API oder die Von Brightcove Learning Services erstellte Beispiel-App.)

  • Playlist-Daten:

    video-cloud/playlist/read
    video-cloud/playlist/create
    video-cloud/playlist/update
    video-cloud/playlist/delete
    oder
    video-cloud/playlist/all

  • Benachrichtigungen:

Ratenbegrenzung

Diese CMS API Bietet nicht zwischengespeicherten Lesezugriff auf die Daten. Dies ist wichtig für zeitkritische Veröffentlichungsworkflows, da Sie mithilfe von Änderungen an Videos und Wiedergabelisten vornehmen CMS API und lesen Sie schnell die Daten, um zu überprüfen, ob sie korrekt sind.

Das CMS API ist nicht für die Verwendung in großem Maßstab zur Laufzeit geeignet (z. B. für den Zugriff auf Videos auf einer öffentlichen Webseite mit hohem Datenaufkommen). Für Anwendungen mit hohem Datenverkehr müssen Sie eine zwischengespeicherte Schnittstelle verwenden, z. B. die Playback API, Gallery, Players oder die Native SDKs.

Um die Leistung der Video Cloud System, nicht mehr als 20 gleichzeitige Anrufe an die CMS API sind pro Konto erlaubt. Die Zugriffshäufigkeit sollte weniger als 10 Anfragen pro Sekunde betragen.

Wenn mehrere Anwendungen in das integriert werden CMS API Für ein Konto sollten diese Anwendungen über eine Back-Off- und Wiederholungslogik verfügen, um Fälle zu behandeln, in denen Parallelitäts- oder Ratenlimits erreicht werden.

Wenn entweder die Geschwindigkeits- oder Gleichzeitigkeitsgrenze überschritten wird, a 429 - TOO_MANY_REQUESTS Fehler wird zurückgegeben.

Konflikte mit der Referenz-ID

Um die Eindeutigkeit von Referenz-IDs zu gewährleisten, wird die CMS API Sperrt die ID für bis zu 3 Minuten nach jeder Operation an dem Video, dem sie zugewiesen ist. Dies kann dazu führen, dass 409-Fehler zurückgegeben werden, wenn Sie versuchen, eine Anforderung zu wiederholen, die zu schnell fehlschlägt, oder wenn Sie versuchen, eine Referenz-ID zu früh nach dem Löschen des Videos, dem sie zuvor zugewiesen war, wiederzuverwenden. Siehe die Fehlermeldungsreferenz für mehr Details.

Limit für Video-Assets

Es gibt ein Limit von 1.000 Assets pro Video. Zu den Assets gehören Wiedergaben, Audiospuren, Textspuren und Bilder sowie der digitale Master. Wiedergaben und Bilder summieren sich selten auf mehr als 10-15 Assets. Selbst wenn Sie separate Audio- und Textspuren für 150 verschiedene Sprachen hätten, hätten Sie immer noch weniger als 350 Assets.

Hinweise zur Verwendung

Methoden

Derzeit unterstützt die API die folgenden Anfragetypen:

  • GET
  • POST
  • PATCH
  • PUT
  • DELETE

Parameter

Beachten Sie, dass alle Parameter Optional. Sofern nicht anders angegeben, gelten sie für GET Anfragen für Videos und Playlists.

GET-Anforderungsparameter
Parameter Beschreibung
q Abfragestring für Suchen - siehe Suchsyntax für mehr Informationen
limit Anzahl der zurückzugebenden Videos – muss eine ganze Zahl zwischen 1 und 100 sein. Standard: 20
offset Anzahl der zu überspringenden Videos (für Paging-Ergebnisse). Muss eine positive ganze Zahl sein. Standard: 0
sort Eine Zeichenfolge, die das Feld angibt, nach dem sortiert werden soll. Beginnen mit - absteigend zu sortieren. Wenn ein Wert für q bereitgestellt wird, ist die Standardsortierung nach "Score" (Relevanz der Suchergebnisse zur ursprünglichen Abfrage). Wenn kein Wert für q bereitgestellt wird, ist die Standardsortierung nach updated_at absteigend. Die folgenden Felder sind für die Sortierung gültig: name reference_id, created_at, published_at, updated_at, schedule_starts_at, schedule_ends_at state, plays_total, und plays_trailing_week

Brightcove's CMS API bietet eine programmatische Möglichkeit, nach Videos in Ihrem zu suchen Video Cloud Bibliothek.

Um einfache und komplexe Suchen in Ihren Videodaten durchzuführen, verwenden Sie die q Parameter:

        https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q={search terms}

Weitere Informationen zur Suche nach Videos finden Sie im Videos suchen dokumentieren.

Bei Wiedergabelisten sind die unterstützten Werte für die Suchzeichenfolge eingeschränkter. Sie können derzeit nach type, name description, und suchen reference_id. Hier sind einige Beispiele für gültige Suchanfragen:

  • q=type:EXPLICIT
  • q=type:ACTIVATED_OLDEST_TO_NEWEST
  • q=type:ALPHABETICAL
  • q=bears+otters(Name, Beschreibung oder Referenz-ID müssen entweder „Bären“ oder „Otter“ enthalten)
  • q=%2Bname:bears+type:EXPLICIT(Name muss „Bären“ enthalten)

Sehen Playlists durchsuchen für mehr Details.

Paging-Ergebnisse

Verwenden Sie die limit Parameter, um anzugeben, wie viele Elemente Sie bei einer Anfrage zurückgeben möchten - bis zu 100. Sie können den offset Parameter dann verwenden, um Ergebnismengen zu durchsuchen, die größer als die sind limit. Die offset ist die Anzahl der zu überspringenden Elemente.

Die folgende Suche gibt beispielsweise Videos 51-75 der Gesamtergebnismenge zurück, vorausgesetzt, die Gesamtergebnismenge enthält mindestens 75 Videos:

        /videos?q=updated_at:2014-01-01..2014-06-30&limit=25&offset=50

Die limit und offset Parameter können sowohl für Videos als auch für Wiedergabelisten verwendet werden.

Best Practice beim Paging

Da möglicherweise gleichzeitige Änderungsvorgänge mit der CMS-API ausgeführt werden, wird empfohlen, beim Blättern durch Ihre Ergebnismenge die folgenden Schritte auszuführen:

  1. Mach ein count Anfrage, um die Gesamtzahl der Videos in Ihrem Resultset abzurufen. 
          /accounts/578380111111/counts/videos?q=tags:nature
  2. Verwenden Sie die limit und offset -Parameter, um Datengruppen aus Ihrer Ergebnismenge zurückzugeben. 
          /accounts/578380111111/videos?q=tags:nature&limit=20&offset=50
  3. Beachten Sie, dass einige Seiten möglicherweise weniger als 20 Videos enthalten. Sie wissen, dass Sie das Ende der Ergebnismenge erreicht haben, wenn Sie so viele Videos wie im ersten angefordert haben count Anfrage.

Zusammenfassend: Rufen Sie so lange Seiten ab, bis Sie eine Videoanzahl erhalten, die dem Original entspricht. count Anfrage, da diese Zahl auf der Seite der Überschätzung liegen sollte. Nachfragen:

      count / page-size + 1 page

Sortieren von Videoergebnissen

Verwenden Sie den Parameter sort=field_name um anzugeben, wie die Ergebnisse sortiert werden sollen - Sie können sowohl Videos als auch Wiedergabelisten sortieren. Sie können nach folgenden Videofeldern sortieren: [1-1]

  • name
  • reference_id
  • created_at
  • published_at
  • updated_at
  • schedule_starts_at(Hinweis: Dies ist das Sortierfeld - das Suchfeld ist schedule.starts_at )
  • schedule_ends_at(Hinweis: Dies ist das Sortierfeld - das Suchfeld ist schedule.ends_at )
  • state
  • plays_total [1-2]
  • plays_trailing_week [1-2]

Anmerkungen

  • [1-1] Wenn Sie keinen Sortierwert für einen Videosuchanruf angeben, werden die Ergebnisse nach Relevanz sortiert. Wenn Sie keinen Sortierwert für einen GET Videoanruf angeben, werden die Ergebnisse updated_at absteigend sortiert.
  • [1-2] Sie können weiter sortieren plays_total oder plays_trailing_week Diese Felder sind jedoch nicht in den Ergebnissen enthalten

Playlist-Ergebnisse sortieren

Sie können Wiedergabelisten nach den folgenden Feldern sortieren:

  • name
  • updated_at(Standard)

Alle Videos und große Datensätze

Wenn Sie alle Videos in Ihrem Konto oder eine große Anzahl von Videos abrufen, müssen Sie einige Dinge beachten:

  1. Sie könnten versucht sein, die größte zulässige zu verwenden limit (100), aber es ist besser, Videos in Stapeln von 25 oder weniger abzurufen, um die Möglichkeit von Zeitüberschreitungen bei API-Anfragen zu minimieren
  2. Beim Blättern durch große Datensätze ist es möglich, dass die Videodaten während des Vorgangs aktualisiert werden, was dazu führen kann, dass sich Elemente in den Antworten verschieben:
    • Möglicherweise wird ein Element auf aufeinanderfolgenden Seiten wiederholt
    • Ein Element kann übersehen werden, da es in einen vorherigen Antwortsatz verschoben wurde

    Um die erste Möglichkeit zu berücksichtigen, sollte Ihre App die vollständige Artikelliste deduplizieren, nachdem Sie das Abrufen von Videos abgeschlossen haben. Um die zweite Möglichkeit zu handhaben, müssen Sie die Gesamtzahl der abgerufenen Elemente (nach der Deduplizierung) mit der erwarteten Anzahl vergleichen und dann die Anforderungen erneut ausführen und die Ergebnisse nach last_modified_date (absteigend) sortieren - das sollte nicht nötig sein mehr als einen Stapel abrufen, um verpasste Artikel abzuholen.

  3. Sie können die Wahrscheinlichkeit der Szenarien im vorherigen Element verringern, indem Sie die zurückgegebenen Ergebnisse entsprechend sortieren. Die Standardsortierung nach Relevanz for searchs basiert auf einem komplexen Algorithmus, der nach Kombinationen von Schlüsselwörtern, Tags und benutzerdefinierten Feldwerten sucht. Wenn Sie auf der Grundlage mehrerer Schlüsselwörter, Tags und/oder benutzerdefinierter Felder nach Videos suchen, ist die Sortierung nach Relevanz genau das Richtige für Sie. Wenn Sie jedoch nur versuchen, alle oder einen großen Satz Ihrer Videos abzurufen, stellen Sie die sort Parameter gibt Ihnen explizit mehr Kontrolle über die Reihenfolge der zurückgegebenen Elemente.

Videofunktionen

Videooperationen umfassen:

  • Erhalten Sie eine Anzahl von Videos oder Suchergebnissen
  • Alle Videos abrufen
  • Rufen Sie ein oder mehrere Videos nach ID oder Referenz-ID ab
  • Videos erstellen, abrufen, aktualisieren und löschen
  • Nach Videos suchen
  • Erhalten Sie Videoquellen, Bilder und die digitalen Masterinformationen
  • Holen Sie sich die Playlists, zu denen ein Video gehört
  • Entfernen Sie das Video aus allen Playlists

Details zu den Videooperationen finden Sie im API-Referenz.

Playlist-Vorgänge

Zu den Playlist-Vorgängen gehören:

  • Anzahl der Wiedergabelisten abrufen
  • Alle Playlists abrufen
  • Playlists erstellen, aktualisieren und löschen
  • Anzahl der Videos in einer Playlist abrufen
  • Holen Sie sich die Videos in eine Playlist

Details zu den Playlist-Operationen finden Sie in der API-Referenz.

Vermögenswerte

Asset-Operationen ermöglichen Ihnen die Verwaltung von Assets, einschließlich Darstellungen, Manifesten, Bildern und Textspuren. Um Assets aufzunehmen, müssen Sie die verwenden Dynamic Ingest API. Das POST und PATCH Operationen für die CMS API /assets kann zum Hinzufügen und Aktualisieren verwendet werden Remote-Assets. CMS API GET-Operationen funktionieren für beide aufgenommene und entfernte Vermögenswerte.

  • Wiedergabeversionen hinzufügen, aktualisieren oder löschen
  • Hinzufügen, Aktualisieren oder Löschen von Metadaten für das digitale Master
  • Manifeste für segmentierte Videotypen wie HLS hinzufügen, aktualisieren oder löschen
  • Poster und Miniaturbilder hinzufügen, aktualisieren oder entfernen
  • Hinzufügen, Aktualisieren oder Entfernen von WebVTT-Textspuren oder DFXP-Untertiteln

Details zu den Asset-Operationen finden Sie im API-Referenz.

Benutzerdefinierte Feldoperationen

Derzeit gibt es eine benutzerdefinierte Feldoperation:

  • Alle benutzerdefinierten Felder für ein Konto abrufen

Details zu den benutzerdefinierten Feldoperationen finden Sie im API-Referenz.

Ordnervorgänge

Ordneroperationen ermöglichen Ihnen:

  • Holen Sie sich eine Liste von Ordnern
  • Ordner erstellen, aktualisieren und löschen
  • Rufen Sie eine Liste von Videos in einem Ordner ab
  • Ein Video zu einem Ordner hinzufügen
  • Ein Video aus einem Ordner entfernen

Einzelheiten zu den Ordnervorgängen finden Sie im API-Referenz.

Benachrichtigungen

Sie können Benachrichtigungen erhalten, wenn video-change Ereignisse in Ihrer Videobibliothek auftreten, oder master-video-change Benachrichtigungen, wenn ein geteiltes Video seine Inhalte automatisch aktualisiert, nachdem das Mastervideo es aktualisiert hat. Die Benachrichtigungen werden an die von Ihnen angegebene URL gesendet, die auf eine Anwendung verweisen sollte, die HTTP-POST-Anfragen bearbeiten kann.

Benachrichtigungsfehler

Das Benachrichtigungssystem behandelt jede 4xx- oder 5xx-Rückgabe vom Kundenserver als einen wiederherstellbaren Fehler. Fehlgeschlagene Rückrufe werden bis zu 20 Mal wiederholt, wobei die Verzögerung zwischen nachfolgenden Rückrufen exponentiell ansteigt. Die ersten Versuche werden innerhalb von Minuten nach dem ersten Rückrufversuch durchgeführt. Wenn der Rückruf weiterhin fehlschlägt und wir bis zum 20. Wiederholungsversuch kommen, wird die Wiederholungsverzögerung einige Tage betragen.

Firewalls

Falls Ihre Organisation eine strenge Richtlinie bezüglich der Quellen des eingehenden Datenverkehrs durch Ihre Firewall hat, lassen wir alle IPs der AWS-Region Ost zu. Dies kann sich ändern, daher sollten alle AWS-IPs auf die Whitelist gesetzt werden. Sehen https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html für mehr Informationen.

Benachrichtigungsvorgänge

Die derzeit für Benachrichtigungen verfügbaren Operationen sind:

  • Abonnements erstellen
  • Holen Sie sich ein oder alle Abonnements
  • Abonnement löschen

Einzelheiten zu den Benachrichtigungsvorgängen finden Sie im API-Referenz.