Gestion des statuts et des états | Frame.io API Documentation

Présentation

Ce guide explique comment gérer le statut de l’appareil et maintenir la synchronisation avec Frame.io. Nous utilisons un protocole websocket qui permet la communication en temps réel entre Frame.io et votre appareil. Si vous ne connaissez pas les websockets, ce guide vous aidera à comprendre leur implémentation pour les intégrations C2C.

Les websockets permettent à Frame.io d’envoyer des messages à votre appareil et, en maintenant une connexion persistante, offrent un canal de communication plus efficace que les requêtes HTTP traditionnelles.

Dans ce guide, nous allons traiter des sujets suivants :

Ouverture d’une connexion socket pour indiquer que votre appareil est « en ligne »
Récupération d’informations sur la connexion de votre appareil
Vérification de la disponibilité du backend Frame.io

Conditions préalables

Si vous ne l’avez pas encore fait, veuillez consulter le guide Implémentation C2C : configuration avant de continuer. Vous aurez besoin de l’élément access_token obtenu au cours du processus d’authentification et d’autorisation. Sachez que les jetons expirent au bout de 8 heures. Vous devrez donc peut-être actualiser votre jeton ou recommencer le processus d’autorisation. Pour les exemples de connexion websocket de ce guide, nous recommandons d’utiliser websocat, un outil CLI avec des instructions d’installation complètes pour différents systèmes d’exploitation.

MacOS

Installez avec : brew install websocat

Récupération des informations de connexion

Après toute nouvelle autorisation ou actualisation de jeton, votre appareil doit immédiatement interroger le point d’entrée identity. Cela fournit des informations essentielles sur votre connexion :

$ 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 réponse ressemble à ceci (avec certaines données abrégées) :

{
    "_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",
    ...
}

Ce point d’entrée aide à vérifier les détails de connexion. L’appareil doit présenter ces informations aux utilisateurs :

project.name : nom du projet connecté.
authorization.creator.name : utilisateur qui a autorisé l’appareil.
authorization.expires_at (facultatif) : heure d’expiration de la connexion, si définie.
statut (facultatif) : statut de l’appareil, qui peut être :
en ligne : l’appareil est en ligne et couplé * hors ligne : l’appareil n’a pas communiqué depuis plus de 5 minutes (l’interrogation de ce point d’entrée changera le statut en en ligne) * suspendu : l’appareil a été temporairement désactivé dans le volet Connexions C2C de Frame.io.

Étant donné que l’expiration et le statut de pause peuvent changer à tout moment dans Frame.io, envisagez d’interroger périodiquement ces informations si vous les affichez pour les utilisateurs. Nous recommandons de limiter la fréquence d’enquête à une fois toutes les 60 secondes maximum.

id

Notez la valeur id, car vous en aurez besoin pour la connexion websocket dans la section suivante.

Établissement de la connexion WebSocket

Le panneau Connexions C2C de Frame.io affiche le statut de connexion de chaque appareil. Lorsqu’un appareil a une connexion socket active, il s’affiche comme en ligne avec un indicateur vert dans le coin supérieur gauche de la carte. Les appareils sans connexion active apparaissent hors ligne avec un affichage grisé.

Le serveur met automatiquement fin aux connexions socket après 60 secondes sans message de pulsation. Bien que cet intervalle soit suffisant, nous recommandons d’envoyer des pulsations toutes les 15 secondes pour des questions de fiabilité. Si la connexion se ferme de manière inattendue, rétablissez-la.

Se connecter au websocket de Frame.io implique deux étapes :

établir la négociation TCP/IP et ouvrir la connexion websocket physique ;
rejoindre le canal spécifique de l’appareil pour identifier votre appareil sur notre backend.

Pour ouvrir la connexion websocket :

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

L’en-tête d’autorisation

Contrairement aux points d’entrée API standard où le jeton d’accès va dans l’en-tête Authorization, pour les connexions websocket, il est inclus comme paramètre de requête encodé en URL. Notez que vous devez toujours inclure Bearer (avec l’espace) avant votre jeton d’accès. Dans les chaînes encodées en URL, les espaces apparaissent comme %20, donc ce formatage est attendu.

