Aperçu: CMS API

Dans cette rubrique, vous obtiendrez un aperçu de la CMS API. le CMS API fournit un accès en lecture non mis en cache aux données. Ceci est important pour les flux de travail de publication sensibles au facteur temps, car vous apportez des modifications aux vidéos et aux listes de lecture en utilisant 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 de l'API.

Informations générales

URL de base

L'URL de base pour le 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. 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 pour les demandes nécessite un En-tête d'autorisation :

        Authorization: Bearer {access_token}

La access_token est un jeton d'accès OAuth2 temporaire qui doit être obtenu à partir du Brightcove OAuth un service. Pour plus de détails, voir le Présentation de Brightcove OAuth.

La façon la plus simple de créer des informations d'identification client est via les pages d'administration de Brightcove Studio. Pour des instructions détaillées, voir Gestion des informations d'identification de l'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 souhaitées. Voici une liste des opérations actuellement prises en charge pour le CMS API :

Données vidéo:
video-cloud/video/read
video-cloud/video/create
video-cloud/video/update
video-cloud/video/delete
or
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 obtenir cette autorisation lors de la création d'informations d'identification dans Studio. Cela doit être fait par OAuth API ou le 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
or
video-cloud/playlist/all
Notifications:
- video-cloud/notifications/all (Pour Notifications)

Limitation de débit

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

La CMS API n'est pas approprié pour une utilisation à grande échelle (par exemple, l'accès à des vidéos sur une page Web publique très fréquentée). Pour les applications à fort trafic, vous devez utiliser une interface en cache telle que: Playback API , Gallery, Players, ou les SDK natifs.

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

Si plusieurs applications vont s'intégrer au CMS API pour un compte, ces applications doivent avoir une logique de reprise et de nouvelle tentative pour gérer les instances où les limites de concurrence ou de taux sont atteintes.

Si la limite de débit ou de concurrence est dépassée, un 429 - TOO_MANY_REQUESTS l'erreur sera renvoyée.

Conflits d'identifiant de référence

Pour assurer l'unicité des identifiants de référence, le CMS API verrouille l'id pendant un nombre maximal de minutes 3 après toute opération sur la vidéo à laquelle il est affecté. Cela peut entraîner le renvoi 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 la suppression de la vidéo à laquelle il avait été précédemment attribué. Voir le Référence du message d'erreur pour plus de détails.

Limite d'actifs vidéo

Il y a une limite de ressources 1,000 par vidéo. Les actifs incluent 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 que les actifs 10-15. Même si vous aviez des pistes audio et des pistes de texte distinctes pour les différentes langues de 150, vous auriez toujours moins de ressources 350.

Notes sur l'utilisation

La CMS API est destiné aux intégrations et à la publication de workflows. Vous ne pouvez pas passer d'appels côté client à cette API à partir d'une page Web publique, car cela impliquerait d'exposer les informations d'identification de votre client pour l'API (pour cette raison, l'API n'est pas compatible CORS). Vous pouvez passer des appels à partir d'une application (Web) côté client, à condition de router les appels API via un proxy côté serveur. Services d'apprentissage Brightcove fournit plusieurs exemples d'applications qui utilisent cette approche, et un guide pour la construction de ce genre d'application.

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

Évitez les URL codées en dur

Les URL des vignettes, des affiches, des fichiers vidéo et des autres médias ne doivent jamais être codées en dur dans vos pages ou applications. le CMS API renverra toujours les URL actuelles pour les fichiers multimédias, mais les URL elles-mêmes sont sujettes à modification. Vous devriez utiliser le CMS API ( ou Playback API ) demande à récupérer ces URL chaque fois que la page se charge, ou les cache pour pas plus de six heures.

Mise en cache des URL de vidéos et d'images

Vous pouvez mettre en cache des URL pour des vidéos et des images afin d'améliorer les performances de la page, 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, ils s'appliquent à GET demandes de vidéos et de playlists.

