Support Kontakt Support | Systemstatus Systemstatus

Überblick: Social Syndication API

Unser Social Syndication API ist eine öffentlich zugängliche API, mit der Syndizierungen erstellt, verwaltet und zum Generieren dynamischer Feeds (z. B. MRSS-Feeds) aus einem VideoCloud-Videokatalog verwendet werden können.

In diesem Dokument

Zugehörige Dokumente

Einführung

Die Brightcove Syndication Configuration API ist eine öffentlich zugängliche API, mit der Syndizierungen erstellt, verwaltet und zum Generieren dynamischer Feeds (z. B. MRSS-Feeds) aus a verwendet werden können Video Cloud Videokatalog des Kontos.

Es ist auch eine zugeordnet Syndication Feed API Dies kann verwendet werden, um einen Feed abzurufen, der einer Syndizierung zugeordnet ist.

Verfügbarkeit

Die Syndication-APIs stehen allen zur Verfügung Video Cloud Kunden, die Zugriff auf die Plattform-APIs haben.

API-Referenz / Basis-URL / Header

Unser Konfigurations-API-Referenz enthält alle Details zu den verfügbaren Operationen, Feldern und Parametern.

Die Basis-URL lautet:

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

Alle Anforderungen müssen über einen Autorisierungsheader authentifiziert werden:

Authorization: Bearer {your_access_token}

Informationen zu Zugriffstoken finden Sie im nächsten Abschnitt zur Authentifizierung.

Für jede Anfrage, die einen Anfragetext sendet, müssen Sie auch a einschließen Content-Type: application/json Header.

Beglaubigung

Für den Zugriff auf die Konfigurations-API muss a angegeben werden bearer Token von der Brightcove OAuth-Dienst in der Anfrage Authorization Header. Für die verschiedenen API-Methoden muss außerdem eine der folgenden Operationen (abhängig von der Methode, auf die zugegriffen wird) für die betreffenden Anmeldeinformationen angegeben werden:

  • video-cloud/social/mrss/read
  • video-cloud/social/mrss/write

Diese Vorgänge können über das konfiguriert werden API-Authentifizierungsabschnitt des Studio-Verwaltungsmoduls:

Social Syndizierungsberechtigungen
Social Syndizierungsberechtigungen

Wenn Sie möchten, können Sie auch Anmeldeinformationen über das erstellen OAuth API:

Syndication-Ressource

Die Syndizierungsressource ist ein Objekt, das definiert, wie die Syndizierung erstellt wird. Hier ist ein Beispiel für einen Anforderungshauptteil zum Erstellen einer Syndizierungsressource:

  {
    "name": "80s music videos syndication",
    "type": "advanced",
    "include_all_content": false,
    "include_filter": "tags:mytag",
    "title": "80s Music Videos",
    "description": "Amateur Tokyo drift!",
    "destination_url": "http://mywebsite.com",
    "keywords": "80s, rock",
    "author": "Rick Astley",
    "category": "Music",
    "album_art_url": "http://my_album_art.jpg",
    "explicit": "no",
    "owner_name": "http://my_album_art.jpg",
    "owner_email": "rick@astley.com",
    "language": "en-us",
    "fetch_sources": true,
    "fetch_digital_master": false,
    "fetch_dynamic_renditions": true,
    "sort": "-created_at"
  }

In der Antwort werden einige schreibgeschützte Felder hinzugefügt:

  {
    "id": "7f594cd3-4853-4174-aff3-203c3e99e9c2",
    "name": "80s music videos syndication",
    "type": "advanced",
    "include_all_content": false,
    "include_filter": "tags:mytag",
    "title": "80s Music Videos",
    "description": "Amateur Tokyo drift!",
    "syndication_url": "https://social.feeds.brightcove.com/v1/accounts/9999999999999/mrss/accounts/{account_id}/mrss/syndications/7f594cd3-4853-4174-aff3-203c3e99e9c2/feed",
    "destination_url": "http://mywebsite.com",
    "keywords": "80s, rock",
    "author": "Rick Astley",
    "category": "Music",
    "album_art_url": "http://my_album_art.jpg",
    "explicit": "no",
    "owner_name": "http://my_album_art.jpg",
    "owner_email": "rick@astley.com",
    "language": "en-us",
    "fetch_sources": true,
    "fetch_digital_master": false,
    "fetch_dynamic_renditions": true,
    "sort": "-created_at"
    }
