Questo articolo è dedicato agli amministratori di Nudgis che hanno bisogno di automatizzare le attività utilizzando l'API di Nudgis, come la configurazione di un flusso di lavoro subordinato al proprio sistema informativo.

Indice dei contenuti

1/ PREREQUISITI

  1.1/ FILE DI CONFIGURAZIONE

  1.2/ CHIAVE API

2/ UTILIZZO DEGLI SCRIPT

  2.1/ CICLO DI VITA DEL VIDEO

  2.2/ STATISTICHE E METRICHE

  2.3/ REVERSIBILITÀ

Per rendere più semplice l'utilizzo di questa funzione, UbiCast ha creato un client API Nudgis in Python con script pronti all'uso. Inizieremo spiegando i requisiti di installazione per l'utilizzo di questi script. Successivamente, approfondiremo l'uso di determinati script rilevanti nel contesto del ciclo di vita dei media, statistiche/metriche e, infine, il processo di reversibilità. Prima di iniziare, è possibile accedere ai dettagli dell'API di Nudgis tramite il menu 'Amministrazione > Informazioni su questo sito > Documentazione API':

Prerequisiti

Per utilizzare il client API di Nudgis, è necessario installare l'ambiente Python.
Si prega di consultare la documentazione ufficiale del progetto Python per l'installazione.
Il client API di Nudgis richiede solo che il modulo Python 'Requests' sia installato come dipendenza.

Sarà quindi necessario scaricare il codice sorgente per l'implementazione Python del client API di Nudgis a questo indirizzo: https://github.com/UbiCastTeam/mediaserver-client/releases/latest

Assicurarsi di verificare regolarmente la presenza di aggiornamenti a questo codice per garantire che l'API di Nudgis funzioni correttamente.

File di configurazione

Quindi copiare il file di configurazione JSON di esempio 'config.json.example' nella directory degli esempi con il nome 'config.json':

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

Infine, è necessario modificare il file di configurazione (config.json) aggiungendo la chiave API dell'account API_KEY che eseguirà lo script e l'indirizzo del proprio server 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 }

Chiave API

È possibile trovare la chiave API nella pagina del profilo utente di Nudgis tramite Il mio profilo > Visualizza la mia chiave API:

Per terminare questo capitolo, consigliamo vivamente di creare un account API dedicato senza password e con solo i permessi appropriati per lo script in esecuzione. Questo account non sarà in grado di connettersi a Nudgis (poiché la password è vuota).

La chiave API master del sito non deve mai essere utilizzata per l'API di Nudgis.

Utilizzo degli script

Gli script disponibili si trovano nella directory 'examples' del progetto.

Innanzitutto, per verificare che la configurazione nel file 'config.json' sia corretta e che sia possibile comunicare con il server, è necessario eseguire lo script ping_server.py.

Questo script non richiede alcun permesso particolare. Il comando deve restituire un esito positivo, nonché il numero di versione del proprio server Nudgis. Un ritorno corretto si leggerà come segue:

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

Dopo aver completato con successo questo test, è ora possibile eseguire gli script nella directory degli esempi. Inizieremo la nostra esplorazione presentando gli script per la gestione dell'archiviazione del server, risparmiando spazio su disco ove possibile.

Ciclo di vita del video

Poiché lo spazio su disco del server è limitato, sarà necessario pulire regolarmente i video. Questa operazione è resa molto più semplice dagli script presentati di seguito. Tuttavia, dovrebbero essere usati con la massima cura, poiché elimineranno in modo permanente i dati dal server. Ecco perché questi script consentono di eseguire test a vuoto per convalidare le condizioni di eliminazione. Per utilizzarli, è necessario disporre dell'autorizzazione per accedere ed eliminare i media nel proprio catalogo.

Il primo script disponibile è delete_video_qualities.py. Può essere utilizzato per eliminare qualità video indesiderate da un canale o da un file csv. Una volta eseguito lo script, viene mantenuta solo la migliore qualità della risorsa MP4 (o MP3 se applicabile). È inoltre necessario disporre dell'autorizzazione di modifica 'File di risorse' per poter eseguire questo script.

Ma è anche possibile scegliere quali risoluzioni eliminare individualmente. Ad esempio, per simulare l'eliminazione delle qualità 360p di un canale (rappresentato nello script dal suo identificatore, o OID), eseguire il seguente comando:

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

Al termine dell'esecuzione dello script, lo spazio su disco che verrà liberato viene visualizzato come segue:

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

Se il risultato è soddisfacente, è possibile applicare l'eliminazione aggiungendo l'opzione --delete

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

Il comando seguente fornisce i dettagli sulle opzioni dello script:

python delete_video_qualities.py --help

Il secondo script presentato, cleanup_unwatched_media.py, elimina i media non visualizzati. Oltre ai permessi di accesso ed eliminazione dei media, questo script richiede il permesso globale 'Può vedere tutte le statistiche' e il permesso di modifica 'File di risorse'.

