Organisation des ressources
Présentation
Dans ce guide, nous allons apprendre comment et dans quelle mesure nous pouvons contrôler l’emplacement où les ressources de votre intégration sont chargées.
De quoi ai-je besoin ?
Si vous n’avez pas lu le guide Implémentation C2C : configuration, jetez-y un coup d’œil rapide avant de continuer ! Vous aurez également besoin de l’élément access_token que vous avez reçu au cours du processus d’authentification et d’autorisation du matériel C2C ou de l’application C2C.
Structure de dossier des ressources
Par défaut, les ressources sont créées avec la structure de dossier suivante :
Cloud Devices > {YYYY}_{MM}_{DD} > {ASSET_TYPE} > {YOUR_DEVICE} > {ASSET_NAME} où {ASSET_TYPE} est VIDEO, AUDIO ou DATA (configuré pour votre modèle d’appareil par canal), {YOUR_DEVICE} est le nom de l’appareil de projet connecté au projet de l’utilisateur, et {ASSET_NAME} est le nom de la ressource que vous avez chargée et qui est la ressource réellement lisible dans Frame.io.
Routage d’extension
Vous pouvez configurer votre appareil pour acheminer différentes ressources vers des dossiers {ASSET_TYPE} personnalisés en fonction d’une extension de fichier dans {ASSET_NAME}. Par exemple, supposons que votre intégration produise plusieurs types de fichiers différents, qui appartiennent chacun à une provenance spécifique. Vous pouvez nous indiquer de mapper ces ressources comme suit :
Désormais, lorsque vous créez la ressource suivante :
Spécification du point d’entrée de l’API
La documentation pour /v2/assets est disponible ici.
… elle sera acheminée vers un emplacement tel que : Cloud Devices > 2022_04_01 > STILLS > MY_DEVICE > IMAGE_0001.jpeg. Si le fichier s’appelait plutôt A001_C001.mov, il serait acheminé vers : Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > A001_C001.mov.
Chemins d’accès de chargement avec jeton
Certaines intégrations peuvent souhaiter avoir plus de contrôle sur la structure de dossiers que leur appareil crée. En retour, Frame.io doit assurer un certain niveau de cohérence dans la façon dont les fichiers sont chargés vers Frame.io depuis un appareil C2C, et en particulier garantir aux clients de Frame.io avec quelle partie de leur projet un appareil C2C peut interagir. À cette fin, nous permettons aux intégrateurs de personnaliser leurs emplacements de chargement de ressources dans le dossier {YOUR_DEVICE}, mais ne permettons pas de charger les ressources en dehors de ce dossier.
Pour charger vers une structure de dossiers personnalisée, vous devrez collaborer avec votre gestionnaire partenaire. Les structures de dossiers personnalisées sont un ensemble de métadonnées avec jeton qui doivent être fournies lors de la création d’une ressource. Prenons un exemple simple :
Supposons que nous ayons un squelette de caméra 3D qui contient des valeurs reel_name comme « A001 », « A002 », « A003 », etc. et des valeurs clip_number comme « C001 », « C002 », etc. Nous souhaitons créer des dossiers pour chaque clip et les remplir avec les fichiers d’œil gauche et droit, de sorte que les fichiers apparaîtraient ainsi dans un projet : 
Pour ce faire, nous devrons configurer deux paramètres :
- Champs de métadonnées requis
- Chemin d’accès de fichier avec jeton
Les champs de métadonnées requis constituent une liste simple de clés qui doivent être définies lors de la création de la ressource pour votre intégration :
Vous pouvez ensuite utiliser n’importe laquelle de ces clés pour créer un chemin d’accès délimité par /, en utilisant {field_name} pour indiquer où la valeur d’un champ doit être injectée :
Ces deux paramètres devront être communiqués à notre équipe Frame.io pour être ajoutés dans les détails de votre intégration. Une fois cette configuration effectuée, lorsque vous créez une ressource, ces valeurs devront être fournies à la racine de la payload pour que la création de la ressource soit réussie :
Le code ci-dessus créera un fichier avec un chemin d’accès complet tel que : Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > REEL_A001 > A001_C001 > A001_C001_LEFT.mp4.
Erreurs de métadonnées
Si votre appareil n’a pas été explicitement configuré pour autoriser ces champs, vous recevrez une erreur si vous tentez de faire le même appel. De même, si vous configurez les champs de métadonnées requis, vous DEVEZ les fournir dans la payload de création de ressource. Sinon, une erreur sera renvoyée.
La payload acceptera toute valeur JSON valide. Les valeurs qui ne sont pas des chaînes sont affichées de la manière suivante :
- entiers : rendus en base 10 :
10->"10" - flottants : utilise la représentation la plus courte selon l’algorithme décrit dans « Printing Floating-Point Numbers Quickly and Accurately » dans Proceedings of the SIGPLAN ’96 Conference on Programming Language Design and Implementation.
- booléens :
vraietfauxsont rendus comme« vrai »et« faux ». - null : rendu comme une chaîne vide. Si
reel_nameétait défini surnull, le premier dossier personnalisé serait rendu commeREEL_.
En général, nous suggérons de limiter vos valeurs à des chaînes, et de formater les autres valeurs comme vous le souhaitez (par exemple, les entiers seront toujours imprimés sans zéros de tête, ce que vous pourriez vouloir modifier).
En général, seuls les champs qui ont une valeur valide pour chaque clip doivent être utilisés ; si un champ n’a pas toujours une valeur valide, vous devriez avoir un plan pour représenter les valeurs non définies ou nulles.
Empilement des versions
Frame.io prend en charge l’empilement des versions, un moyen de regrouper plusieurs itérations du même contenu dans l’interface utilisateur. L’API C2C permet aux appareils de charger de nouvelles itérations d’une ressource qui sera placée dans un empilement de versions avec ses versions précédentes. Pour créer un empilement de versions, vous devez fournir une valeur autoversion_id pour identifier à quel empilement de versions appartiennent les ressources. Cette valeur peut être de nature variée : un UUID, un nom de fichier, etc. Veillez à n’utiliser que des valeurs qui ne seront jamais répétées involontairement dans un dossier de ressources. Par exemple, s’il est possible que votre intégration crée le même nom de fichier plusieurs fois, alors le nom de fichier n’est pas un bon candidat pour autoversion_id.
Nous fournissons une valeur autoversion_id comme ceci :
Maintenant, chaque fois que vous chargez une nouvelle ressource, si vous utilisez la même valeur autoversion_id, la ressource sera ajoutée comme dernière version dans un empilement avec la ressource d’origine :
Les ressources ne s’empileront que si elles sont chargées dans le même dossier. Vous devrez donc garder quelques points à l’esprit si vous souhaitez implémenter l’empilement des versions :
- Les métadonnées avec jeton doivent être résolues vers le même dossier parent pour que l’empilement des versions soit créé.
- Étant donné que la date de création fait partie du chemin d’accès au fichier, les nouvelles versions créées après minuit UTC peuvent ne pas s’empiler correctement, sauf si vous fournissez un décalage pour l’heure de création du chargement d’origine.
Ce deuxième point est important. Imaginons que 48 heures après le chargement initial, une nouvelle version de la ressource est créée. Pour s’empiler avec la ressource d’origine, nous devons indiquer un décalage de 48 heures dans le passé : 172 800 secondes.
Si la ressource actuelle avait été chargée vers 2022_04_03, elle sera maintenant chargée vers 2022_04_01 et s’empilera avec la bonne ressource.
Étapes suivantes
Il s’agit du dernier guide pour créer une excellente intégration C2C ! Prenez un moment pour vous féliciter et mesurer le chemin parcouru. Il ne vous reste plus qu’à consulter la liste de vérification de l’intégrateur, où vous trouverez un résumé de tout ce qui est nécessaire pour créer une intégration infaillible.
Si ce n’est pas déjà fait, nous vous encourageons à contacter notre équipe, puis à passer au guide suivant. Nous nous ferons un plaisir de répondre à vos questions.