> This page is for Camera to Cloud. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Gestion des statuts et des états ## 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](./implementing-c2c-setting-up) avant de continuer. Vous aurez besoin de l’élément `access_token` obtenu au cours du [processus d’authentification et d’autorisation](./implementing-c2c-authentication-and-authorization). 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](https://github.com/vi/websocat), un outil CLI avec des instructions d’installation complètes pour différents systèmes d’exploitation. 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 : ```shell 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. 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 : 1. établir la négociation TCP/IP et ouvrir la connexion websocket physique ; 2. rejoindre le canal spécifique de l’appareil pour identifier votre appareil sur notre backend. Pour ouvrir la connexion websocket : ```shell websocat -n "wss://api.frame.io/devices/websocket?Authorization=Bearer ACCESS_TOKEN" ``` 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 : ```json {"topic":"devices:YOUR_DEVICE_ID", "event":"phx_join", "payload":"", "ref":"channel_connect"} ``` Vous recevrez une confirmation : ```json {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"channel_connect","topic":"devices:YOUR_DEVICE_ID"} ``` 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`** ```python title="Python" def heartbeat_task(): """ Task that emits heartbeats every 15 seconds. """ while True: c2c.emit_socket_heartbeat() sleep(15) ``` Le format du message de pulsation : ```json {"topic":"phoenix", "event":"heartbeat", "payload":"", "ref":"heartbeat"} ``` Destinataire de cette réponse : ```json {"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 : ```shell 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é : ```json { "ok": true } ``` 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](/camera-to-cloud/how-to-basic-upload). 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](./how-to-authorization-management).