Pré-requis

Il faudra ensuite récupérer le code source de l'implémentation en Python du client d'API Nudgis
à cette adresse : https://github.com/UbiCastTeam/mediaserver-client/releases/latest

Veillez à consulter régulièrement les mises à jour de ce code afin de garantir le bon fonctionnement de l'API Nudgis

Puis, copiez le fichier de configuration JSON  d'exemple "config.json.example" dans le répertoire examples sous le nom "config.json" : 

cd mediaserver-client-4.5 
cp config.json.example examples/config.json

Enfin, il faut éditer le fichier de configuration (config.json) en ajoutant la clé API du compte API_KEY qui va exécuter le script  et l'adresse de votre serveur Nudgis SERVER_URL :

{
"API_KEY": "XXX",
"CLIENT_ID": "python-api-client",
"PROXIES": {
"http": "",
"https": ""
},
"SERVER_URL": "https://XXX",
"UPLOAD_CHUNK_SIZE": 5242880,
"VERIFY_SSL": false
}

Vous retrouverez votre clé d'API dans la page de votre profil utilisateur Nudgis via Mon Profil > Afficher ma clé d'API :

Pour terminer ce chapitre, nous vous recommandons fortement de créer un compte dédié à l'API sans mot de passe, et ayant uniquement les permissions adéquates en fonction du script exécuté. Ce compte ne pourra pas se connecter à Nudgis (car le mot de passe est vide).

La clé d'API maître du site ne doit jamais être utilisée dans le cadre de l'API Nudgis

Utilisation des scripts

Les scripts disponibles se trouvent dans le répertoire "examples" du projet.

Tout d'abord, afin de vérifier que la configuration du fichier "config.json" est correcte et que vous pouvez communiquer avec votre serveur, il faut exécuter le script ping_server.py.

Ce script ne nécessite aucune permission particulière. La commande doit retourner un succès, ainsi que le numéro de version de votre serveur Nudgis. Un retour correct sera libellé comme suit :

cd examples
python3 ping_server.py config.json 
{'success': True, 'mediaserver': '13.0.1'}

Ce test réalisé avec succès, il vous est désormais possible d'exécuter les scripts du répertoire examples. Nous commencerons leur exploration en présentant des scripts permettant de gérer le stockage de votre serveur en gagnant de l'espace disque lorsque c'est possible.

Cycle de vie des vidéos

L'espace disque de votre serveur étant limité, il sera nécessaire d'effectuer régulièrement un nettoyage de vos vidéos. Cette opération est grandement facilitée par les scripts présentés ci-dessous. Toutefois, ils sont à utiliser avec la plus grande précaution, car ils vont supprimer définitivement des données de votre serveur. C'est pourquoi ces scripts permettent de réaliser des tests à blanc afin de valider les conditions de suppression. Leur utilisation implique d'avoir la permission d'accéder et supprimer les médias de votre catalogue.

Le premier script à votre disposition est delete_video_qualities.py . Il permet de supprimer les qualités vidéo indésirables d'une chaîne, ou à partir d'un fichier csv. Une fois le script exécuté, seule la meilleure qualité de la ressource MP4 (ou MP3 le cas échéant) est conservée. Vous devez de plus avoir la permission d'édition "Fichiers de ressource" pour pouvoir exécuter ce script.

Mais vous pouvez également choisir les résolutions à effacer individuellement. Par exemple, pour simuler la suppression des qualités 360p d'une chaîne (représentée dans le script par son identifiant, ou OID), il faut exécuter la commande suivante :

python delete_video_qualities.py --conf config.json --channel c12640c68e63b949rq65 --qualities "360" 

A la fin de l'exécution du script, l'espace disque qui sera libéré est affiché comme suit :

Would have freed 1 GB (29 resources) if run with "--delete".

Si le résultat convient, vous pouvez appliquer concrètement la suppression en ajoutant l'option --delete

python delete_video_qualities.py --conf config.json --channel c12640c68e63b949rq65 --qualities "360" --delete

La commande suivante permet de connaître le détail des options du script : 

python delete_video_qualities.py --help

Le second script présenté, cleanup_unwatched_media.py, permet de supprimer les médias non visionnés. Ce script nécessite, en plus des permissions d'accès et suppression des médias, d'avoir la permission globale "Peut consulter toutes les statistiques" et la permission d'édition "Fichiers de ressource".

Par exemple, la commande pour simuler la suppression des médias qui ont 10 vues (ou moins de 10)  pour l'année l'année 2023 et les mettre dans la corbeille sera la suivante :

python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash

Vous pouvez appliquer le script sur une chaîne en particulier, au lieu d'adresser l'ensemble du catalogue, si vous ajoutez le paramètre --channel-oid avec l'identifiant de votre chaîne

python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash --channel-oid c12664e08d3623prveob

A la fin de l'exécution du script, l'espace disque qui sera libéré est affiché comme suit :

