API en direct : Notifications

Cette rubrique montre comment configurer des notifications pour les tâches Live API.

Introduction

Le système Brightcove Live envoie des notifications de divers événements. Vous pouvez configurer des écouteurs pour les notifications afin de déclencher d'autres actions. Le ou les écouteurs peuvent être écrits dans n'importe quel langage côté serveur que vous utilisez, et ils rechercheraient les requêtes POST entrantes, analyseraient le corps de la requête JSON, puis prendraient l'action que vous souhaitez. Ci-dessous, nous verrons comment vous pouvez demander des notifications.

Demander des notifications

Vous pouvez demander des notifications en incluant un ou plusieurs notifications champs dans les sorties votre Créer un travail demander.

La valeur de notifications est un tableau d'objets de destination de notification. Vous pouvez utiliser une chaîne simple avec une URL : "https://httpbin.org/post", ou vous pouvez utiliser un objet avec les options suivantes : {"url": "https://httpbin.org/post", "credentials": "reference_to_your_credentials"}. Une notification sera envoyée à la destination que vous spécifiez lorsque la sortie change d'état. Si vous appliquez ce paramètre à une sortie VOD, les notifications ne seront liées qu'à cette tâche VOD, pas à la tâche en direct.

Voici quelques exemples :

Notifications pour un travail en direct

{
    "live_stream": true,
    "region": "us-west-2",
    "reconnect_time": 20,
    "notifications": [
      {"url": "https://httpbin.org/post/URLA",
        "credentials": "reference_to_your_credentials",
        "event": "first_segment_uploaded"},
      {"url": "https://httpbin.org/post/URLB",
      "credentials": "reference_to_your_credentials",
      "event": "state_changed"}
      ],
    "outputs": [
    {
        "label": "hls360p",
        "live_stream": true,
        "height": 360,
        "video_bitrate": 650,
        "segment_seconds": 6
    },
    {
        "url":"s3://YOURBUCKET/path/filename.mp4",
        "credentials": "accConfiguredCredsAWSIdSecret",
        "notifications":    [
        {
            "url": "https://httpbin.org/post?vodStateChange"
        },
        {
            "url": "https://httpbin.org/post?vodFinished",
            "event": "output_finished"
        }
        ]
    }]
}

Notifications pour Live to VOD (output_finished événement uniquement)

{
  "videocloud": {
    "video": {
      "name": "video name"
    }
  },
  "notifications": [{
    "url": "https://httpbin.org/post?vodFinished",
    "event": "output_finished"
  }]
}

Notifications pour Live to VOD (tous les événements)

{
  "videocloud": {
    "video": {
      "name": "video name"
    }
  },
  "notifications": [{
    "url": "https://httpbin.org/post"
  }]
}

Stratégie de nouvelle tentative

En cas d'échec d'une demande d'envoi de notification, la stratégie de relance par défaut consiste à réessayer 50 fois avec un délai exponentiel entre les tentatives.

          max_retry_times = 50
          delay_delta_s = 5
          next_retry = now_s + retry_count * delay_delta_s

Evénements

Vous trouverez ci-dessous les événements d'un cycle de vie d'emploi que vous pouvez écouter. Notez que la portée de l'événement est par tâche, de sorte que le cycle de vie de l'événement pour une tâche en direct serait distinct du cycle de vie d'une tâche de découpage VOD basée sur le même flux en direct.

  • state_changed- l'état de la tâche en cours a changé ; voir le tableau ci-dessous pour plus de détails
  • first_segment_uploaded- le premier segment de la diffusion en direct est téléchargé sur Origin
  • output_finished- l'événement en direct est terminé et le traitement VOD a créé au moins un rendu audio et un rendu vidéo, ou un rendu MP4 progressif

Les state_changed notifiera sur les états suivants décrits dans le tableau ci-dessous

