Architecture d’intégration

Présentation

Avant de commencer à envoyer des requêtes d’API, vous devez comprendre l’architecture de base des intégrations C2C. (Dans le prochain article, vous utiliserez le terminal. Dans ce guide, nous nous penchons sur les concepts essentiels.)

Le modèle de données simplifié pour votre intégration ressemblera à ceci :

                                   ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 01 │ -> │ Project │
┌───────────┐    ┌──────────────┐  └───────────────────┘    └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥
└───────────┘    └──────────────┘  ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 02 │ -> │ Project │
                                   └───────────────────┘    └─────────┘

Applications OAuth

Votre intégration est définie par une application OAuth, une entité enregistrée avec notre backend qui permet à vos appareils de s’autoriser avec Frame.io en utilisant OAuth 2. Votre application OAuth définit la stratégie d’autorisation pour toute votre intégration. Chaque appareil que vos utilisateurs connectent à Frame.io s’autorisera via la même application OAuth (bien que les intégrateurs disposant de plusieurs gammes d’appareils puissent vouloir une application OAuth pour chacune).

Pour les intégrations C2C, nous utilisons un flux OAuth spécialisé conçu spécifiquement pour les appareils avec des capacités d’interface utilisateur limitées.

Authentification des appareils C2C

L’API C2C est conçue pour les appareils dont les capacités d’interface utilisateur sont limitées. Ces appareils permettent à un utilisateur de les connecter à Frame.io à l’aide d’un code à 6 chiffres, que l’utilisateur saisit ensuite sur le site web Frame.io en utilisant son propre navigateur.

Les appareils reçoivent un paramètre client_secret qui doit être fourni à notre backend pour qu’un code d’autorisation à 6 chiffres soit envoyé. Cette approche simplifiée garantit une expérience d’authentification cohérente et sécurisée pour toutes les intégrations C2C.

Modèles d’appareils

Le modèle d’appareil définit le comportement de votre appareil lors de l’interaction avec le backend C2C, y compris les fonctionnalités qu’il prend en charge. Les paramètres suivants sont configurés par votre modèle d’appareil :

Les fonctionnalités prises en charge par votre appareil peuvent varier selon les versions du micrologiciel. Pour activer la rétrocompatibilité et offrir une expérience client fluide, la configuration de votre appareil est sélectionnée dynamiquement selon la version de micrologiciel détectée. Dans un avenir proche, une intégration pourra inclure plusieurs paramètres DeviceModel. Le modèle d’appareil utilisé sera déterminé en comparant la version de micrologiciel de l’appareil à l’exigence de version de micrologiciel minimum d’un modèle d’appareil spécifique.

Appareils de projet et identification

Le paramètre ProjectDevice représente chaque instance physique d’un appareil connecté à Frame.io. Un ProjectDevice s’identifie en utilisant une valeur d’identification unique appelée client_id. Cette valeur ne doit pas être partagée entre deux appareils. Il peut s’agir du numéro de série d’un appareil ou d’une chaîne aléatoire que l’appareil a générée une fois et enregistrée. Le paramètre client_id ne doit PAS être une valeur que votre appareil ne possède pas, comme l’adresse MAC d’un ordinateur.

Notre backend suit chaque appareil de projet et enregistre des informations à son sujet, comme sa version de micrologiciel actuelle.

Chaque ProjectDevice sera associé à un projet Frame.io spécifique et à une autorisation OAuth accordant à l’appareil l’accès au projet, ainsi qu’un ensemble de portées détaillant ce qu’un appareil est autorisé à faire. Pour plus d’informations sur les portées disponibles, consultez les guides détaillés sur l’implémentation de l’authentification et des autorisations. Le point d’entrée /me renvoie le paramètre ProjectDevice. Un appareil ne peut être activement lié qu’à un seul ProjectDevice à la fois, et donc à un seul projet à la fois.

Versions des micrologiciels

Votre appareil doit fournir sa version de micrologiciel actuelle avec l’en-tête HTTP x-client-version chaque fois que vous appelez un point d’entrée sur https://api.frame.io. Les guides d’API ultérieurs incluront cet en-tête dans chaque exemple. Dans certains cas, notre backend doit trier plusieurs versions de micrologiciel, et pour prendre cela en charge, nous exigeons que les valeurs soient une version sémantique valide. Il s’agit entre autres de valeurs telles que 0.1.2, 2.1.3-preview.01 et 2.1.3-preview.01+build_19770504.01.

Une erreur sera renvoyée si les valeurs de version du micrologiciel ne sont pas des versions sémantiques valides. Nous comprenons que toutes les intégrations ne suivent pas leur micrologiciel à l’aide du contrôle de version sémantique, et dans de tels cas, nous vous demandons de garder la trace d’une version sémantique à fournir à notre backend pour chaque version interne que vous créez.

En fournissant l’en-tête, différentes versions de votre micrologiciel peuvent prendre en charge différentes fonctionnalités (parfois contradictoires) dans Frame.io.

Étapes suivantes

Il est temps d’effectuer quelques appels API ! Découvrons comment s’authentifier et octroyer des autorisations avec C2C. Suivez le guide de configuration pour commencer.