Syndication-Ressource
Feld Typ Schreibgeschützt Beschreibung
id Schnur Ja Wird generiert, wenn die Syndizierung erstellt wird
name Schnur Nein Ein interner Name für diese Syndizierung - erforderlich für POST-Anfragen
include_all_content Boolean Nein Wenn dies der Fall ist, sind alle Katalogvideos in dieser Syndizierung enthalten
include_filter Schnur Nein Muss angegeben werden, wenn include_all_content false ist. Wert ist a CMS API Suchzeichenfolge mit der CMS API Videosuchsyntax v2. Es gelten alle Syntaxregeln - der einzige Unterschied besteht darin, dass die Suchzeichenfolge als eingegeben wird include_filter Wert eher als ein ?query= param.
type Schnur Nein Die Art des Feeds, der generiert wird. Mit dem universellen Typ können benutzerdefinierte Feeds von einer hochgeladenen Feed-Vorlage generiert werden. Gültige Werte: advanced, google, iphone, ipad, mp4, itunes, roku, source, universal. Erforderlich für POST-Anfragen
title Schnur Nein Der Titel dieses Feeds. Dies ist im <channel> -Tag für die entsprechenden Feed-Typen enthalten
description Schnur Nein Die Beschreibung dieses Feeds. Dies ist im <channel> -Tag für die entsprechenden Feed-Typen enthalten
syndication_url Schnur Ja Die URL des MRSS-Feeds dieser Syndikation
destination_url Schnur Nein Die URL, die im <channel> -Tag für die entsprechenden Feed-Typen enthalten sein soll
keywords Schnur Nein durch Kommas getrennte Liste, die nur für iTunes und (möglicherweise) universelle Feeds verwendet wird
author Schnur Nein Wird nur für iTunes und (möglicherweise) universelle Feeds verwendet
owner_name Schnur Nein Wird nur für iTunes und (möglicherweise) universelle Feeds verwendet
language Schnur Nein Wird nur für iTunes und (möglicherweise) universelle Feeds verwendet - aus zwei Buchstaben bestehender Sprachcode in Kleinbuchstaben, z "en"
owner_email Schnur Nein Wird nur für iTunes und (möglicherweise) universelle Feeds verwendet
category Schnur Nein Wird nur für iTunes und (möglicherweise) universelle Feeds verwendet. Um eine Kategorie mit einer Unterkategorie anzugeben, trennen Sie diese durch einen Doppelpunkt (:) - zum Beispiel: "Business:Business News". "category": "Music"
album_art_url Schnur Nein URL für Bild, nur für iTunes und (möglicherweise) universelle Feeds verwendet
fetch_sources Boolean Nein Bei universellen Vorlagen, ob Videoquellen-Metadaten abgerufen werden sollen - Wenn die Vorlage diese Metadaten nicht benötigt, kann die Leistung durch Angabe verbessert werden false;; könnte leer sein, wenn keine verwendbare Quelle vorhanden ist
fetch_digital_master Boolean Nein Bei universellen Vorlagen kann beim Abrufen digitaler Video-Master-Metadaten angegeben werden. Wenn die Vorlage diese Metadaten nicht benötigt, kann die Leistung durch Angabe verbessert werden false;; könnte leer sein, wenn kein digitaler Master vorhanden ist
fetch_dynamic_renditions Boolean Nein Bei universellen Vorlagen, ob Metadaten für die dynamische Videowiedergabe abgerufen werden sollen - Wenn die Vorlage diese Metadaten nicht benötigt, kann die Leistung durch Angabe verbessert werden false
sort Schnur Nein Ein CMS-Videosortierspezifizierer, der die gewünschte Rückgabereihenfolge für die Feed-Ergebnisse angibt. CMS-unterstützte Werte wie name, reference_id, created_at, published_at, updated_at, schedule.starts_at, schedule.ends_at, state, plays_total, und plays_trailing_week kann angegeben werden. Um in absteigender Reihenfolge zu sortieren, müssen Sie dem Wert ein Minuszeichen (-) voranstellen, d. H. -created_atDer Feed wird nach dem neuesten sortiert updated_at Datum standardmäßig.

[VORLÄUFIGE VOLLAUTOMATISCHE TEXTÜBERSETZUNG - muss noch überarbeitet werden. Wir bitten um Ihr Verständnis.] Für eine detailliertere Anleitung gehen Sie bitte auf: CMS API Videosuchsyntax v2 für Details über die include_filter Eigenschaft .. Es gelten alle Regeln für die Suchsyntax. Der einzige Unterschied besteht darin, dass die Suchzeichenfolge als eingegeben wird include_filter Wert eher als ein ?query= param.

Geschäftstätigkeit

Ausführliche Informationen zu den verfügbaren Vorgängen finden Sie in der API-Referenz:

Die folgenden Aktionen werden unterstützt:

Fehlermeldungen

Wenn API-Anforderungen fehlschlagen, wird eine Fehlermeldung zurückgegeben. Fehlerantworten sehen folgendermaßen aus:

  [
    {
      "error_code" : "Application error code 1",
      "message" : "Application error message 1"
    }, {
      "error_code" : "Application error code 2",
      "message" : "Application error message 2"
    }
  ]