États des tâches en direct
État Description
États JOB (indiqués dans les notifications comme state)
error Une erreur s'est produite ; la tâche ne sera pas traitée.
standby (Applicable uniquement aux travaux de point d'entrée statique [SEP].) Le travail est alloué et prêt à être activé.
waiting Le travail a été attribué à un travailleur en streaming et prêt pour la connexion de l'encodeur.
processing L'encodeur est connecté et le travail est disponible pour la lecture.
disconnected L'encodeur s'est déconnecté et l'agent de streaming attend une reconnexion.
cancelling Le travail a été annulé et le travailleur arrête le travail et ne traitera PAS les sorties VOD en attente.
finishing L'encodeur est déconnecté depuis plus de reconnect_time, et le responsable du streaming arrête les tâches et crée toutes les sorties VOD associées.
cancelled Le travail a été annulé avec succès.
finished Le travail s'est terminé avec succès.
failed Le travail s'est arrêté en raison d'une erreur système.
États JOB VOD (signalés dans les notifications comme jvod_state)
error Une erreur s'est produite ; la tâche ne sera pas traitée.
waiting Le travail en attente de traitement.
waiting_finish_live Le travail en attente de la fin du travail en direct (si le clip en dépend).
processing Le clip est en cours de traitement.
creating_asset Un actif VOD est en cours de création.
cancelling Le travail a été annulé et le travailleur arrête le travail et ne traitera PAS les sorties VOD en attente.
cancelled Le travail a été annulé avec succès.
finished Le travail s'est terminé avec succès.
failed Le travail s'est arrêté en raison d'une erreur système.
États SSAI (indiqués dans les notifications comme ssai_state)
none Le travail n'est pas un travail SSAI.
waiting_input L'agent de streaming attend que l'encodeur se connecte et fournisse les informations d'entrée de flux.
start_transcoding L'encodeur s'est connecté et l'ardoise SSAI a été mise en file d'attente pour le transcodage en fonction des données d'entrée et de sortie du flux.
transcoding L'ardoise est en cours de transcodage.
error L'ardoise n'a pas pu être téléchargée ou transcodée.
ready L'ardoise a été générée et le travail est prêt pour la lecture SSAI.
États SEP (indiqués dans les notifications comme sep_state)
none Le travail n'est pas un travail SEP.
ready Le point d'entrée a été activé et prêt pour la connexion de l'encodeur.
pending_activation Le point d'entrée a été mis en file d'attente pour l'affectation des travailleurs en streaming.
activation_in_progress Le point d'entrée est en cours de mise à jour pour acheminer les connexions vers le travailleur en streaming.
pending_deactivation Le point d'entrée a été mis en file d'attente pour le nettoyage du flux de travail.
deactivation_in_progress Le point d'entrée est en train de se déconnecter du flux de travail.
cancelled Le point d'entrée a été annulé.
finished Le point d'entrée s'est terminé avec succès.
États de sortie RTMP (rapportés pour rtmp_output_state_changed notifications en tant que state)
starting Le flux démarre.
connected L'encodeur est connecté.
Disconnected L'encodeur s'est déconnecté.
error Le flux n'a pas réussi à se connecter.
pending_deactivation Le point d'entrée a été mis en file d'attente pour le nettoyage du flux de travail.
deactivation_in_progress Le point d'entrée est en train de se déconnecter du flux de travail.
cancelled Le point d'entrée a été annulé.
finished Le point d'entrée s'est terminé avec succès.

Exemples de notifications

Notification de diffusion en direct

Voici un exemple de notification pour un state_changed événement pour un emploi en direct :

          {
              "outputs": [
                  {
                      "rfc_6381_video_codec": null,
                      "finished_at": "2017-10-19T20:08:11.115Z",
                      "segment_seconds": 4,
                      "created_at": "2017-10-19T19:47:04.534Z",
                      "privacy": false,
                      "md5_checksum": null,
                      "audio_codec": "AAC",
                      "error_class": null,
                      "updated_at": "2017-10-19T20:08:11.115Z",
                      "video_bitrate_in_kbps": 2150.4,
                      "id": "0-621669558be84a7da4ff20bccb9a6a1a",
                      "state": "cancelled",
                      "playback_url": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_0\/chunklist.m3u8",
                      "duration_in_ms": 1156873,
                      "file_size_bytes": null,
                      "height": 720,
                      "playback_url_dvr": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_0\/chunklist_dvr.m3u8",
                      "error_message": null,
                      "video_codec": "H.264",
                      "audio_bitrate_in_kbps": 196.608,
                      "fragment_duration_in_ms": null,
                      "test": false,
                      "playback_url_vod": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_0\/chunklist_vod.m3u8",
                      "total_bitrate_in_kbps": 2347.008,
                      "format": null,
                      "label": "hls720p",
                      "frame_rate": null,
                      "video_codec_profile": "high",
                      "keyframe_interval": 60,
                      "keyframe_interval_follow_source": false,
                      "live_stream": true,
                      "channels": null,
                      "playback_added_cdns": [

                      ],
                      "width": 1280,
                      "rfc_6381_audio_codec": null,
                      "audio_sample_rate": null
                  },
                  {
                      "rfc_6381_video_codec": null,
                      "finished_at": "2017-10-19T20:08:11.115Z",
                      "segment_seconds": 4,
                      "created_at": "2017-10-19T19:47:04.534Z",
                      "privacy": false,
                      "md5_checksum": null,
                      "audio_codec": "AAC",
                      "error_class": null,
                      "updated_at": "2017-10-19T20:08:11.115Z",
                      "video_bitrate_in_kbps": 1536,
                      "id": "1-621669558be84a7da4ff20bccb9a6a1a",
                      "state": "cancelled",
                      "playback_url": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_1\/chunklist.m3u8",
                      "duration_in_ms": 1156873,
                      "file_size_bytes": null,
                      "height": 540,
                      "playback_url_dvr": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_1\/chunklist_dvr.m3u8",
                      "error_message": null,
                      "video_codec": "H.264",
                      "audio_bitrate_in_kbps": 196.608,
                      "fragment_duration_in_ms": null,
                      "test": false,
                      "playback_url_vod": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_1\/chunklist_vod.m3u8",
                      "total_bitrate_in_kbps": 1732.608,
                      "format": null,
                      "label": "hls540p",
                      "frame_rate": null,
                      "video_codec_profile": "main",
                      "keyframe_interval": 60,
                      "keyframe_interval_follow_source": false,
                      "live_stream": true,
                      "channels": null,
                      "playback_added_cdns": [

                      ],
                      "width": 960,
                      "rfc_6381_audio_codec": null,
                      "audio_sample_rate": null
                  },
                  {
                      "rfc_6381_video_codec": null,
                      "finished_at": "2017-10-19T20:08:11.115Z",
                      "segment_seconds": 4,
                      "created_at": "2017-10-19T19:47:04.534Z",
                      "privacy": false,
                      "md5_checksum": null,
                      "audio_codec": "AAC",
                      "error_class": null,
                      "updated_at": "2017-10-19T20:08:11.115Z",
                      "video_bitrate_in_kbps": 819.2,
                      "id": "2-621669558be84a7da4ff20bccb9a6a1a",
                      "state": "cancelled",
                      "playback_url": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_2\/chunklist.m3u8",
                      "duration_in_ms": 1156873,
                      "file_size_bytes": null,
                      "height": 360,
                      "playback_url_dvr": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_2\/chunklist_dvr.m3u8",
                      "error_message": null,
                      "video_codec": "H.264",
                      "audio_bitrate_in_kbps": 196.608,
                      "fragment_duration_in_ms": null,
                      "test": false,
                      "playback_url_vod": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/profile_2\/chunklist_vod.m3u8",
                      "total_bitrate_in_kbps": 1015.808,
                      "format": null,
                      "label": "hls360p",
                      "frame_rate": null,
                      "video_codec_profile": "main",
                      "keyframe_interval": 60,
                      "keyframe_interval_follow_source": false,
                      "live_stream": true,
                      "channels": null,
                      "playback_added_cdns": [

                      ],
                      "width": 640,
                      "rfc_6381_audio_codec": null,
                      "audio_sample_rate": null
                  },
                  {
                      "playlist_type": "defaultS3",
                      "dvr_filename": "playlist_dvr.m3u8",
                      "filename": "playlist.m3u8",
                      "playback_url": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/playlist.m3u8",
                      "type": "playlist",
                      "playback_url_dvr": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/playlist_dvr.m3u8"
                  }
              ],
              "input": {
                  "finished_at": "2017-10-19T20:08:11.115Z",
                  "created_at": "2017-10-19T19:47:04.534Z",
                  "privacy": false,
                  "md5_checksum": null,
                  "audio_codec": null,
                  "error_class": null,
                  "updated_at": "2017-10-19T20:08:11.115Z",
                  "video_bitrate_in_kbps": null,
                  "id": "input-621669558be84a7da4ff20bccb9a6a1a",
                  "state": "cancelled",
                  "duration_in_ms": 1156873,
                  "file_size_bytes": null,
                  "audio_tracks": null,
                  "height": null,
                  "error_message": null,
                  "video_codec": null,
                  "audio_bitrate_in_kbps": null,
                  "test": false,
                  "total_bitrate_in_kbps": null,
                  "format": null,
                  "frame_rate": null,
                  "url": null,
                  "channels": null,
                  "width": null,
                  "audio_sample_rate": null
              },
              "event": "state_changed",
              "job": {
                  "event_length": 0,
                  "static": false,
                  "finished_at": "2017-10-19T20:08:11.115Z",
                  "test": false,
                  "submitted_at": "2017-10-19T19:47:04.534Z",
                  "created_at": "2017-10-19T19:47:04.534Z",
                  "privacy": false,
                  "out_worker_bytes_rate": 0,
                  "ad_insertion": false,
                  "metadata_passthrough": false,
                  "live_stream": true,
                  "out_worker_bytes": 147114065,
                  "live_dvr_sliding_window_duration_ms": 57600000,
                  "updated_at": "2017-10-19T20:08:11.115Z",
                  "encryption": [

                  ],
                  "live_dvr_sliding_window_duration_ms": 57600000,
                  "ssai_state": "none",
                  "id": "621669558be84a7da4ff20bccb9a6a1a",
                  "state": "cancelled",
                  "playback_url": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/playlist.m3u8",
                  "region": "us-west-2",
                  "reconnect_time": 1800,
                  "playback_url_dvr": "https:\/\/bcovlive-a.akamaihd.net\/621669558be84a7da4ff20bccb9a6a1a\/us-west-2\/NA\/playlist_dvr.m3u8"
              }
          }

Coupure à l'échantillon S3

Vous trouverez ci-dessous un exemple d' state_changed événement permettant de créer un clip et de l'envoyer vers un compartiment S3. Notez qu'il inclut l'adresse S3 du clip comme jvod_url.

          {
              "jvod_id": "b750cce9e21a4cc894c4507208495b0c",
              "jvod_url": "s3:\/\/some.bucket\/test_dur60.mp4",
              "jvod_created_at": 1517520650785,
              "jvod_duration_s": 30,
              "jvod_cancelling_flag": false,
              "label": "last_30",
              "jvod_reported_duration_s": null,
              "jvod_finished_at": 0,
              "jvod_type": "s3",
              "account_id": "a95ac581551b4478b27910e5675db1f8",
              "jvod_worker_id": "b55b6fec738e4d2788544d3233b5ecf6",
              "user_id": "c2691d4d039040be96c190a949d754a7",
              "job_id": "7005c6e07bc24ca7b69b6b9d24052720",
              "jvod_last_state_change_at": 1517520652312,
              "jvod_region": "us-west-2",
              "cloud_id": "301c91a5d9254b5d944b108c355f12be",
              "event": "state_changed",
              "jvod_state": "processing"
          }

Gestion des notifications

Pour recevoir des notifications, vous avez simplement besoin d'une application pouvant recevoir HTTP/HTTPS POST demandes. L'application peut ensuite analyser les notifications JSON et faire ce que vous voulez en fonction de leur contenu.

À titre d'exemple simple, voici une application PHP que nous utilisons dans Brightcove Learning Services pour recevoir des notifications et les écrire dans un fichier texte.

          <? php
            //POST ne fonctionnera pas pour les données JSON
            $problem = "No errors";
            $NotificationType = null ;
            essayez {
                $json = file_get_contents ('php : //entrée') ;
                $decoded = json_decode ($json, vrai) ;
                //transformer la notification en JSON joli imprimé
                $notification = json_encode ($décodé, JSON_PRETTY_PRINT) ;
            } capture (Exception $e) {
                $problem = $e— > getMessage () ;
                $notification = $json ;
            }

            $logEntry = $notification. » \ n \ n » ;

            //Dites à PHP où il peut trouver le fichier journal et dire à PHP de l'ouvrir
            //et ajoutez la chaîne que nous avons créée plus tôt.
                $logFileLocation = "live-log.txt « ;
                $fileHandle = fopen ($logFileLocation, 'a') ou die (« -1") ;
                fwrite ($FileHandle, $LogEntry) ;
                fclose ($FileHandle) ;

            //ligne ci-dessous s'affiche lorsque vous naviguez directement dans l'application
            echo « L'application de rappel en direct est en cours d'exécution » ;
            ? >

Remarques

  • Dans certains cas, des notifications identiques seront envoyées plusieurs fois. Si votre gestionnaire effectue des actions (en dehors de la simple journalisation) basées sur des notifications, vous devez le configurer pour vérifier les doublons (plusieurs notifications avec les mêmes notifications id et status) et ignorez-les.

Configurer les notifications dans le module Live

Pour configurer des notifications pour un événement en direct créé dans le module Live, vous devrez procéder comme suit :

  1. Créez une application de gestion qui peut recevoir des requêtes POST comme l'application PHP illustrée dans la section précédente.
  2. Hébergez l'application sur une URL publique.
  3. Lorsque vous créez votre job live dans le module Live, développez le Options avancées.
  4. Vérifier la Activer l'option de notification d'état du flux et saisissez l'URL de votre application de gestion :
    Activer les notifications dans Live Module
    Activer les notifications dans Live Module