Notifications d'API CMS

Dans cette rubrique, vous découvrirez CMS API les notifications. Le CMS API fournit des notifications des modifications apportées aux vidéos de votre compte, qu'elles soient effectuées par un utilisateur de compte ou par le système Video Cloud.

Aperçu

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

Authentification

Comme toutes les demandes adressées à l'API CMS, les demandes de configuration ou de liste d'abonnements aux notifications doivent être authentifiées à l'aide d'un jeton d'accès. Les informations d'identification client utilisées pour obtenir le jeton d'accès doivent avoir des autorisations pour video-cloud/notifications/all (CMS->Notifications si vous utilisez l' interface utilisateur de Studio pour créer les informations d'identification).

Configuration

Pour créer un nouvel abonnement, envoyez une POST demande https://cms.api.brightcove.com/v1/accounts/{account_id}/subscriptions avec un corps de requête incluant le point de terminaison auquel vous souhaitez que les notifications soient envoyées video-change et/ou en master-video-change tant qu'élément unique d'un tableau d'événements. Vous pouvez spécifier jusqu'à 10 points de terminaison par événement pour recevoir des notifications.

Les événements disponibles pour video-change concernent votre vidéothèque, et désormais, les événements pour master-video-change concernent les modifications apportées aux éléments d'une vidéo de diffusion dynamique qui seront finalement reflétées dans votre vidéo partagée.

Pour les video-change événements

{
  "endpoint":"https://solutions.brightcove.com/bcls/di-api/di-callbacks.php",
  "events":["video-change"]
}

Pour les master-video-change événements

{
  "endpoint":"https://solutions.brightcove.com/bcls/di-api/di-callbacks.php",
  "events":["master-video-change"]
}

Les notifications sont envoyées au format JSON. Voici un exemple d' video-change événements :

{
  "timestamp":1423840514446, 
  "account_id":"775205503001", 
  "event":"video-change", 
  "video":"4020894387001", 
  "version":26,
  “action”:”UPDATE”,
  “updated_by”:{ "email": "string", "id": "string", "type": "user" }
}

Et voici un master-video-change exemple de :

{
  "timestamp":1423840514446,
  "account_id":"775205503001",
  "event":"video-change",
  "video":"4020894387001", 
  "version":26, 
  "action":"UPDATE", 
  "updated_by":{ "email": "string", "id": "string", "type": "user" },
  "master_account_id":"784205904003",
  "master_video_id":"6200985429005"
}

Champs de notification

Article Description
timestamp heure à laquelle l'événement s'est produit en Epoch millisecondes
account_id l'identifiant Video Cloud du compte
master_account_id les Only for master-video-change events: The id of the master video who made the update in the assets shared with the affiliate video.
master_video_id les Only for master-video-change events: The id of the Video Cloud master account for the master video.
event le type d'événement - actuellement ce sera toujours video-change
video l'identifiant de la vidéo
version la version de la vidéo - chaque ensemble d'événements de changement incrémente la version vidéo - par exemple, la création d'un nouvel ensemble de rendus constituerait un ensemble d'événements de changement
action[1-1] l'action qui a été effectuée - l'une des suivantes :
  • UPDATE- un actif a été mis à jour
  • CREATE- un actif a été créé
  • TRIGGERED_MANUAL- une notification a été déclenchée par une application interne de Brightcove
  • DELETE- un actif a été supprimé
    		•
    updated_by[1-1] un objet contenant des informations sur l'auteur de l'action, si elles sont disponibles ; les propriétés de l'objet sont les suivantes :
  • email- l'adresse e-mail de l'utilisateur
  • id- l'identifiant système Video Cloud de l'utilisateur
  • type- le type de mise à jour :
    • user- un utilisateur dans Studio
    • api-key- un utilisateur via l'API
    • internal- un système Brightcove ou un utilisateur
    		•

    Les demandes de création d'un abonnement recevront une réponse HTTP 422 d'erreur pour les conditions suivantes :

    • Les endpoint ou events le champ est manquant dans le corps de la requête
    • Les events la valeur du champ n'est pas une liste (tableau)
    • L'abonnement défini existe déjà
    • Vous avez déjà 10 abonnements à cet événement

    Échecs de notification

    Le système de notification traite tout 4xx ou 5xx retour du serveur client en tant qu'échec réessayable. 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.

    Pare-feu

    Si votre organisation a une politique stricte concernant les sources de trafic entrant via votre pare-feu, nous autorisons les IP AWS us-east-1/Virginia. 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.

    Point de terminaison pour les abonnements aux notifications

            /accounts/{account_id}/subscriptions

    Obtenez la liste de vos abonnements

    Pour obtenir la liste de tous vos abonnements, envoyez une GET demande au point de terminaison des abonnements :.

    /accounts/{account_id}/subscriptions

    Obtenir ou supprimer un seul abonnement

    Utilisez le point de terminaison suivant pour obtenir ou supprimer un seul abonnement :

    Point de terminaison

    /accounts/{account_id}/subscriptions/{subscription_id}

    UNE GET demande récupérera l'abonnement. UNE DELETE demande supprimera l'abonnement. Vous ne pouvez pas mettre à jour un abonnement pour le moment. Si vous souhaitez modifier un abonnement, vous devrez le supprimer et en créer un nouveau.

    Qu'est-ce qui déclenche les notifications ?

    video-change les événements sont déclenchés par tout changement dans les métadonnées de la vidéo. Cela inclut toute modification apportée à la vidéo effectuée dans Studio ou via une méthode d' CMS API écriture. Il existe également des événements système qui déclencheront video-change événements.

    Les changements qui déclencheront un événement incluent :

    • Une vidéo est créée
    • L'ingestion de la vidéo ou du fichier d'éléments commence
    • L'ingestion de la vidéo ou du fichier d'éléments est terminée
    • L'encodage d'un nouveau rendu se termine
    • Une image d'affiche est créée
    • Une image miniature est créée
    • Une vidéo est activée ou désactivée
    • Une vidéo est supprimée
    • Les métadonnées de la vidéo sont modifiées (par le système ou un utilisateur)
    • master-video-change les événements sont déclenchés par des mises à jour des éléments d'une vidéo principale, ce qui les rend uniquement disponibles pour le partage.

      Les changements qui déclencheront cet événement sont les suivants

      • Les ressources ingérées sont ajoutées à la vidéo principale
      • Les éléments ingérés sont remplacés/retranscodés dans la vidéo principale

    Remarques

    Le retranscodage d'une vidéo ne déclenchera pas video-change à moins que l'ensemble de rendu résultant soit différent.

    Certains événements système se produisent après la suppression d'une vidéo. Vous recevrez donc des notifications concernant une vidéo après sa suppression.

    Ce qui sera ne pas déclencher un video-change l'événement est une modification d'un élément vidéo qui ne modifie pas les métadonnées de la vidéo. Par exemple, si vous remplacez un fichier ou une image de piste de texte distant, mais que l'URL enregistrée dans les métadonnées de la vidéo reste la même, non video-change l'événement se produira et aucune notification ne sera envoyée.

    La suppression des éléments d'une vidéo principale ne déclenchera aucun master-video-change événement. Lorsque des ressources sont supprimées dans une vidéo, c'est parce que la vidéo est en train d'être supprimée, et le partage gère déjà le processus de suppression des vidéos d'affiliation.