assistance Contacter le support | Étatétat du système du système
Contenu de la page

    Présentation : API de syndication sociale

    L'API Social Syndication est une API accessible au public qui permet de créer, de gérer et d'utiliser des syndications pour générer des flux dynamiques (tels que les flux MRSS) à partir d'un catalogue vidéo VideoCloud.

    Dans ce document

    Documents connexes

    Introduction

    L'API Brightcove Syndication Configuration est une API accessible au public qui permet de créer, de gérer et d'utiliser des syndications pour générer des flux dynamiques (tels que les flux MRSS) à partir du catalogue vidéo d'un compte Video Cloud.

    Il existe également une API de flux de syndication associée qui peut être utilisée pour récupérer un flux associé à une syndication.

    Disponibilité

    Les API de syndication sont disponibles pour tous les clients Video Cloud qui ont accès aux API de la plate-forme.

    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 Autorisation :

    Authorization: Bearer {your_access_token}

    Consultez la section suivante sur l'authentification pour plus d'informations sur les jetons d'accès.

    Pour toute requête qui envoie un corps de requête, 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 du service OAuth Brightcove dans l' Authorization en-tête de la requête. Les différentes méthodes d'API nécessitent également l'une des opérations suivantes (en fonction de la méthode utilisée) à spécifier 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 la section Authentification API du module d'administration Studio:

    Autorisations de syndication sociale
    Autorisations de syndication sociale

    Si vous préférez, vous pouvez également créer des informations d'identification via l'API OAuth :

    Ressource de syndication

    La ressource de syndication est un objet qui définit la façon dont la syndication sera créée. Voici un exemple de corps de requête 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 va ajouter 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"
        }
    Ressource de syndication
    Champ Type Lecture seule 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 Si cette option est définie, remplace l'en-tête Content-Type renvoyé par le serveur de flux pour ce flux de syndication. Sinon, le flux utilise par défaut une valeur d'en-tête spécifique au type de syndication
    include_all_content Booléen Non Si la valeur est true, toutes les vidéos du catalogue sont incluses dans cette syndication
    include_filter Chaîne Non Doit être spécifié si include_all_content a la valeur false. Valeur est une chaîne CMS API de recherche utilisant la syntaxe de recherche vidéo de l'API CMS 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 que comme ?query= paramètre.
    type Chaîne Non 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 demandes POST
    title Chaîne Non Le titre de ce flux. Ceci est inclus dans la > balise de < canal pour les types de flux applicables
    description Chaîne Non La description de ce flux. Ceci est inclus dans la > balise de < canal pour les types de flux applicables
    syndication_url Chaîne Oui URL du flux MRSS de cette syndication
    destination_url Chaîne Non URL à inclure dans la > balise de < canal pour les types de flux applicables
    keywords Chaîne Non liste délimitée par des virgules, utilisée uniquement pour itunes et (potentiellement) les flux universels
    author Chaîne Non uniquement utilisé pour les flux itunes et (potentiellement) universels
    owner_name Chaîne Non uniquement utilisé pour les flux itunes et (potentiellement) universels
    language Chaîne Non uniquement utilisé pour les flux itunes et (potentiellement) universels - code de langue à deux lettres en minuscules, tel que "en"
    owner_email Chaîne Non uniquement utilisé pour les flux itunes et (potentiellement) universels
    category Chaîne Non utilisé uniquement pour les flux itunes et (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, utilisée uniquement pour itunes et (potentiellement) les flux universels
    fetch_sources Booléen Non Pour les modèles universels, s'il faut récupérer les métadonnées de 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 ; peut être vide si aucune source utilisable n'existe
    fetch_digital_master Booléen Non Pour les modèles universels, s'il faut récupérer les métadonnées maîtresses numériques 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 ; peut être vide si aucun maître numérique n'existe
    fetch_dynamic_renditions Booléen Non Pour les modèles universels, si vous souhaitez récupérer les métadonnées vidéo dynamiques associées - 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 Spécificateur de tri vidéo CMS indiquant l'ordre de retour des résultats de flux souhaités. Valeurs prises en charge par le CMS telles que name , reference_id , created_at , published_at , updated_at , schedule.starts_at , schedule.ends_at , state , plays_total , et plays_trailing_week peut être spécifié. Pour trier par ordre décroissant, préfacer la valeur avec un signe moins (-), c'est-à-dire -created_at, spécifié, le flux sera trié par défaut par updated_at date la plus récente.

    Voir la syntaxe de recherche vidéo de l'API CMS v2 pour plus de détails sur la include_filter propriété. 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 que comme ?query= paramètre.

    Opérations

    Reportez-vous à la référence de l'API pour plus de détails sur les opérations disponibles :

    Les actions suivantes sont prises en charge :

    Messages d’erreur

    Si une demande d'API échoue, un message d'erreur sera renvoyé. Les réponses d'erreur ressembleront à ce qui suit :

      [
        {
          "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

    Point de terminaison : /accounts/{account_id}/mrss/syndications

    Corps de demande d'échantillon :

      {
        "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

    Point de terminaison : /accounts/{account_id}/mrss/syndications/{syndication_id}

    Corps de demande d'échantillon :

      {
        "name": "my new name"
      }

    Notez que le corps de la requête pour les requêtes PATCH ne doit pas inclure les champs (type , id et syndication_url).

    Supprimer une syndication

    Méthode : DELETE

    Point de terminaison : /accounts/{account_id}/mrss/syndications/{syndication_id}

    Obtenir toutes les syndications pour un compte

    Méthode : GET

    Point de terminaison : /accounts/{account_id}/mrss/syndications

    Obtenir une syndication spécifique

    Méthode : GET

    Point de terminaison : /accounts/{account_id}/mrss/syndications/{syndication_id}

    Définir le modèle pour une syndication universelle

    Méthode : PUT

    Point de terminaison : /accounts/{account_id}/mrss/syndications/{syndication_id}/template

    Corps de demande d'échantillon :

      <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>

    Obtenir le modèle pour une syndication universelle

    Méthode : GET

    Point de terminaison : /accounts/{account_id}/mrss/syndications/{syndication_id}/template

    Récupère le flux associé à une syndication

    L'URL du flux peut être obtenue à partir du syndication_url champ de la syndication, ou construite manuellement. Notez que l' API de flux de syndication peut également être utilisée pour récupérer un flux sans authentification.

    Méthode : GET

    Point de terminaison : /accounts/{account_id}/mrss/syndications/{syndication_id}/feed

    Langue de modèle universel

    Les syndications universelles permettent de fusionner les données de catalogue avec un modèle personnalisé pour générer n'importe quel type de flux souhaité. Le langage de modèle pris en charge est Liquid. 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 les modèles fournis sous forme d'exemples pour vous aider à créer des modèles personnalisés si nécessaire.

    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 afficher tous les champs de métadonnées vidéo Video Cloud avec des descriptions, accédez à la référence des champs vidéo de l'API CMS.

    Propriétés de niveau supérieur

    Dérivé des champs Syndication

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

    ID de compte Video Cloud

    • account_id

    Préfixe d'URL de la page du lecteur par défaut de VideoCloud

    Utilisez comme ceci :

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

    URL de la page suivante du flux

    • next_page

    Collecte des ressources vidéo extraites du catalogue (voir ci-dessous pour plus de détails)

    • assets

    Propriétés de l'actif

    Les ressources de la collection d'actifs sont dérivées des ressources vidéo renvoyées par la méthode API Get Videos CMS, et toutes les mêmes propriétés sont prises en charge, y compris, mais sans s'y limiter, les suivantes :

    • 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'actifs 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 les articles retournés dans le sources)
    • hls_source ( retourne la source HLS - sera vide si aucune n'existe)
    • best_dynamic_rendition_quality ( renvoie la qualité vidéo du rendu dynamique de la vidéo avec la taille d'image la plus élevée, si des métadonnées de rendu dynamique ont été récupérées pour la vidéo. Les valeurs autorisées sont « SD », « HD », « FHD » et « UHD ».)

    Propriétés de la source

    Les ressources de la collection de sources d'un actif sont dérivées des ressources source vidéo renvoyées par la méthode CMS Get Video Sources API. 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 maîtresses numériques

    La digital_master ressource d'un actif est dérivée de la ressource principale numérique renvoyée par la méthode CMS Get Digital Master Info API. Les propriétés suivantes sont prises en charge :

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

    Propriétés du format associé dynamique

    La dynamic_renditions ressource d'une ressource est dérivée des formats associés dynamiques renvoyés par la méthode CMS Get Digital Master Info API. 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 Liquid pour prendre en charge un filtre TouTC qui analysera la plupart des formats de chaîne datetime ISO-8601 standard et les transformera en chaînes UTC datetime 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 suivante si asset.published_at a une valeur de 2019-08-09T 13:32:52 .031Z።

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

    Filtre ToEpoch

    L'analyseur Liquid 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 les spécifications de date valides au format epoch. Le filtre renvoie une valeur de données numérique représentant des millisecondes depuis l'époque qui convient à l'entrée dans les filtres mathématiques. Par exemple :

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

    produit une sortie comme suit :

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

    Filtre FromEPoch

    Le filtre FromEPoch convertit des nombres représentant des millisecondes depuis l'époque en chaînes de date UTC. Le filtre acceptera également une chaîne contenant les chiffres de la valeur d'époque en entrée. La sortie peut être transmise au filtre de date pour le reformatage si nécessaire.

    Par exemple :

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

    produit une sortie comme suit :

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