Une connexion réussie renvoie un code d’état 101, indiquant le remplacement du protocole par wss. Votre bibliothèque websocket peut gérer cela automatiquement. Un jeton expiré produira une réponse 403. Rejoignez ensuite le canal de votre appareil en envoyant ce message JSON, en utilisant l’id de vos informations de connexion :

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

Vous recevrez une confirmation :

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

Les champs ref et payload

Le champ ref met en corrélation les réponses avec les événements qui les ont initiées. Étant donné que l’ordre des événements n’est pas garanti, cet identifiant aide à associer les réponses du serveur aux événements déclencheurs. Frame.io n’utilise pas ce champ pour les événements entrants : il sert uniquement de référence pour le client. Le champ payload doit toujours être présent, mais peut souvent être une chaîne vide (nous préciserons quand une payload nécessite un contenu spécifique).

Vérifiez le tableau de bord C2C : votre appareil devrait maintenant apparaître en ligne ! Nous recommandons d’implémenter un processus en arrière-plan pour maintenir cette connexion :

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)

Le format du message de pulsation :

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

Destinataire de cette réponse :

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

Avec une connexion socket active et un abonnement au canal, votre appareil s’affichera comme en ligne dans le panneau Connexions C2C de Frame.io. Lorsque la connexion prend fin, il apparaît hors ligne.

Affichage du statut de l’appareil

Plutôt que d’afficher les valeurs de statut brutes (en ligne, hors ligne, suspendu), nous recommandons de les traduire en indicateurs plus significatifs pour l’utilisateur :

Suspendu : vrai/faux ; affiche vrai si le statut est suspendu, et faux autrement.
Connecté : vrai/faux ; indique si l’appareil peut atteindre le backend Frame.io (voir les tests de connexion backend ci-dessous)

Gestion du statut de pause

Bien que l’affichage du statut de pause soit facultatif, il est important de comprendre son utilité.

La fonctionnalité de pause est conçue pour bloquer temporairement le chargement de contenu sensible. Elle ne bloque pas le trafic réseau, mais empêche des médias spécifiques d’atteindre Frame.io. Cette fonctionnalité est utile dans des situations comme le tournage de scènes contenant des éléments sensibles où le stockage immédiat dans le cloud pourrait être inapproprié.

La suspension est contrôlée via l’interface Frame.io, et non via votre intégration. Lorsqu’un appareil est suspendu, seuls les médias créés pendant la période de pause sont bloqués : les médias capturés précédemment peuvent toujours être chargés.

Considérations importantes :

Ne vous fiez pas uniquement au point d’entrée d’identité pour valider l’éligibilité de chargement : notre backend gère cela automatiquement.
Les événements de socket vous informeront des changements de statut avec event: "status_updated" et payload: "paused" ou "resumed"
Bien que les événements puissent aider à gérer le statut, ils peuvent être manqués ou fournis dans le désordre.
Recevoir une erreur 409 lors du chargement ne signifie pas nécessairement que l’appareil est actuellement suspendu : cela peut indiquer que le média a été créé pendant une pause précédente.
Si vous affichez un statut suspendu, vérifiez sa précision en contrôlant périodiquement les informations de connexion.

Vérification de la connectivité backend

Pour vérifier la disponibilité du backend Frame.io, utilisez ce point d’entrée :

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

Ce point d’entrée ne nécessite aucune autorisation. Une réponse réussie indique la connectivité :

1 {
2     "ok": true
3 }

Cette vérification d’état est particulièrement utile, car elle confirme la connectivité spécifiquement avec Frame.io, plutôt que la disponibilité générale du réseau. Dans certains cas, votre réseau peut fonctionner, mais Frame.io est inaccessible en raison de problèmes de service ou de routage.

Étapes suivantes

Nous vous encourageons à contacter l’équipe pour toute question et à consulter le guide de chargement de base. Nous nous ferons un plaisir de vous aider à faire avancer votre intégration. Pour plus d’informations sur la gestion des autorisations des appareils, consultez le guide de gestion des autorisations.