Arquitectura de la integración
Arquitectura de la integración
Introducción
Antes de empezar a realizar solicitudes a la API, debe entender la arquitectura básica de las integraciones de C2C. No se preocupe, en el siguiente artículo trabajará en el terminal. Por ahora, tratemos estos conceptos esenciales.
El modelo de datos simplificado para su integración tendrá un aspecto similar a este:
Aplicaciones de OAuth
Su integración está definida por una aplicación de OAuth, una entidad registrada con nuestro backend que permite que sus dispositivos se autoricen con Frame.io mediante OAuth 2. Su aplicación de OAuth define la estrategia de autorización para toda su integración. Cada dispositivo que sus usuarios conecten a Frame.io se autorizará a través de la misma aplicación de OAuth (aunque puede que los integradores con varias líneas de dispositivos quieran una aplicación de OAuth para cada una).
Para las integraciones de C2C, usamos un flujo de OAuth especializado diseñado específicamente para dispositivos con capacidades de interfaz de usuario limitadas.
Autenticación de dispositivos de C2C
La API de C2C se ha diseñado para dispositivos con capacidades de interfaz de usuario limitadas. Estos dispositivos permiten que un usuario los conecte a Frame.io mostrando un código de 6 dígitos, que luego el usuario introduce en el sitio web de Frame.io usando su propio navegador.
A los dispositivos se les emite un client_secret que debe proporcionarse a nuestro backend para recibir un código de autorización de 6 dígitos. Este enfoque optimizado garantiza una experiencia de autenticación coherente y segura en todas las integraciones de C2C.
Modelos de dispositivo
El modelo de dispositivo configura cómo se comporta su dispositivo al interactuar con el backend de C2C, lo que incluye qué funciones admite. Los siguientes ajustes se configuran según su modelo de dispositivo:
Si la integración usará sockets de baja latencia para comunicar su estado actual, o llamadas REST de mayor latencia.
El nombre de su integración como debería aparecer en la ruta de cualquier activo cargado.
C2C solo permite cargar activos a rutas de archivos raíz específicas, pero por debajo de ese requisito su dispositivo se puede configurar para cargar activos en una ruta de archivo calculada dinámicamente basada en los metadatos suministrados del activo.
Qué metadatos serán obligatorios al cargar un activo en Frame.io, especialmente para admitir la ruta de archivo tokenizada.
Si la integración usará sockets de baja latencia para comunicar su estado actual, o llamadas REST de mayor latencia.
Las funciones que admite su dispositivo pueden cambiar según la versión de firmware. Para habilitar la compatibilidad con versiones anteriores y ofrecer una experiencia de usuario limpia, la configuración de su dispositivo se selecciona dinámicamente según la versión de firmware detectada. En un futuro cercano, una integración podrá tener más de un DeviceModel. El modelo de dispositivo que se usará se determinará comparando la versión de firmware del dispositivo con el requisito de versión mínima de firmware de un modelo de dispositivo concreto.
Dispositivos de proyecto e identificación
El ProjectDevice representa cada instancia física de un dispositivo conectado a Frame.io. Un ProjectDevice se identifica usando un valor de identificación único llamado client_id. Este valor debe ser algo que esté garantizado que no se comparta entre dos dispositivos. Puede ser el número de serie de un dispositivo o una cadena aleatoria que el dispositivo genera una vez y guarda. El client_id NO debe ser un valor que su dispositivo no posea, como la dirección MAC de un ordenador.
Nuestro backend realiza un seguimiento de cada dispositivo de proyecto y guarda información sobre él, como su versión de firmware actual.
Cada ProjectDevice tendrá un Project específico de Frame.io asociado a él y una OauthAuthorization que permite que el dispositivo acceda al proyecto y un conjunto de ámbitos que detallan lo que tiene permitido hacer un dispositivo. Para obtener más información sobre los ámbitos disponibles, consulte las guías detalladas sobre cómo implementar la autenticación y autorización. El ProjectDevice es lo que devuelve el punto final /me. Un Device solo puede estar vinculado activamente a un único ProjectDevice a la vez, y por lo tanto, a un único Project a la vez.
Versiones de firmware
Su dispositivo debe suministrar su versión de firmware actual con el encabezado HTTP x-client-version siempre que llame a un punto final en https://api.frame.io. Las guías posteriores sobre la API incluirán este encabezado en cada ejemplo. En algunos casos, nuestro backend debe ordenar varias versiones de firmware, y para que pueda hacerlo, los valores DEBEN ser una versión semántica válida. Esto incluye valores como 0.1.2, 2.1.3-preview.01 y 2.1.3-preview.01+build_19770504.01, entre otros.
Se devolverá un error si los valores de la versión de firmware no son versiones semánticas válidas. Entendemos que no todas las integraciones realizan un seguimiento de su firmware mediante versiones semánticas y, en esos casos, le pedimos que mantenga un registro de una versión semántica que proporcionar a nuestro backend para cada versión interna que cree.
Al proporcionar el encabezado, diferentes versiones de su firmware pueden admitir funciones diferentes (y a veces conflictivas) en Frame.io.
Host de encabezado
La versión de firmware solo se gestiona mediante llamadas a https://api.frame.io; al realizar llamadas a https://applications.frame.io, el encabezado no se aplica.
Requisito actual
x-client-version es ahora un encabezado HTTP obligatorio y se aplicará en los servidores de Frame.
Próximos pasos
Ha llegado el momento de realizar algunas llamadas API. Aprendamos cómo autenticar y autorizar con C2C. Siga la guía de configuración para empezar.