Ad esempio, il comando per simulare l'eliminazione dei media che hanno 10 visualizzazioni (o meno) per l'anno 2023 e inserirli nel cestino sarebbe il seguente:

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

È possibile specificare un canale particolare invece di indirizzare l'intero catalogo, aggiungendo l'opzione --channel-oid con l'OID del canale selezionato a seguire:

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

Al termine dell'esecuzione dello script, lo spazio su disco che verrà liberato viene visualizzato come segue:

Trashing these VODs would have freed up to 61.4MB

Se il risultato è soddisfacente, è possibile applicare l'eliminazione aggiungendo l'opzione --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

Il comando seguente fornisce i dettagli sulle opzioni dello script:

python cleanup_unwatched_media.py --help

Per concludere questo capitolo, diamo un'occhiata allo script mass_delete.py, che consente di eseguire un'eliminazione di massa specificando un elenco di identificatori video con un file CSV nella prima colonna. Le righe che iniziano con '#' vengono ignorate.

L'ID video può essere trovato anche nel link permanente dei media

Questo script richiede il permesso globale aggiuntivo 'Può modificare le impostazioni del sito' e il permesso di modifica 'File di risorse'. Utilizzare il comando seguente per eseguire lo script:

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

Il risultato dovrebbe essere simile alla riga seguente:

Deleting these VODs would have freed 4.1 GB

Se il risultato è soddisfacente, è possibile applicare l'eliminazione aggiungendo l'opzione --apply:

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

Se non si desidera che i media vadano nel cestino, aggiungere l'opzione --permanent. Fare attenzione quando la si utilizza, tuttavia, poiché l'eliminazione sarà immediata e permanente:

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

Il comando seguente fornisce i dettagli sulle opzioni dello script:

python mass_delete.py --help

Statistiche e metriche

Molte informazioni sull'utilizzo del portale sono disponibili nell'interfaccia del sito, come descritto nell'articolo 'Statistiche in Nudgis'. Tuttavia, è possibile andare ancora oltre utilizzando lo script csv_media_stats.py, che può essere utilizzato per estrarre metriche non disponibili nelle statistiche di Nudgis. Ad esempio, è possibile ottenere informazioni sulla distribuzione dei media per tipo, durata e dati per collaboratore, come i dieci maggiori collaboratori in termini di media pubblicati, ad esempio.

Per poter analizzare questi dati, è prima necessario generarli eseguendo lo script csv_media_generate.py. È necessario disporre del permesso globale 'Può modificare le impostazioni del sito' per eseguire questo script, il cui comando genererà un file CSV:

python csv_media_generate.py config.json

Una volta generato il file, è possibile eseguire la sua analisi con il seguente comando:

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

È anche possibile recuperare l'elenco dei media di un relatore in formato CSV. È sufficiente specificare l'indirizzo email del relatore utilizzando l'opzione --target-email, utilizzando lo script list_media_for_speaker.py. È necessario disporre dell'autorizzazione per accedere e modificare i media nel catalogo per utilizzare questo script:

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

Reversibilità

L'API di Nudgis offre anche l'opzione di recuperare i dati per il backup o la migrazione. Lo script backup_media.py genererà un archivio ZIP contenente i metadati del video e la risorsa video di migliore qualità. Questo script richiede l'autorizzazione di modifica 'File di risorse' e 'Impostazioni della community'. Per salvare i media caricati prima del 2024, utilizzare il comando seguente:

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

Per impostazione predefinita, il backup andrà nella directory 'backups'

Per eliminare i file di backup, aggiungere l'opzione --delete. Fare attenzione quando si utilizza questa opzione, tuttavia, poiché l'eliminazione sarà immediata e definitiva:

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

Il comando seguente fornisce i dettagli sulle opzioni dello script:

python backup_media.py --help

Il seguente script, backup_channel_recursive.py, consente di limitare il backup per canale specificando l'identificatore del canale, ma eseguirà anche un backup predefinito nella directory 'backups':

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

Per ripristinare il backup su Nudgis, è sufficiente utilizzare lo script restore_media.py e specificare la directory del proprio backup. I media vengono ripristinati nella loro catena originale:

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

È anche possibile ripristinare i media su un altro canale esistente sul server Nudgis utilizzando l'opzione --channel con l'OID del canale corrispondente a seguire. In questo caso, i media verranno ripristinati su quel canale:

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

L'ultimo script, download_all_original_files.py, recupera solo la migliore qualità della risorsa originale, che nella maggior parte dei casi è l'MP4 con la migliore risoluzione. Per completare il comando, è sufficiente specificare una directory di destinazione ('VideosHD' nell'esempio seguente).

python download_all_original_files.py config.json VideosHD

Speriamo che questo articolo ti abbia aiutato a familiarizzare con questa funzionalità e le sue molteplici possibilità. Non esitare a raccontarci la tua esperienza con l'API di Nudgis nei commenti!

Per continuare: "La documentazione dell'API di Nudgis"