Aperçu: 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 API

Voir aussi le Référence 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. Par conséquent, vous allez toujours ajouter 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 le Présentation de Brightcove OAuth.

Le moyen le plus simple de créer des informations d'identification client consiste à utiliser les pages d'administration de Brightcove Studio. Pour des instructions détaillées, voir Gestion des informations d'authentification API

Opérations

Lorsque vous demandez des informations d'identification du client, vous devez spécifier le type d'accès au compte ou d'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 fait via l'API OAuth ou le Exemple d'application créée par Brightcove Learning Services.)
Données de la liste de lecture :
video-cloud/playlist/read
video-cloud/playlist/create
video-cloud/playlist/update
video-cloud/playlist/delete
ou
video-cloud/playlist/all
Notifications :
- video-cloud/notifications/all(pour Notifications)

Limitation de débit

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 doit être inférieure à 10 requêtes 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 la limite de débit ou de simultanéité est dépassée, un 429 - TOO_MANY_REQUESTS l'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 retour d'erreurs 409 lorsque vous essayez 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 avoir supprimé la vidéo à laquelle il était précédemment attribué. Voir le Référence des messages d'erreur pour plus de détails.

Limite d'éléments vidéo

Il y a une limite de 1 000 éléments par vidéo. Les ressources comprennent les rendus, les pistes audio, les pistes de texte et les images, ainsi que le master numérique. Les rendus et les images totalisent rarement plus de 10 à 15 éléments, donc même si vous aviez des pistes audio et des pistes de texte séparées pour 150 langues différentes, vous auriez toujours moins de 350 éléments.

Remarques sur l'utilisation

Le CMS API est destiné aux intégrations et aux workflows de publication. Vous ne pouvez pas effectuer d'appels côté client à cette API à partir d'une page Web publique, car cela impliquerait d'exposer vos informations d'identification client pour l'API (pour cette raison, l'API n'est pas compatible CORS). Vous pouvez effectuer des appels à partir d'une application côté client (web), à condition que vous routiez les appels d'API via un proxy côté serveur. Brightcove Learning Services fournit plusieurs exemples d'applications qui utilisent cette approche, ainsi qu'un guide pour créer ce type d'application.

Si vous allez récupérer toutes vos vidéos ou de grands ensembles de vidéos, assurez-vous de voir le note sur les grands ensembles de données.

Évitez les URL codées en dur

Les URL des vignettes, affiches, fichiers vidéo et autres médias ne doivent jamais être codées en dur dans vos pages ou applications. Le CMS API renvoie toujours les URL actuelles pour les fichiers multimédias, mais les URL elles-mêmes sont sujettes à changement. Vous devez utiliser les CMS API (ou Playback API ) requêtes pour récupérer ces URL chaque fois que la page se charge, ou les mettre en cache pendant au plus six heures.

Mettre en cache les URL des vidéos et des images

Vous pouvez mettre en cache les URL des vidéos et des images pour améliorer les performances des pages, mais le cache doit être actualisé régulièrement. Si vous mettez en cache les URL que vous récupérez pour améliorer les performances de vos pages, veillez à actualiser le cache en répétant les appels d'API au moins une fois toutes les six heures.

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 optionnel. Sauf indication contraire, elles 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 nombre 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`	Une chaîne qui spécifie le champ à trier. Commencer avec `-` pour trier par ordre décroissant. Si une valeur pour `q` est fourni, le tri par défaut est par « score » (pertinence des résultats de la recherche par rapport à la requête d'origine). Si aucune valeur pour `q` est fourni, le tri par défaut est par `updated_at` descendant. 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`

Rechercher des vidéos

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

Pour effectuer des recherches basiques 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, reportez-vous à la Rechercher des vidéos document.

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 doit contenir soit "ours" soit "loutres")
q=%2Bname:bears+type:EXPLICIT(le nom doit contenir "ours")

Voir Rechercher des listes de lecture pour plus de détails.

Notez le terme de recherche playable:true/false que vous pouvez utiliser pour ne renvoyer que des vidéos jouables (ou non) :

        https://cms.api.brightcove.com/v1/accounts/:account_id/videos?q=%2Bplayable:true

Cette requête nécessite que les vidéos renvoyées soient lisibles (non désactivées, non programmées et ne manquent pas de rendus lisibles).

Si vous recherchez des vidéos qui ne pas jouable, utiliser q=%2Bplayable:false.

Résultats de la pagination

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

Par exemple, la recherche suivante renvoie les vidéos 51-75 de l'ensemble de résultats total, en supposant que l'ensemble de résultats total comporte au moins 75 vidéos :

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

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

Noter: limit et offset faire ne pas fonctionner lorsque vous demandez les vidéos appartenant à une liste de lecture - cette demande renverra toujours toutes les vidéos de la liste 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 ensemble de résultats :

Faire un count demande pour obtenir le nombre total de vidéos dans votre ensemble de résultats.
```
      /accounts/578380111111/counts/videos?q=tags:nature
```
Utilisez le limit et offset paramètres pour renvoyer des groupes de données de votre jeu de résultats.
```
      /accounts/578380111111/videos?q=tags:nature&limit=20&offset=50
```
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 aurez demandé autant de vidéos que dans le premier count demander.

Pour résumer, continuez à récupérer des pages jusqu'à ce que vous obteniez un nombre de vidéos égal à l'original count demande, car ce nombre devrait pécher par excès de surestimation. Demander:

      count / page-size + 1 page

