Guida pratica: Gestire stato e condizione | Frame.io API Documentation

Introduzione

Questa guida spiega come gestire lo stato del dispositivo e mantenere la sincronizzazione con Frame.io. Utilizziamo un protocollo di websocket che consente la comunicazione in tempo reale tra Frame.io e il dispositivo. Se non conosci i websocket, questa guida ti aiuterà a comprenderne l’implementazione per le integrazioni C2C.

I websocket consentono a Frame.io di inviare messaggi al dispositivo e, mantenendo una connessione permanente, offrono un canale di comunicazione più efficiente rispetto alle richieste HTTP tradizionali.

In questa guida tratteremo questi argomenti:

Apertura di una connessione socket per indicare che il dispositivo è “online”
Recupero delle informazioni sulla connessione del dispositivo
Verifica della disponibilità del backend di Frame.io

Prerequisiti

Se non l’hai già fatto, consulta la guida Implementazione C2C: configurazione prima di procedere. Avrai bisogno dell’access_token ottenuto durante il processo di autenticazione e autorizzazione. Tieni presente che i token scadono dopo 8 ore, quindi potresti dover aggiornare il token o ripetere il processo di autorizzazione. Per gli esempi di connessione websocket di questa guida, consigliamo di usare websocat, uno strumento CLI con istruzioni di installazione complete per vari sistemi operativi.

MacOS

Esegui l’installazione con brew install websocat

Recupero delle informazioni di connessione

Dopo ogni nuova autorizzazione o aggiornamento del token, il dispositivo deve interrogare immediatamente l’endpoint identity. Ciò fornisce informazioni cruciali sulla connessione:

$ curl -X GET https://api.frame.io/v2/devices/me \
>     --header 'Authorization: Bearer [access_token]' \
>     --header 'x-client-version: 2.0.0' \
>     | python -m json.tool

La risposta sarà simile a questa (con alcuni dati abbreviati):

{
    "_type": "project_device",
    "id": "a7e95254-8cd6-4d59-b54d-28c58570a8de",
    "asset_type": "video",
    "authorization": {
        "_type": "project_device_authorization",
        "creator": {
            "_type": "user",
            "id": "e7e96254-8bd6-4d59-b54d-28c58570a8de",
            "name": "Harry Potter"
        },
        "expires_at": null,
        "id": "7b2b68e5-788d-497c-8597-f9362cb1a75e",
        ...
        "project_device_id": "14856308-46e0-4d7d-8438-320262eec74e",
        "scopes": {
            ...
            "asset_create": true,
            ...
            "id": "0fe0accb-447f-44f6-b2af-177d913b3a29",
            "offline": true,
            ...
        }
    },
    ...
    "name": "Frameio-BPEAKE-TEST-DEVICE",
    "project": {
        "_type": "project",
        "id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3",
        "name": "Testbed"
    },
    "project_id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3",
    "status": "online",
    ...
}

Questo endpoint consente di verificare i dettagli della connessione. Il dispositivo deve mostrare queste informazioni agli utenti:

project.name: il nome del progetto connesso
authorization.creator.name: l’utente che ha autorizzato il dispositivo
authorization.expires_at (facoltativo): orario di scadenza della connessione, se impostato
status (facoltativo): stato del dispositivo, che può essere:
online: il dispositivo è online e associato * offline: il dispositivo non ha comunicato per oltre 5 minuti (se si esegue una query su questo endpoint, lo stato cambierà in online) * paused: il dispositivo è stato disabilitato temporaneamente nel pannello Connessioni C2C di Frame.io

Poiché lo stato di scadenza e pausa può cambiare in qualsiasi momento all’interno di Frame.io, conviene eseguire periodicamente il polling di queste informazioni, se vengono mostrate agli utenti. Consigliamo di limitare la frequenza del polling a non più di una volta ogni 60 secondi.

id

Annota il valore per id poiché ti servirà per la connessione websocket nella sezione successiva

Stabilire la connessione websocket

Il pannello Connessioni C2C in Frame.io mostra lo stato di connessione di ciascun dispositivo. Quando un dispositivo ha una connessione socket attiva, appare come online con un indicatore verde nell’angolo in alto a sinistra nella scheda. I dispositivi senza connessioni attive appaiono offline con una visualizzazione in grigio.

Il server termina automaticamente le connessioni socket dopo 60 secondi senza un messaggio di “heartbeat”. Sebbene questo intervallo sia sufficiente, consigliamo di inviare heartbeat ogni 15 secondi per una maggiore affidabilità. Se la connessione si chiude inaspettatamente, basta ristabilirla.

La connessione al websocket di Frame.io prevede due passaggi:

Stabilire l’handshake TCP/IP e aprire la connessione websocket fisica
Entrare nel canale specifico del dispositivo per identificare il tuo dispositivo al nostro backend

Per aprire la connessione websocket:

$ websocat -n "wss://api.frame.io/devices/websocket?Authorization=Bearer ACCESS_TOKEN"