GET Paramètres de requête
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 entre 1 et 100. Par défaut: 20
`offset`	Nombre de vidéos à ignorer (pour les résultats de recherche de personnes). Doit être un entier positif. Par défaut: 0
`sort`	Une chaîne qui spécifie le champ à trier. Commencer avec `-` trier par ordre décroissant Si une valeur pour `q` est fourni, alors 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` `plays_trailing_week`

Rechercher des vidéos

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

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

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

Pour plus de détails sur la recherche de vidéos, voir Vidéos de la recherche document.

Pour les playlists, les valeurs prises en charge pour la chaîne de recherche sont plus limitées. Vous pouvez actuellement effectuer une recherche par type, name, description 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'identifiant de référence doit contenir "ours" ou "loutres")
q=%2Bname:bears+type:EXPLICIT (le nom doit contenir "ours")

découvrir Rechercher des playlists pour plus de détails.

Notez le terme de recherche playable:true/false que vous pouvez utiliser pour renvoyer uniquement les 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 retournées soient jouables (non désactivées, non planifiées et ne comportant pas de rendus jouables).

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

Résultats de pagination

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

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

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

La limit et offset les paramètres peuvent être utilisés pour les vidéos et les playlists.

Note : limit et offset do ne sont pas travailler lorsque vous demandez les vidéos appartenant à une liste de lecture - cette demande retournera toujours toutes les vidéos de la liste de lecture.

Meilleures pratiques de pagination

Comme il peut y avoir des opérations de modification simultanées en cours avec le CMS API, il est recommandé de suivre ces étapes lors de la pagination de votre jeu de résultats:

Faire un count demande d'obtenir le nombre total de vidéos dans votre jeu 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 vidéos 20. Vous saurez que vous avez atteint la fin du jeu de résultats lorsque vous avez demandé autant de vidéos que dans le premier count demande.

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

      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 listes de lecture. Vous pouvez trier les champs vidéo suivants: ^[1-1]

Préfixez 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 (note: c'est le sort champ - le champ de recherche est schedule.starts_at )
schedule_ends_at (note: c'est le sort champ - 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 de 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 or 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)

Préfixez 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 connaître certaines choses:

Vous pourriez être tenté d'utiliser le plus grand autorisé limit (100), mais il est préférable de récupérer des vidéos dans des lots de 25 ou moins pour minimiser la possibilité que les demandes d'API arrivent à expiration
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 le décalage des éléments dans les réponses:
- Vous pourriez voir un article 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 prendre en compte la première possibilité, votre application doit redéfinir la liste complète des éléments une fois que vous avez terminé de récupérer les vidéos. Pour gérer la seconde possibilité, vous devez comparer le nombre total d'éléments récupérés (après dédoublonnage) au nombre attendu, puis réexécuter les requêtes, en triant les résultats par last_modified_date (en descendant). 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ées. Si vous recherchez des vidéos basées sur plusieurs mots-clés, tags et / ou champs personnalisés, trier par pertinence est exactement ce que vous voulez. Cependant, si vous essayez simplement de récupérer tout ou une grande partie de vos vidéos, sort 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 comprennent:

Obtenir le nombre de vidéos ou de résultats de recherche
Obtenez toutes les vidéos
Obtenir 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 des informations de base numériques
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 de l'API.

Opérations de playlist

Les opérations de Playlist incluent:

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

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

Des atouts

Les opérations d'actifs vous permettent de gérer des actifs, y compris des rendus, des manifestes, des images et des 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 pour tous les deux actifs ingérés et distants.

Ajouter, mettre à jour ou supprimer des rendus
Ajouter, mettre à jour ou supprimer des métadonnées pour le maître numérique
Ajouter, mettre à jour ou supprimer des manifestes pour des 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 de l'actif peuvent être trouvés dans le Référence de l'API.

Opérations de terrain personnalisées

Il y a actuellement une opération de champ personnalisée:

Obtenir tous les champs personnalisés pour un compte

Les détails des opérations de terrain personnalisées peuvent être trouvés dans le Référence de l'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 de l'API.

Notifications

Vous pouvez recevoir des notifications quand video_change les é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 gérer HTTP POST demandes.

Échecs 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 aux temps 20, avec un délai exponentiellement croissant entre les rappels suivants. Les premières tentatives auront lieu dans les minutes qui suivent la première tentative de rappel. Si le rappel continue à échouer et que nous obtenons tout le chemin d'accès à la nouvelle tentative 20th, 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 utilisateur. Par conséquent, ces événements ne correspondent pas toujours aux modifications apportées aux propriétés vidéo dans Studio ou via les API.

Les 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 Est. Ceci est susceptible d'être modifié, de sorte que toutes les adresses IP AWS doivent figurer dans 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 les suivantes:

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

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