Erstellen Sie eine Syndizierung

Methode: POST

Endpunkt: /accounts/{account_id}/mrss/syndications

Beispielanfragetext:

  {
    "name": "my mp4 feed",
    "type": "mp4"
  }

Beachten Sie, dass die name und type Felder sind Pflichtfelder. Andere sind optional.

Aktualisieren Sie eine Syndizierung

Methode: PATCH

Endpunkt: /accounts/{account_id}/mrss/syndications/{syndication_id}

Beispielanfragetext:

  {
    "name": "my new name"
  }

Beachten Sie, dass der Anforderungshauptteil für PATCH-Anforderungen muss nicht Fügen Sie die Felder hinzu (type, id und syndication_url).

Löschen Sie eine Syndizierung

Methode: DELETE

Endpunkt: /accounts/{account_id}/mrss/syndications/{syndication_id}

Holen Sie sich alle Syndizierungen für ein Konto

Methode: GET

Endpunkt: /accounts/{account_id}/mrss/syndications

Holen Sie sich eine bestimmte Syndication

Methode: GET

Endpunkt: /accounts/{account_id}/mrss/syndications/{syndication_id}

Legen Sie die Vorlage für eine universelle Syndizierung fest

Methode: PUT

Endpunkt: /accounts/{account_id}/mrss/syndications/{syndication_id}/template

Beispielanfragetext:

  <feed header>My Feed Header</feed header>
  

Die obige Vorlage würde einen Feed ähnlich dem folgenden generieren:

  <feed header>My Feed Header</feed header>
    <item>
      <title>Title for Video 1</title>
      <video_info>Description for Video 1</video_info>
    </item>
    <item>
      <title>Title for Video 2</title>
      <video_info>Description for Video 2</video_info>
    </item>

Holen Sie sich die Vorlage für eine universelle Syndizierung

Methode: GET

Endpunkt: /accounts/{account_id}/mrss/syndications/{syndication_id}/template

Holen Sie sich den Feed, der einer Syndizierung zugeordnet ist

Die Feed-URL kann von der Syndication abgerufen werden syndication_url Feld oder manuell erstellt. Notiere dass der Syndication Feed API kann auch verwendet werden, um einen Feed ohne Authentifizierung abzurufen.

Methode: GET

Endpunkt: /accounts/{account_id}/mrss/syndications/{syndication_id}/feed

Universelle Vorlagensprache

Universelle Syndizierungen ermöglichen das Zusammenführen von Katalogdaten mit einer benutzerdefinierten Vorlage, um jede Art von Feed zu generieren. Die unterstützte Vorlagensprache ist Flüssigkeit. Feeds für die Standard-Syndication-Typen werden mit denselben Vorlagentypen generiert Vorlagen als Beispiele um Ihnen bei Bedarf beim Erstellen benutzerdefinierter Vorlagen zu helfen.

In den folgenden Abschnitten werden die Syndication-, Asset-, Source- und Digital Master-Eigenschaften aufgeführt, die Sie verwenden können, sowie eine Erweiterung zu Liquid, die der Einfachheit halber hinzugefügt wurde.

Um alles zu sehen Video Cloud Video-Metadatenfelder mit Beschreibungen, um die zu gehen CMS API Videofeldreferenz.

Eigenschaften der obersten Ebene

Abgeleitet von Syndication-Feldern

  • album_art_url
  • author
  • category
  • description
  • destination_url
  • explicit
  • keywords
  • name
  • owner_name
  • owner_email
  • subtitle
  • syndication_id
  • syndication_url
  • title

Video Cloud Konto-ID

  • account_id

VideoCloud Standard player Seiten-URL-Präfix

Verwenden Sie wie folgt:

  <media:player url="//default_default/index.html?videoId=">
  • player_url

URL der nächsten Seite des Feeds

  • next_page

Sammlung von Video-Assets aus dem Katalog (Details siehe unten)

  • assets

Asset-Eigenschaften

Die Ressourcen in der Assets-Sammlung werden von den Videoressourcen abgeleitet, die von der CMS Get Videos API-Methode zurückgegeben werden, und alle gleichen Eigenschaften werden unterstützt, einschließlich, aber nicht beschränkt auf Folgendes:

  • created_at
  • description
  • duration
  • id
  • images
  • images.thumbnail
  • images.poster
  • long_description
  • name
  • original_filename
  • published_at
  • schedule
  • state
  • tags
  • text_tracks
  • updated_at