Trashing these VODs would have freed up to 61.4MB

Si le résultat convient, vous pouvez appliquer concrètement la suppression en ajoutant le paramètre --apply : 

python cleanup_unwatched_media.py --conf config.json --start-date 2023-01-01 --end-date "2023-12-31" --max-views 10 --action trash --channel-oid c12664e08d3623prveob --apply

La commande suivante permet de connaître le détail des options du script : 

python cleanup_unwatched_media.py --help

Pour terminer ce chapitre, découvrons le script mass_delete.py, qui donne la possibilité de faire une suppression en masse en spécifiant une liste d'identifiants de vidéos avec un fichier CSV dans la première colonne. Les lignes commençant par "#" sont ignorées.

L'identifiant d'une vidéo peut également être retrouvé dans le lien permanent du média

Ce script nécessite la permission globale supplémentaire "Peut éditer les paramètres du site" et la permission d'édition "Fichiers de ressource". La commande suivante permet d'exécuter le script :

python mass_delete.py --conf config.json --csv ./videos-id.csv

Le résultat obtenu doit être similaire à la ligne suivante : 

Deleting these VODs would have freed 4.1 GB

Si le résultat convient, vous pouvez appliquer concrètement la suppression en ajoutant le paramètre --apply : 

python mass_delete.py --conf config.json --csv ./videos-id.csv --apply

Si vous ne voulez pas que les médias aillent dans la corbeille, ajoutez le paramètre --permanent. Attention toutefois à l'utilisation de cette option, car la suppression sera alors immédiate et définitive : 

python mass_delete.py --conf config.json --csv ./videos-id.csv --apply --permanent

La commande suivante permet de connaître le détail des options du script : 

python mass_delete.py --help

Statistiques et métriques

De nombreuses informations sur l'utilisation du portail sont disponibles dans l'interface du site, comme le décrit l'article Les statistiques dans Nudgis.  Il est toutefois possible d'aller encore plus loin en utilisant le script csv_media_stats.py , qui permet d'extraire des métriques qui ne sont pas disponibles dans les statistiques Nudgis. Il est par exemple possible d'obtenir des informations sur la répartition de vos médias par type, durée, et données par intervenant, comme les dix plus importants contributeurs en terme de médias déposés, par exemple.

Pour pouvoir analyser ces données, il faudra d'abord les générer en exécutant le script csv_media_generate.py. Vous devez avoir la permission globale "Peut éditer les paramètres du site" pour lancer ce script, dont la commande générera un fichier CSV :

python csv_media_generate.py config.json 

Une fois le fichier généré, vous pourrez lancer son analyse avec la commande suivante :

python csv_media_stats.py --input media-monserveur.fr.csv 

De plus, il est possible de récupérer la liste des médias d'un intervenant au format CSV. Il suffit de spécifier le courriel de l'intervenant via le paramètre --target-email à l'aide du script list_media_for_speaker.py. Il est nécessaire d'avoir la permission d'accéder et éditer les médias du catalogue pour utiliser ce script :

python list_media_for_speaker.py --conf config.json --target-email "test@ubicast.eu"

Réversibilité

L'API Nudgis offre également la possibilité de récupérer les données pour effectuer une sauvegarde ou une migration. Le script backup_media.py générera une archive ZIP contenant les métadonnées de la vidéo ainsi que la meilleure qualité de la ressource vidéo. Ce script nécessite d'avoir la permission d'édition "Fichiers de ressource" et "Paramètres de communauté". Pour sauvegarder les médias avant 2024, utilisez la commande suivante : 

python backup_media.py --conf config.json --date 2024-01-01

Par défaut, la sauvegarde ira dans le répertoire "backups"

Pour supprimer les fichiers sauvegardés, ajoutez l'option --delete . Attention toutefois à l'utilisation de cette option, car la suppression sera alors immédiate et définitive : 

python backup_media.py --conf config.json --date 2024-01-01 --delete

La commande suivante permet de connaître le détail des options du script : 

python backup_media.py --help

Le script suivant, backup_channel_recursive.py, permet de restreindre la sauvegarde par chaîne en spécifiant l'identifiant de la chaîne, mais effectuera également une sauvegarde par défaut dans le répertoire "backups" :

 python backup_channel_recursive.py --conf config.json --channel c12640c68e63b949rq65

Pour restaurer la sauvegarde sur Nudgis, il suffit d'utiliser le script restore_media.py en spécifiant le répertoire de votre sauvegarde. Les médias sont restaurés dans leur chaîne originale : 

python restore_media.py --conf config.json --path backups

Vous pouvez aussi restaurer les médias dans une autre chaîne existante sur votre serveur Nudgis en utilisant le paramètre --channelsuivi de l'OID correspondant. Auquel cas, les médias seront restaurés dans ladite chaîne :

  python restore_media.py --conf config.json --path backups --channel c1266553ef1690qfgln9

python download_all_original_files.py config.json VideosHD