Dans ce document
- Introduction
- Spécifications OpenAPI
- Authentification
- URL de base
- Ressource de syndication
- Actions
- Langage de modèle universel
Documents connexes
- Syntaxe de recherche pour la syndication
- Exemples de modèles pour la syndication universelle
- Référence de l'API de configuration de la syndication
- Référence API de flux de syndication
Introduction
L'API de configuration de la syndication Brightcove est une API accessible au public qui permet de créer, gérer et utiliser des syndications pour générer des flux dynamiques (tels que des flux MRSS) à partir d'un Video Cloud catalogue vidéo du compte.
Il existe également un API de flux de syndication qui peut être utilisé pour récupérer un flux associé à une syndication.
Disponibilité
Les API de syndication sont accessibles à tous Video Cloud les clients qui ont accès aux API de la plateforme.
Référence API / URL de base / en-têtes
La Référence de l'API de configuration contient tous les détails sur les opérations, les champs et les paramètres disponibles.
L'URL de base est:
https://social.api.brightcove.com/v1
Toutes les demandes doivent être authentifiées via un en-tête d'autorisation:
Authorization: Bearer {your_access_token}
Voir la section suivante sur l'authentification pour plus d'informations sur les jetons d'accès.
Pour toute demande qui envoie un corps de demande, vous devez également inclure un Content-Type: application/json
en-tête.
Authentification
L'accès à l'API de configuration nécessite la spécification d'un bearer
jeton de la Service Brightcove OAuth dans la demande de Authorization
entête. Les différentes méthodes d'API nécessitent également que l'une des opérations suivantes (selon la méthode utilisée) soit spécifiée pour les informations d'identification en question:
video-cloud/social/mrss/read
video-cloud/social/mrss/write
Ces opérations peuvent être configurées via le Section Authentification API du module d'administration Studio:

