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

    Présentation : API CMS

    Dans cette rubrique, vous obtiendrez une vue d'ensemble de l'API CMS. Le CMS API fournit un accès en lecture non mis en cache aux données. Ceci est important pour les workflows de publication sensibles au temps, car vous apportez des modifications aux vidéos et aux listes de lecture à l'aide du CMS API et lisez rapidement les données pour vérifier que c'est correct.

    Référence de l'API

    Voir également la référence de l'API.

    Informations générales

    URL de base

    L'URL de base de l' CMS API est :

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

    Chemin du compte

    Dans tous les cas, des demandes seront faites pour un Video Cloud compte spécifique. Ainsi, vous ajouterez toujours le terme accounts suivi de votre identifiant de compte à l'URL de base :

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

    Authentification

    L'authentification des demandes nécessite Authorization header :

            Authorization: Bearer {access_token}

    Le access_token est un jeton d'accès OAuth2 temporaire qui doit être obtenu à partir du Brightcove OAuth service. Pour plus de détails, consultez la présentation OAuth de Brightcove.

    La façon la plus simple de créer des informations d'identification client consiste à utiliser les pages d'administration de Brightcove Studio. Pour obtenir des instructions détaillées, voir Gestion des informations d'authentification API

    Opérations

    Lorsque vous demandez des informations d'identification client, vous devez spécifier le type d'accès au compte ou les opérations que vous souhaitez. Voici une liste des opérations actuellement prises en charge pour CMS API :

    • Données vidéo :

      video-cloud/video/read
      video-cloud/video/create
      video-cloud/video/update
      video-cloud/video/delete
      ou
      video-cloud/video/all
      video-cloud/video/assets/delete (Uniquement nécessaire si vous souhaitez supprimer des masters numériques - notez que vous ne peux pas obtenez cette autorisation lors de la création d'informations d'identification dans Studio. Cela doit être effectué via l'API OAuth ou l' exemple d'application créée par Brightcove Learning Services.)

    • Données de la playlist :

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

    • Notifications :

    Limitation du taux

    Cela CMS API fournit un accès en lecture non mis en cache aux données. Ceci est important pour les workflows de publication sensibles au temps, car vous apportez des modifications aux vidéos et aux listes de lecture à l'aide du CMS API et lisez rapidement les données pour vérifier que c'est correct.

    Le n' CMS API est pas approprié pour une utilisation d'exécution à grande échelle (par exemple, l'accès à des vidéos sur une page Web publique à trafic élevé). Pour les applications à trafic élevé, vous devez utiliser une interface mise en cache telle que : le Playback API , Galerie, Players ou les SDK natifs.

    Pour assurer les performances du Video Cloud système, pas plus de 20 appels simultanés vers le CMS API sont par compte. La fréquence d'accès devrait être inférieure à 10 demandes par seconde.

    Si plusieurs applications s'intègrent au compte CMS API pour un compte, ces applications doivent avoir une logique de rétro-off et de nouvelle tentative pour gérer les instances où des limites de concurrence ou des limites de taux sont atteintes.

    Si le taux ou la limite de concurrence est dépassée, une 429 - TOO_MANY_REQUESTS erreur sera renvoyée.

    Conflits d'ID de référence

    Pour garantir l'unicité des identifiants de référence, l'identifiant CMS API verrouille l'id pendant 3 minutes au maximum après toute opération sur la vidéo à laquelle il est affecté. Cela peut entraîner le renvoi d'erreurs 409 lorsque vous tentez de réessayer une demande qui échoue trop rapidement, ou lorsque vous essayez de réutiliser un identifiant de référence trop tôt après la suppression de la vidéo à laquelle elle a été précédemment affectée. Pour plus de détails, reportez-vous à la référence du message d'erreur .

    Limite des ressources vidéo

    Il y a une limite de 1 000 ressources par vidéo. Les ressources incluent les formats associés, les pistes audio, les pistes de texte et les images, ainsi que le maître numérique. Les formats associés et les images totalisent rarement plus de 10 à 15 ressources. Par conséquent, même si vous possédez des pistes audio et des pistes de texte distinctes pour 150 langues différentes, vous disposez toujours de moins de 350 ressources.

    Remarques sur l'utilisation

    Méthodes

    Actuellement, l'API prend en charge les types de requêtes suivants :

    • GET
    • POST
    • PATCH
    • PUT
    • DELETE

    Paramètres

    Notez que tous les paramètres sont facultatifs. Sauf indication contraire, ils s'appliquent aux GET demandes de vidéos et de playlists.

    Paramètres de requête GET
    Paramètre Description
    q Chaîne de requête pour les recherches - voir Syntaxe de recherche pour plus d'informations
    limit Nombre de vidéos à renvoyer - doit être un entier compris entre 1 et 100. Par défaut : 20
    offset Nombre de vidéos à ignorer (pour les résultats de pagination). Doit être un entier positif. Par défaut : 0
    sort Chaîne qui spécifie le champ à trier. - Commencez par trier décroissant. Si une valeur pour q est fournie, alors le tri par défaut est par « score » (pertinence des résultats de recherche par rapport à la requête d'origine). Si aucune valeur pour n' q est fournie, le tri par défaut est updated_at décroissant. Les champs suivants sont valides pour le tri: name , reference_id , created_at , published_at , updated_at , schedule_starts_at , schedule_ends_at , state , plays_total , et plays_trailing_week

    Brightcove's CMS API fournit un moyen programmatique de rechercher des vidéos dans votre Video Cloud bibliothèque.

    Pour effectuer des recherches de base et complexes sur vos données vidéo, vous utiliserez le q paramètre :

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

    Pour plus d'informations sur la recherche de vidéos, consultez le document Rechercher des vidéos .

    Pour les listes de lecture, les valeurs prises en charge pour la chaîne de recherche sont plus limitées. Vous pouvez actuellement rechercher par type , name , description , et reference_id. Voici quelques exemples de recherches valides :

    • q=type:EXPLICIT
    • q=type:ACTIVATED_OLDEST_TO_NEWEST
    • q=type:ALPHABETICAL
    • q=bears+otters ( le nom, la description ou l'ID de référence doivent contenir des « ours » ou des « loutres »)
    • q=%2Bname:bears+type:EXPLICIT ( le nom doit contenir « ours »)

    Voir Search Splaylists pour plus de détails.

    Résultats de pagination

    Utilisez le limit paramètre pour spécifier le nombre d'éléments que vous souhaitez renvoyer sur une demande - jusqu'à 100. Vous pouvez ensuite utiliser le offset paramètre pour parcourir les jeux de résultats qui sont plus grands que le limit. offset Le nombre d'éléments à ignorer.

    Par exemple, la recherche suivante renvoie 51-75 vidéos du jeu total de résultats, en supposant que le jeu de résultats total comporte au moins 75 vidéos :

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

    le limit et offset Les paramètres peuvent être utilisés pour les vidéos et les listes de lecture.

    Meilleures pratiques de pagination

    Étant donné qu'il peut y avoir des opérations de modification simultanées en cours avec l'API CMS, il est recommandé de suivre ces étapes lors de la pagination de votre jeu de résultats :

    1. Faites une count demande pour obtenir le nombre total de vidéos dans votre jeu de résultats.
            /accounts/578380111111/counts/videos?q=tags:nature
    2. Utilisez le limit et offset paramètres pour renvoyer des groupes de données à partir de votre jeu de résultats.
            /accounts/578380111111/videos?q=tags:nature&limit=20&offset=50
    3. Notez que certaines pages peuvent contenir moins de 20 vidéos. Vous saurez que vous avez atteint la fin du jeu de résultats lorsque vous avez demandé autant de vidéos que dans la première count demande.

    Pour résumer, continuez à récupérer les pages jusqu'à ce que vous obteniez un nombre de vidéos égal à la count demande d'origine, car ce nombre devrait errer du côté de la surestimation. Demandez :

          count / page-size + 1 page

    Tri des résultats vidéo

    Utilisez le paramètre sort=field_name pour spécifier comment les résultats doivent être triés - vous pouvez trier les vidéos et les playlists. Vous pouvez trier les champs vidéo suivants : [1-1]

    • name
    • reference_id
    • created_at
    • published_at
    • updated_at
    • schedule_starts_at ( note : il s'agit du champ de tri - le champ de recherche est schedule.starts_at )
    • schedule_ends_at ( note : il s'agit du champ de tri - le champ de recherche est schedule.ends_at )
    • state
    • plays_total [ 1-2]
    • plays_trailing_week [ 1-2]

    Notes

    • [ 1-1] Si vous ne fournissez pas de valeur de tri pour un appel de recherche vidéo, les résultats seront triés par pertinence. Si vous ne fournissez pas de valeur de tri pour un appel GET vidéo, les résultats seront triés par updated_at ordre décroissant.
    • [ 1-2] Vous pouvez trier sur plays_total ou plays_trailing_week , mais ces champs ne sont pas inclus dans les résultats

    Tri des résultats de la playlist

    Vous pouvez trier les playlists dans les champs suivants :

    • name
    • updated_at ( par défaut)

    Toutes les vidéos et les grands ensembles de données

    Si vous récupérez toutes les vidéos de votre compte, ou un grand nombre de vidéos, vous devez être conscient de certaines choses :

    1. Vous pouvez être tenté d'utiliser le plus grand permis limit (100), mais il est préférable de récupérer des vidéos par lots de 25 ou moins afin de minimiser la possibilité que les demandes d'API soient épuisées
    2. Au fur et à mesure que vous parcourez des ensembles de données volumineux, il est possible que les données vidéo soient mises à jour pendant l'opération, ce qui pourrait entraîner le déplacement des éléments dans les réponses :
      • Vous pouvez voir un élément répété sur les pages successives
      • Un élément peut être manqué, car il a été déplacé vers un jeu de réponses précédent

      Pour tenir compte de la première possibilité, votre application doit dédupliquer la liste complète des éléments une fois que vous avez terminé la récupération des vidéos. Pour gérer la deuxième possibilité, vous devez comparer le nombre total d'éléments récupérés (après dédupage) au nombre que vous attendiez, puis réexécuter les requêtes, trier les résultats par last_modified_date (décroissant) - vous ne devriez pas avoir besoin de récupérer plus d'un lot pour récupérer les éléments manqués.

    3. Vous pouvez réduire la probabilité des scénarios de l'élément précédent en triant les résultats renvoyés de manière appropriée. Le tri par défaut par pertinence pour les recherches est basé sur un algorithme complexe qui regarde des combinaisons de mots-clés, de balises et de valeurs de champ personnalisées. Si vous recherchez des vidéos basées sur plusieurs mots-clés, balises et/ou champs personnalisés, trier par pertinence correspond exactement à ce que vous voulez. Cependant, si vous essayez simplement de récupérer la totalité ou une grande partie de vos vidéos, la définition explicite du sort paramètre vous donnera plus de contrôle sur l'ordre des éléments retournés.

    Opérations vidéo

    Les opérations vidéo comprennent :

    • Obtenir un nombre de vidéos ou de résultats de recherche
    • Récupérer toutes les vidéos
    • Obtenir une ou plusieurs vidéos par ID ou ID de référence
    • Créer, récupérer, mettre à jour et supprimer des vidéos
    • Rechercher des vidéos
    • Obtenir des sources vidéo, des images et des informations de base numériques
    • Obtenir les listes de lecture auxquelles appartient une vidéo
    • Supprimer la vidéo de toutes les listes de lecture

    Les détails des opérations vidéo sont disponibles dans la référence API.

    Opérations de playlist

    Les opérations de liste de lecture comprennent :

    • Recevez un nombre de playlists
    • Obtenir toutes les listes de lecture
    • Créer, mettre à jour et supprimer des sélections
    • Recevez un nombre de vidéos dans une playlist
    • Obtenir les vidéos dans une playlist

    Vous trouverez des détails sur les opérations de sélection dans la référence de l'API.

    Ressources

    Les opérations de ressources vous permettent de gérer les ressources, y compris les formats associés, les manifestes, les images et les pistes de texte. Pour ingérer des actifs, vous devez utiliser le Dynamic Ingest API. le POST et PATCH opérations pour le CMS API /assets peut être utilisé pour ajouter et mettre à jour actifs distants. CMS API Les opérations GET fonctionneront à la fois pour les actifs ingérés et distants.

    • Ajouter, mettre à jour ou supprimer des formats associés
    • Ajouter, mettre à jour ou supprimer des métadonnées pour le maître numérique
    • Ajouter, mettre à jour ou supprimer des manifestes pour les types de vidéo segmentés tels que HLS
    • Ajouter, mettre à jour ou supprimer des images d'affiche et de miniatures
    • Ajouter, mettre à jour ou supprimer des pistes de texte WebVTT ou des légendes DFXP

    Vous trouverez des détails sur les opérations de l'actif dans la référence API.

    Opérations sur le terrain personnalisées

    Il existe actuellement une opération sur le terrain personnalisée :

    • Obtenir tous les champs personnalisés pour un compte

    Vous trouverez des détails sur les opérations de terrain personnalisées dans la référence API.

    Opérations de dossier

    Les opérations de dossier vous permettent de :

    • Obtenir une liste de dossiers
    • Créer, mettre à jour et supprimer des dossiers
    • Obtenir une liste de vidéos dans un dossier
    • Ajouter une vidéo à un dossier
    • Supprimer une vidéo d'un dossier

    Les détails des opérations de dossier se trouvent dans la référence de l'API.

    Notifications

    Vous pouvez recevoir des notifications lorsque des video_change événements se produisent dans votre vidéothèque. Les notifications seront envoyées à l'URL que vous spécifiez, qui devrait pointer vers une application capable de traiter les HTTP POST demandes.

    Échec de notification

    Le système de notification traite tout retour 4xx ou 5xx du serveur client comme une défaillance récupérable. Les rappels défaillants seront réessayés jusqu'à 20 fois, avec un délai exponentiellement croissant entre les rappels ultérieurs. Les premières tentatives se produiront dans les minutes suivant la tentative de rappel initiale. Si le rappel continue à échouer et que nous arrivons jusqu'à la 20e nouvelle tentative, le délai de nouvelle tentative sera de quelques jours.

    Pare-feu

    Dans le cas où votre organisation a une politique stricte concernant les sources de trafic entrant via votre pare-feu, nous autorisons toutes les adresses IP de la région AWS East. Ceci est sujet à changement, donc toutes les adresses IP AWS doivent être mises en liste blanche. Voir https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html pour plus d'informations.

    Opérations de notification

    Les opérations actuellement disponibles pour les notifications sont les suivantes :

    • Créer des abonnements
    • Obtenir un ou tous les abonnements
    • Supprimer un abonnement

    Vous trouverez des détails sur les opérations de notification dans la référence de l'API.