Asset-Ressourcen unterstützen auch die folgenden Eigenschaften:

  • sources (Sammlung von Quellen für das Video - Quelleneigenschaften finden Sie im nächsten Abschnitt)
  • digital_master (ist leer, wenn kein digitaler Master vorhanden ist - siehe unten für die Eigenschaften des digitalen Masters)
  • best_mp4_source (Die MP4-Quelle mit der höchsten Qualität - ist möglicherweise leer, wenn keine MP4-Quellen vorhanden sind. Die Eigenschaften entsprechen denen, die in der zurückgegeben werden sources)
  • hls_source (gibt die HLS-Quelle zurück - ist leer, wenn keine vorhanden ist)
  • best_dynamic_rendition_quality (Gibt die Videoqualität der dynamischen Wiedergabe des Videos mit der größten Bildgröße zurück, wenn für das Video Metadaten für die dynamische Wiedergabe abgerufen wurden. Zulässige Werte sind "SD", "HD", "FHD" und "UHD".)

Quelleneigenschaften

Die Ressourcen in der Quellensammlung für ein Asset werden aus den Videoquellenressourcen abgeleitet, die von der CMS Get API Sources API-Methode zurückgegeben werden. Die folgenden Eigenschaften werden unterstützt:

  • app_name
  • asset_id
  • codec
  • container
  • created_at
  • duration
  • encoding_rate
  • height
  • size
  • src
  • stream_name
  • type
  • uploaded_at
  • width

Digitale Master-Eigenschaften

Unser digital_master Die Ressource für ein Asset wird aus der digitalen Masterressource abgeleitet, die von der CMS-API-Methode Get Digital Master Info zurückgegeben wird. Die folgenden Eigenschaften werden unterstützt:

  • duration
  • encoding_rate
  • height
  • size
  • url
  • width

Dynamische Wiedergabeeigenschaften

Unser dynamic_renditions Die Ressource für ein Asset wird aus den dynamischen Wiedergaben abgeleitet, die von der CMS Get Digital Master Info API-Methode zurückgegeben werden. Die folgenden Eigenschaften werden unterstützt:

  • rendition_id
  • frame_height
  • frame_width
  • media_type
  • encoding_rate
  • created_at
  • updated_at
  • size
  • duration
  • audio_configuration
  • language
  • variant

Erweiterungen zu Liquid

toUTC Filter

Wir haben unseren Liquid-Parser erweitert, um einen toUTC-Filter zu unterstützen, der die meisten Standardformate für ISO-8601-Datums- und Uhrzeitzeichenfolgen analysiert und sie in Standard-UTC-Datums- und Uhrzeitzeichenfolgen umwandelt. Dieses Format ist für den Datumsfilter von Liquid akzeptabel, mit dem die Zeitstempel in Datums- / Uhrzeitzeichenfolgen in einem beliebigen Format neu formatiert werden können. Zum Beispiel:

  <pubDate></pubDate>

Dies erzeugt eine Ausgabe wie die folgende, wenn asset.published_at den Wert 2019-08-09T13 hat: 32: 52.031Z ::

  <pubDate>Fri, 09 Aug 2019 09:32:52 +0000</pubDate>

toEpoch Filter

Der von uns verwendete Liquid-Parser unterstützt das Token "% s" in Datumsfiltern zum Konvertieren von Datumsangaben in Zeitstempel der Unix-Epoche nicht. Um dies zu beheben, wird ein benutzerdefinierter toEpoch-Filter bereitgestellt, mit dem gültige Datumsspezifikationen in das Epochenformat konvertiert werden können. Der Filter gibt einen numerischen Datenwert zurück, der Millisekunden seit der Epoche darstellt, die für die Eingabe in mathematische Filter geeignet ist. Zum Beispiel:

  <toEpochMillis>now</toEpochMillis>
  <toEpochSeconds>0</toEpochSeconds>
  <thirtyDaysAgo>-2592000000</thirtyDaysAgo>

erzeugt eine Ausgabe wie die folgende:

  <toEpochMillis>1580917253024</toEpochMillis>
  <toEpochSeconds>1580917253</toEpochSeconds>
  <thirtyDaysAgo>2020-01-06T15:40:53.055Z</thirtyDaysAgo>

fromEpoch Filter

Der fromEpoch-Filter konvertiert Zahlen, die Millisekunden seit der Epoche darstellen, in UTC-Datumszeichenfolgen. Der Filter akzeptiert auch eine Zeichenfolge, die die Epochenwertziffern enthält, als Eingabe. Die Ausgabe kann bei Bedarf zur Neuformatierung an den Datumsfilter übergeben werden.

Beispielsweise:

  
  <fromEpochMillis>now</fromEpochMillis>
  <thirtyDaysAgoAltFormat>52067-04-10</thirtyDaysAgo>
  

erzeugt eine Ausgabe wie die folgende:

  
  <fromEpochMillis>2020-02-05T16:09:37.809Z</fromEpochMillis>
  <thirtyDaysAgoAltFormat>2020-02-05</thirtyDaysAgo>

Seite zuletzt aktualisiert am 22. Juni 2020