L'intestazione Authorization

A differenza degli endpoint API standard dove il token di accesso va nell’intestazione Authorization, per le connessioni websocket è incluso come parametro di richiesta codificato nell’URL. Devi comunque includere Bearer (con uno spazio) prima del token di accesso. Nelle stringhe codificate nell’URL, gli spazi appaiono come %20, quindi questa formattazione è prevista.

Una connessione riuscita restituisce un codice di stato 101, che indica il passaggio del protocollo a wss. La libreria websocket potrebbe gestire questo automaticamente. Un token scaduto produrrà una risposta 403. Successivamente, entra nel canale del tuo dispositivo inviando questo messaggio JSON, usando l’id dalle informazioni di connessione:

1 {"topic":"devices:YOUR_DEVICE_ID", "event":"phx_join", "payload":"", "ref":"channel_connect"}

Riceverai una conferma:

1 {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"channel_connect","topic":"devices:YOUR_DEVICE_ID"}

I campi ref e payload

Il campo ref mette in correlazione le risposte con gli eventi che le hanno attivate. Poiché l’ordine degli eventi non è garantito, questo identificatore aiuta ad abbinare le risposte del server con gli eventi trigger. Frame.io non utilizza questo campo per gli eventi in arrivo: è esclusivamente per il riferimento del client. Il campo payload deve essere sempre presente, ma spesso può essere una stringa vuota (specificheremo quando un payload richiede contenuto specifico).

Controlla la dashboard C2C: il dispositivo adesso dovrebbe essere online! Consigliamo di implementare un processo in background per mantenere questa connessione:

Python

1 def heartbeat_task():
2     """
3     Task that emits heartbeats every 15 seconds.
4     """
5 
6     while True:
7         c2c.emit_socket_heartbeat()
8         sleep(15)

Il formato del messaggio heartbeat:

1 {"topic":"phoenix", "event":"heartbeat", "payload":"", "ref":"heartbeat"}

Che riceve questa risposta:

1 {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"heartbeat","topic":"phoenix"}

Con una connessione socket attiva e la sottoscrizione al canale, il dispositivo apparirà come online nel pannello Connessioni C2C di Frame.io. Se la connessione si interrompe, apparirà offline.

Visualizzazione dello stato del dispositivo

Anziché visualizzare i valori di stato raw (online, offline, paused), consigliamo di trasformarli in indicatori più significativi per l’utente:

In pausa: true/false - Mostra true se lo stato è paused, altrimenti false
Connesso: true/false - Indica se il dispositivo può raggiungere il backend di Frame.io (vedi il test di connessione backend di seguito)

Gestione dello stato di pausa

Sebbene la visualizzazione dello stato di pausa sia facoltativa, è importante comprenderne la funzione.

La funzione di pausa è progettata per bloccare temporaneamente il caricamento di contenuti sensibili. Non blocca il traffico di rete, ma impedisce che media specifici raggiungano Frame.io. È utile in situazioni come le riprese di scene contenenti materiale sensibile, dove l’archiviazione cloud immediata potrebbe essere inappropriata.

La pausa è controllata tramite l’interfaccia Frame.io, non tramite la tua integrazione. Quando un dispositivo è in pausa, solo i media creati durante il periodo di pausa vengono bloccati, mentre quelli acquisiti in precedenza rimangono idonei per il caricamento.

Considerazioni importanti:

Non fare affidamento esclusivamente sull’endpoint identity per convalidare l’idoneità al caricamento: il nostro backend lo gestisce automaticamente
Gli eventi socket segnalano le modifiche dello stato con event: "status_updated" e payload: "paused" o "resumed"
Benché gli eventi possano aiutare a gestire lo stato, potrebbero andare persi o essere consegnati non in sequenza
Ricevere un errore 409 durante il caricamento non significa necessariamente che il dispositivo sia attualmente in pausa. Potrebbe indicare che il media è stato creato durante una precedente finestra di pausa
Se visualizzi uno stato di pausa, verifica la precisione controllando periodicamente le informazioni di connessione

Verifica della connettività del backend

Per controllare la disponibilità del backend Frame.io, usa questo endpoint:

$ curl -X GET https://api.frame.io/health \
>     | python -m json.tool

Questo endpoint non richiede autorizzazione. Una risposta positiva indica la connettività:

1 {
2     "ok": true
3 }

Questa verifica dello stato è particolarmente utile in quanto conferma la connettività specifica con Frame.io, piuttosto che la disponibilità generale della rete. Potrebbero verificarsi dei casi in cui la rete funziona, ma Frame.io non è raggiungibile a causa di problemi del servizio o di instradamento.

Passaggi successivi

Ti incoraggiamo a contattare il nostro team per qualsiasi domanda, poi vai alla guida sul caricamento di base. Saremo lieti di aiutarti nel tuo percorso di implementazione. Per maggiori informazioni sulla gestione dell’autorizzazione del dispositivo, consulta la guida alla gestione delle autorizzazioni.