Guía práctica: Administrar el estado y la condición

Introducción

En esta guía se explica cómo administrar el estado del dispositivo y mantener la sincronización con Frame.io. Utilizamos un protocolo websocket que permite la comunicación en tiempo real entre Frame.io y su dispositivo. Si no tiene experiencia con los websockets, esta guía le ayudará a entender su implementación para las integraciones de C2C.

Los websockets permiten a Frame.io enviar mensajes a su dispositivo y, al mantener una conexión persistente, proporcionar un canal de comunicación más eficiente que las solicitudes HTTP tradicionales.

En este guía, trataremos lo siguiente:

Abrir una conexión de socket para indicar que su dispositivo está “en línea”
Recuperar información sobre la conexión de su dispositivo
Verificar la disponibilidad del backend de Frame.io

Requisitos previos

Si aún no lo ha hecho, revise la guía Implementar C2C: Configuración antes de continuar. Necesitará el access_token que se obtiene durante el proceso de autenticación y autorización. Tenga en cuenta que los tokens caducan después de 8 horas, por lo que es posible que necesite actualizar su token o repetir el proceso de autorización. Para los ejemplos de conexión websocket de esta guía, recomendamos usar websocat, una herramienta de interfaz de línea de comandos (CLI) con instrucciones de instalación detalladas para diversos sistemas operativos.

MacOS

Instale con: brew install websocat

Recuperar información de conexión

Después de cualquier nueva autorización o actualización de token, su dispositivo debe consultar inmediatamente el punto final identity. Esto proporciona información esencial sobre su conexión:

$ 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 respuesta tendrá un aspecto parecido a este (con algunos datos abreviados):

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

Este punto final ayuda a verificar los detalles de la conexión. Su dispositivo debe mostrar esta información a los usuarios:

project.name: El nombre del proyecto conectado
authorization.creator.name: El usuario que autorizó el dispositivo
authorization.expires_at (opcional): El tiempo de caducidad de la conexión, si se ha establecido
status (opcional): El estado del dispositivo, que puede ser:
online: El dispositivo está en línea y emparejado. * offline: El dispositivo no se ha comunicado en más de 5 minutos (consultar este punto final cambiará el estado a online). * paused: El dispositivo se ha deshabilitado temporalmente en el panel Conexiones de C2C de Frame.io

Dado que los estados de caducidad y pausa pueden cambiar en cualquier momento en Frame.io, plantéese sondear esta información periódicamente si va a mostrársela a los usuarios. Recomendamos limitar la frecuencia de sondeo a no más de una vez cada 60 segundos.

id

Anote el valor de id, ya que lo necesitará para la conexión websocket en la siguiente sección

Establecer la conexión websocket

El panel Conexiones de C2C en Frame.io muestra el estado de conexión de cada dispositivo. Cuando un dispositivo tiene una conexión de socket activa, se muestra como online con un indicador verde en la esquina superior izquierda de la tarjeta. Los dispositivos sin conexiones activas se muestran con un valor offline atenuado.

El servidor termina automáticamente las conexiones de socket después de 60 segundos sin un mensaje de “señal”. Aunque este intervalo es suficiente, recomendamos enviar señales cada 15 segundos para mejorar la fiabilidad. Si la conexión se cierra inesperadamente, simplemente restablézcala.

La conexión al websocket de Frame.io implica dos pasos:

Establecer el protocolo de enlace a través de TCP/IP y abrir la conexión websocket física
Unirse al canal específico del dispositivo para identificar su dispositivo en nuestro backend

Para abrir la conexión websocket:

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

El encabezado de autorización

A diferencia de los puntos finales de API estándar donde el token de acceso va en el encabezado Authorization, para las conexiones websocket se incluye como un parámetro de consulta codificado en URL. Tenga en cuenta que sigue teniendo que incluir Bearer (con un espacio) antes de su token de acceso. En las cadenas codificadas en URL, los espacios aparecen como %20, por lo que se espera este formato.

Una conexión correcta devuelve un código de estado 101, que indica el cambio del protocolo a wss. Su biblioteca websocket puede gestionar esto automáticamente. Un token caducado producirá una respuesta 403. A continuación, únase al canal de su dispositivo enviando este mensaje JSON, con el id de la información de su conexión:

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

Recibirá una confirmación:

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

Los campos ref y payload

El campo ref correlaciona las respuestas con sus eventos iniciadores. Dado que el orden de los eventos no está garantizado, este identificador ayuda a emparejar las respuestas del servidor con los eventos activadores. Frame.io no usa este campo para los eventos entrantes: es solo para referencia del cliente. El campo payload siempre debe estar presente, pero a menudo puede ser una cadena vacía (especificaremos cuándo un campo payload necesite contenido concreto).

Consulte el panel de control de C2C: su dispositivo debería aparecer como en línea. Recomendamos implementar un proceso en segundo plano para mantener esta conexión:

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)

El formato del mensaje de señal:

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

Que recibe esta respuesta:

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

Con una conexión de socket activa y una suscripción a un canal, su dispositivo se mostrará como en línea en el panel Conexiones de C2C de Frame.io. Cuando la conexión termine, aparecerá como sin conexión.

Mostrar el estado del dispositivo

En lugar de mostrar los valores de estado tal cual (online, offline, paused), recomendamos convertirlos en indicadores que tengan más sentido para el usuario:

En pausa: true/false: Muestra true si el estado es paused, de lo contrario false
Conectado: true/false: Indica si el dispositivo puede comunicarse con el backend de Frame.io (consulte la prueba de conexión con el backend a continuación)

Administrar el estado de pausa

Aunque mostrar el estado de pausa es opcional, es importante entender cómo funciona.

La función de pausa está diseñada para bloquear temporalmente la carga de contenido sensible. No bloquea el tráfico de red, pero evita que medios concretos lleguen a Frame.io. Esto es útil en situaciones como filmar escenas que contengan material sensible donde el almacenamiento en la nube inmediato podría ser inapropiado.

La pausa se controla a través de la interfaz de Frame.io, no a través de su integración. Cuando un dispositivo está en pausa, solo se bloquean los medios creados durante el periodo de pausa: los medios capturados previamente siguen pudiendo cargarse.

Consideraciones importantes:

No confíe únicamente en el punto final de identidad para validar la elegibilidad de carga: nuestro backend gestiona esto automáticamente
Los eventos de socket le avisarán de cambios de estado con event: "status_updated" y payload: "paused" o "resumed"
Aunque los eventos pueden ayudar a administrar el estado, puede que se pierdan o se entreguen fuera de orden
Recibir un error 409 durante la carga no significa necesariamente que el dispositivo esté en pausa actualmente: puede indicar que los medios se crearon durante una ventana de pausa anterior
Si ve un estado de pausa, verifique su precisión comprobando periódicamente la información de conexión

Verificar la conectividad con el backend

Para comprobar la disponibilidad del backend de Frame.io, utilice este punto final:

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

Este punto final no requiere autorización. Una respuesta correcta indica que hay conectividad:

1 {
2     "ok": true
3 }

Este comprobador de estado es especialmente útil porque confirma la conectividad específicamente con Frame.io, en lugar de la disponibilidad general de la red. Puede haber escenarios en los que su red funcione, pero no se pueda acceder a Frame.io debido a problemas de servicio o de enrutamiento.

Próximos pasos

Le recomendamos que se ponga en contacto con nuestro equipo si tiene alguna pregunta y a continuar con la guía básica sobre las cargas. Esperamos poder ayudarle con el progreso de su integración. Para obtener más información sobre cómo administrar la autorización del dispositivo, consulte la guía sobre la administración de autorizaciones.