Si vous préférez, vous pouvez également créer des informations d'identification via le OAuth API:
Ressource de syndication
La ressource de syndication est un objet qui définit comment la syndication sera créée. Voici un exemple de corps de demande pour créer une ressource de syndication:
{
"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",
"content_type_header": "application/xml"
}
La réponse ajoutera quelques champs en lecture seule:
{
"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",
"content_type_header": "application/xml"
}
Champ | Type | Lecture seulement | Description |
---|---|---|---|
id |
Chaîne | Oui | généré lors de la création de la syndication |
name |
Chaîne | Non | un nom interne pour cette syndication - requis pour les requêtes POST |
content_type_header |
Chaîne | Non | S'il est défini, remplace l'en-tête Content-Type renvoyé par le serveur de flux pour le flux de cette syndication. Sinon, le flux utilise par défaut une valeur d'en-tête spécifique au type de syndication |
include_all_content |
Boolean | Non | Si vrai, toutes les vidéos du catalogue sont incluses dans cette syndication |
include_filter |
Chaîne | Non | Doit être spécifié si include_all_content est false. La valeur est un CMS API chaîne de recherche à l'aide du CMS API syntaxe de recherche vidéo v2. Toutes les règles de syntaxe s'appliquent - la seule différence est que la chaîne de recherche est entrée comme include_filter valeur plutôt qu'un ?query= param.
|
type |
Chaîne | Non | Le type de flux qui sera généré. Le type universel permet de générer des flux personnalisés par un modèle de flux téléchargé. Valeurs valides: advanced , google , iphone , ipad , mp4 , itunes , roku , source , universal . Requis pour les requêtes POST |
title |
Chaîne | Non | Le titre de ce flux. Ceci est inclus à l'intérieur du étiquette pour les types de flux applicables |
description |
Chaîne | Non | La description de ce flux. Ceci est inclus à l'intérieur du étiquette pour les types de flux applicables |
syndication_url |
Chaîne | Oui | L'URL du flux MRSS de cette syndication |
destination_url |
Chaîne | Non | L'URL à inclure dans le étiquette pour les types de flux applicables |
keywords |
Chaîne | Non | Liste délimitée par des virgules, uniquement utilisée pour iTunes et les flux (potentiellement) universels |
author |
Chaîne | Non | utilisé uniquement pour iTunes et les flux (potentiellement) universels |
owner_name |
Chaîne | Non | utilisé uniquement pour iTunes et les flux (potentiellement) universels |
language |
Chaîne | Non | utilisé uniquement pour iTunes et les flux (potentiellement) universels - code de langue à deux lettres en minuscules, tel que "en" |
owner_email |
Chaîne | Non | utilisé uniquement pour iTunes et les flux (potentiellement) universels |
category |
Chaîne | Non | utilisé uniquement pour iTunes et les flux (potentiellement) universels. Pour spécifier une catégorie avec une sous-catégorie, séparez-les par deux points (:) - par exemple: "Business:Business News". "category": "Music" |
album_art_url |
Chaîne | Non | URL pour l'image, uniquement utilisée pour iTunes et (potentiellement) les flux universels |
fetch_sources |
Boolean | Non | Pour les modèles universels, que ce soit pour récupérer les métadonnées de la source vidéo - si le modèle n'a pas besoin de ces métadonnées, les performances peuvent être améliorées en spécifiant false ; pourrait être vide s'il n'existe aucune source utilisable |
fetch_digital_master |
Boolean | Non | Pour les modèles universels, que ce soit pour récupérer des métadonnées vidéo numériques principales - si le modèle n'a pas besoin de ces métadonnées, les performances peuvent être améliorées en spécifiant false ; pourrait être vide si aucun maître numérique n'existe |
fetch_dynamic_renditions |
Boolean | Non | Pour les modèles universels, que ce soit pour récupérer des métadonnées de rendu dynamique vidéo - si le modèle n'a pas besoin de ces métadonnées, les performances peuvent être améliorées en spécifiant false |
sort |
Chaîne | Non | Un spécificateur de tri vidéo CMS indiquant l'ordre de retour des résultats de flux souhaité. Valeurs prises en charge par CMS comme name , reference_id , created_at , published_at , updated_at , schedule.starts_at , schedule.ends_at , state , plays_total plays_trailing_week peut être spécifié. Pour trier par ordre décroissant, faites précéder la valeur d'un signe moins (-), c.-à-d. -created_at , spécifié, le flux sera trié en fonction de la plus récente updated_at date par défaut. |
découvrir CMS API syntaxe de recherche vidéo v2 pour plus de détails sur le include_filter
.. Toutes les règles de syntaxe de recherche s'appliquent - la seule différence est que la chaîne de recherche est entrée comme include_filter
valeur plutôt qu'un ?query=
param.
Opérations
Voir la référence API pour plus de détails sur les opérations disponibles:
Les actions suivantes sont prises en charge:
- Créer une syndication
- Mettre à jour une syndication
- Supprimer une syndication
- Obtenez toutes les syndications pour un compte
- Obtenez une syndication spécifique
- Définir le modèle pour une syndication universelle
- Obtenez le modèle pour une syndication universelle
- Obtenez le flux associé à une syndication
Messages d'erreur
Si une demande d'API échoue, un message d'erreur sera renvoyé. Les réponses d'erreur ressembleront à ceci:
[
{
"error_code" : "Application error code 1",
"message" : "Application error message 1"
}, {
"error_code" : "Application error code 2",
"message" : "Application error message 2"
}
]
Créer une syndication
Méthode: POST
Endpoint: /accounts/{account_id}/mrss/syndications
Exemple de corps de demande:
{
"name": "my mp4 feed",
"type": "mp4"
}
Notez que le name
et type
les champs sont obligatoires. D'autres sont facultatifs.
Mettre à jour une syndication
Méthode: PATCH
Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}
Exemple de corps de demande:
{
"name": "my new name"
}
Notez que le corps de la demande pour les demandes PATCH doit ne sont pas inclure les champs (type
, id
et syndication_url
).
Supprimer une syndication
Méthode: DELETE
Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}
Obtenez toutes les syndications pour un compte
Méthode: GET
Endpoint: /accounts/{account_id}/mrss/syndications
Obtenez une syndication spécifique
Méthode: GET
Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}
Définir le modèle pour une syndication universelle
Méthode: PUT
Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}/template
Exemple de corps de demande:
<feed header>My Feed Header</feed header>
Le modèle ci-dessus générerait un flux similaire à:
<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>
Obtenez le modèle pour une syndication universelle
Méthode: GET
Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}/template
Obtenez le flux associé à une syndication
L'URL du flux peut être obtenue auprès de la syndication syndication_url
terrain, ou construit manuellement. Notez que le API de flux de syndication peut également être utilisé pour récupérer un flux sans authentification.
Méthode: GET
Endpoint: /accounts/{account_id}/mrss/syndications/{syndication_id}/feed
Langage de modèle universel
Les syndications universelles permettent de fusionner les données du catalogue avec un modèle personnalisé pour générer tout type de flux souhaité. La langue de modèle prise en charge est Liquide. Les flux pour les types de syndication par défaut sont générés à l'aide des mêmes types de modèles, vous pouvez voir le modèles fournis comme exemples pour vous aider à créer des modèles personnalisés si vous en avez besoin.
Les sections ci-dessous identifient les propriétés de syndication, d'actif, de source et de maître numérique que vous pouvez utiliser, ainsi qu'une extension de Liquid ajoutée pour plus de commodité.
Pour tout voir Video Cloud champs de métadonnées vidéo avec descriptions, pour accéder au CMS API Référence des champs vidéo.
Propriétés de premier niveau
Dérivé des champs de syndication
album_art_url
author
category
description
destination_url
explicit
keywords
name
owner_name
owner_email
subtitle
syndication_id
syndication_url
title
Video Cloud identifiant de compte
account_id
VideoCloud par défaut player préfixe d'URL de la page
Utilisez comme ceci:
<media:player url="//default_default/index.html?videoId=">
player_url
URL de la page suivante du flux
next_page
Collection de ressources vidéo extraites du catalogue (voir ci-dessous pour plus de détails)
assets
Propriétés des actifs
Les ressources de la collection d'actifs sont dérivées des ressources vidéo renvoyées par la méthode d'API CMS Get Videos, et toutes les mêmes propriétés sont prises en charge, y compris mais sans s'y limiter:
created_at
description
duration
id
images
images.thumbnail
images.poster
long_description
name
original_filename
published_at
schedule
state
tags
text_tracks
updated_at
Les ressources d'actif prennent également en charge les propriétés suivantes:
sources
(collection de sources pour la vidéo - voir la section suivante pour les propriétés des sources)digital_master
(sera vide si aucun maître numérique n'existe - voir ci-dessous pour les propriétés du maître numérique)best_mp4_source
(source MP4 de la plus haute qualité - peut être vide s'il n'y a pas de sources MP4. Les propriétés seront les mêmes que celles renvoyées dans lesources
)hls_source
(retourne la source HLS - sera vide s'il n'en existe pas)best_dynamic_rendition_quality
(renvoie la qualité vidéo du rendu dynamique de la vidéo avec la plus grande taille d'image, si des métadonnées de rendu dynamique ont été extraites pour la vidéo. Les valeurs autorisées sont "SD", "HD", "FHD" et "UHD".)
Propriétés source
Les ressources de la collection de sources d'un actif sont dérivées des ressources de source vidéo renvoyées par la méthode d'API CMS Get Video Sources. Les propriétés suivantes sont prises en charge:
app_name
asset_id
codec
container
created_at
duration
encoding_rate
height
size
src
stream_name
type
uploaded_at
width
Propriétés du maître numérique
La digital_master
La ressource d'un actif est dérivée de la ressource maître numérique renvoyée par la méthode API Get Get Master Master de CMS. Les propriétés suivantes sont prises en charge:
duration
encoding_rate
height
size
url
width
Propriétés de rendu dynamique
La dynamic_renditions
La ressource d'un actif est dérivée des rendus dynamiques renvoyés par la méthode de l'API CMS Get Digital Master Info. Les propriétés suivantes sont prises en charge:
rendition_id
frame_height
frame_width
media_type
encoding_rate
created_at
updated_at
size
duration
audio_configuration
language
variant
Extensions à Liquid
filtre toUTC
Nous avons étendu notre analyseur liquide pour prendre en charge un filtre toUTC qui analysera la plupart des formats de chaîne de date / heure ISO-8601 et les transformera en chaînes de date / heure UTC standard. Ce format est acceptable pour le filtre de date de Liquid, qui peut ensuite être utilisé pour reformater les horodatages en chaînes datetime dans n'importe quel format souhaité. Par exemple:
<pubDate></pubDate>
Cela produit une sortie comme la suivante si asset.published_at a une valeur de 2019-08-09T13: 32: 52.031Z ::
<pubDate>Fri, 09 Aug 2019 09:32:52 +0000</pubDate>
filtre toEpoch
L'analyseur liquide que nous utilisons ne prend pas en charge le jeton "% s" dans les filtres de date pour convertir les dates en horodatages d'époque Unix. Pour résoudre ce problème, un filtre personnalisé toEpoch est fourni qui peut être utilisé pour convertir des spécifications de date valides au format d'époque. Le filtre renvoie une valeur de données numérique représentant les millisecondes depuis l'époque qui convient pour l'entrée dans les filtres mathématiques. Par exemple:
<toEpochMillis>now</toEpochMillis>
<toEpochSeconds>0</toEpochSeconds>
<thirtyDaysAgo>-2592000000</thirtyDaysAgo>
produit une sortie comme celle-ci:
<toEpochMillis>1580917253024</toEpochMillis>
<toEpochSeconds>1580917253</toEpochSeconds>
<thirtyDaysAgo>2020-01-06T15:40:53.055Z</thirtyDaysAgo>
Filtre d'Epoch
Le filtre fromEpoch convertit les nombres représentant les millisecondes depuis l'époque en chaînes de date UTC. Le filtre accepte également une chaîne contenant les chiffres de la valeur de l'époque comme entrée. La sortie peut être transmise au filtre de date pour un reformatage si nécessaire.
Exemple :
<fromEpochMillis>now</fromEpochMillis>
<thirtyDaysAgoAltFormat>52067-04-10</thirtyDaysAgo>
produit une sortie comme celle-ci:
<fromEpochMillis>2020-02-05T16:09:37.809Z</fromEpochMillis>
<thirtyDaysAgoAltFormat>2020-02-05</thirtyDaysAgo>