Tri des résultats vidéo

Utiliser le paramètre sort=field_name pour spécifier comment les résultats doivent être triés - vous pouvez trier à la fois les vidéos et les listes de lecture. Vous pouvez trier les champs vidéo suivants : ^[1-1]

Préfixe le nom du champ avec un signe moins ( sort= -field_name) pour l'ordre décroissant.

name
reference_id
created_at
published_at
updated_at
schedule_starts_at(attention : c'est le sorte champ - le le champ de recherche est schedule.starts_at )
schedule_ends_at(attention : c'est le sorte champ - le le champ de recherche est schedule.ends_at )
state
plays_total ^{[ 1-2]}
plays_trailing_week ^{[ 1-2]}

Remarques

^{[ 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 GET appel vidéo, les résultats seront triés par updated_at descendant.
^{[ 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 liste de lecture

Vous pouvez trier les playlists sur les champs suivants :

name
updated_at(défaut)

Préfixe le nom du champ avec un signe moins ( sort= -field_name) pour l'ordre décroissant.

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 :

Vous pourriez être tenté d'utiliser le plus grand permis limit (100), mais il est préférable de récupérer les vidéos par lots de 25 ou moins pour minimiser le risque d'expiration des requêtes API
Lorsque vous parcourez de grands ensembles de données, il est possible que les données vidéo soient mises à jour pendant l'opération, ce qui peut entraîner un décalage des éléments dans les réponses :
- Vous pouvez voir un élément répété sur des pages successives
- Un élément peut être manqué, car il est passé à un ensemble 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é de récupérer les 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éduplication) au nombre que vous attendiez, puis réexécuter les demandes, en triant les résultats par last_modified_date (décroissant) - vous ne devriez pas avoir besoin de récupérer plus d'un lot pour ramasser les articles manqués.
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 recherche des combinaisons de mots-clés, de balises et de valeurs de champs personnalisés. Si vous recherchez des vidéos basées sur plusieurs mots-clés, balises et/ou champs personnalisés, trier par pertinence est exactement ce que vous voulez. Cependant, si vous essayez simplement de récupérer la totalité ou une grande partie de vos vidéos, définissez le paramètre sort Le paramètre explicitement vous donnera plus de contrôle sur l'ordre des éléments retournés.

Opérations vidéo

Les opérations vidéo incluent :

Obtenez un nombre de vidéos ou de résultats de recherche
Obtenez toutes les vidéos
Obtenez une ou plusieurs vidéos par identifiant ou identifiant de référence
Créer, récupérer, mettre à jour et supprimer des vidéos
Rechercher des vidéos
Obtenez des sources vidéo, des images et les informations du master numérique
Obtenir les playlists auxquelles appartient une vidéo
Supprimer la vidéo de toutes les playlists

Les détails des opérations vidéo peuvent être trouvés dans le Référence API.

Opérations de liste de lecture

Les opérations de liste de lecture incluent :

Obtenez un nombre de listes de lecture
Obtenez toutes les listes de lecture
Créer, mettre à jour et supprimer des listes de lecture
Obtenez le nombre de vidéos dans une liste de lecture
Obtenez les vidéos dans une liste de lecture

Les détails des opérations de la liste de lecture peuvent être trouvés dans le Référence API.

Actifs

Les opérations sur les actifs vous permettent de gérer les actifs, y compris les rendus, 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 rendus
Ajouter, mettre à jour ou supprimer une métadonnée pour le master 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 affiches et des vignettes
Ajouter, mettre à jour ou supprimer des pistes de texte WebVTT ou des légendes DFXP

Les détails des opérations sur les actifs peuvent être trouvés dans le Référence API.

Opérations sur le terrain personnalisées

Il existe actuellement une opération de champ personnalisé :

Obtenez tous les champs personnalisés pour un compte

Les détails des opérations de champ personnalisé peuvent être trouvés dans le Référence API.

Opérations sur les dossiers

Les opérations sur les dossiers 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 peuvent être trouvés dans le Référence API.

Notifications

Vous pouvez recevoir des notifications lorsque des video-change événements se produisent dans votre vidéothèque ou master-video-change des notifications lorsqu'une vidéo partagée met automatiquement à jour ses ressources une fois que la vidéo principale l'a mise à jour. Les notifications seront envoyées à l'URL spécifiée, qui doit pointer vers une application capable de traiter des requêtes HTTP POST.

Échecs de notification

Le système de notification traite tout retour 4xx ou 5xx du serveur client comme un échec réitérable. Les rappels en échec seront réessayés jusqu'à 20 fois, avec un délai exponentiellement croissant entre les rappels suivants. Les premières tentatives auront lieu quelques minutes après la première tentative de rappel. Si le rappel continue d'échouer et que nous arrivons à la 20e tentative, le délai de nouvelle tentative sera de quelques jours.

video-change les événements sont déclenchés par des processus système automatisés ainsi que par des actions de l'utilisateur. Par conséquent, ces événements ne correspondent pas toujours aux modifications que vous avez apportées aux propriétés de la vidéo dans Studio ou via les API.

Pare-feu

Si votre organisation a une politique stricte concernant les sources de trafic entrant via votre pare-feu, nous autorisons toutes les adresses IP AWS de la région Est. Ceci est sujet à changement, donc toutes les adresses IP AWS doivent être ajoutées à la 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 :

Créer des abonnements
Obtenez un ou tous les abonnements
Supprimer un abonnement

Le détail des opérations de notification se trouve dans le Référence API.