Comment effectuer un chargement (avancé)
Comment effectuer un chargement (avancé)
Présentation
Le chargement fiable des ressources constitue la fonction principale de toute intégration C2C. Ce guide présente des techniques avancées et des bonnes pratiques pour créer un système de chargement robuste, résilient et efficace qui fonctionne bien même dans des environnements difficiles.
Conditions préalables
Si vous ne l’avez pas encore fait, veuillez consulter le guide Implémentation C2C : configuration avant de continuer. Vous aurez besoin de l’élément access_token obtenu au cours du processus d’authentification et d’autorisation. Nous continuerons à utiliser la même ressource test que dans le guide de chargement de base.
Paramètres de ressource avancés
Lors de la création de ressources dans Frame.io, vous pouvez utiliser plusieurs paramètres avancés pour personnaliser le comportement de chargement. Le paramètre Décalage est particulièrement important pour une bonne intégration.
Décalage - Gestion des appareils suspendus
Fournir une valeur Décalage précise est essentiel. Ce paramètre indique quand un élément multimédia a été créé et garantit que l’appareil ne charge pas de contenu qui ne devrait pas être partagé. Quand un appareil est suspendu dans Frame.io, l’utilisateur indique que les médias créés pendant la pause ne doivent pas être chargés. Pour plus de détails, consultez notre guide sur la fonctionnalité de pause.
Avantages supplémentaires du paramètre Décalage
Le paramètre Décalage offre un autre avantage significatif pour organiser les médias dans Frame.io. Lors du chargement de contenu capturé à une date antérieure, par exemple, quand un utilisateur sélectionne une photo prise la semaine précédente pendant la lecture, le paramètre Décalage garantit que ce média apparaît dans les dossiers correspondant à sa date de capture originale plutôt qu’à la date de chargement actuelle. Cette organisation chronologique maintient une chronologie logique dans la structure de projet Frame.io. Sans le paramètre Décalage, les médias historiques apparaîtraient incorrectement groupés avec le contenu d’aujourd’hui, causant potentiellement de la confusion pour les éditeurs et autres utilisateurs collaborateurs. Vous pouvez souhaiter offrir aux utilisateurs un choix à ce sujet sur votre interface. Si les utilisateurs préfèrent organiser tous les chargements selon la date actuelle, indépendamment du moment où les médias ont été capturés, vous pouvez simplement omettre le paramètre Décalage, car il prend par défaut la valeur 0 quand aucune autre valeur n’est spécifiée.
Notre conception d’API élimine le besoin pour l’appareil de suivre le statut de pause. Au lieu de cela, lors du chargement d’un fichier, vous indiquez combien de secondes se sont écoulées depuis la création du fichier. Notre serveur compare cette valeur aux fenêtres de pause et rejette le chargement s’il a été créé pendant une pause.
Pour faire une démonstration de cette fonctionnalité, mettez en pause votre appareil à partir du menu à trois points dans l’onglet Connexions C2C.
Tentez maintenant de charger une ressource :
Spécification de point d’entrée de l’API
Rendez-vous sur cette page pour consulter la documentation /v2/devices/assets.
Vous recevrez cette erreur :
Si vous mettez fin à la pause de l’appareil et réessayez avec la même requête, la ressource est créée.
Cependant, si la ressource a été créée pendant la pause, vous devez définir le paramètre Décalage de manière à refléter le moment où elle a réellement été créée :
Vous indiquez ainsi à Frame.io que la ressource a été créée il y a 60 secondes (pendant la pause), ce qui déclenche correctement l’erreur Canal suspendu. Des valeurs de décalage précises sont essentielles pour empêcher le chargement de contenu sensible contre la volonté de l’utilisateur, y compris du contenu dont la propriété intellectuelle est protégée, des enregistrements sensibles ou d’autres supports soumis à des restrictions.
Décalage et nouvelles tentatives
Lors d’une nouvelle tentative d’appel de création de ressource après un échec, pensez à mettre à jour la valeur Décalage. Pendant des périodes de nouvelles tentatives prolongées, un décalage statique pourrait dériver hors de la fenêtre de pause pertinente, permettant potentiellement des chargements qui devraient être bloqués.
Chargement vers un canal spécifique
Si votre appareil inclut plusieurs canaux, vous pouvez spécifier lequel utiliser :
Si vous n’en spécifiez aucun, le canal par défaut est 0. Pour la plupart des intégrations, cette valeur n’a pas besoin d’être modifiée.
Demande d’un nombre de blocs personnalisé
Par défaut, le serveur de Frame.io divise les fichiers en blocs d’environ 25 Mo. Pour les réseaux avec une forte congestion, des blocs plus petits peuvent être plus adaptés. Vous pouvez demander un nombre spécifique de blocs avec le paramètre Parties :
La réponse inclura quatre URL de chargement :
La taille du bloc sera :
Le dernier bloc fera 5 284 061 octets (calculé comme 21 136 250 - 5 284 063 * 3). Lorsque vous demandez des nombres de blocs personnalisés, tenez compte des limitations de chargement multiparties d’AWS S3 :
- Chaque partie doit faire au moins 5 Mio (5 242 880 octets), excepté la partie finale.
- Il ne peut pas y avoir plus de 10 000 parties.
Si votre demande enfreint ces contraintes, vous recevrez une erreur 500 : ERREUR DE SERVEUR INTERNE :
Vérifiez toujours que le nombre de parties personnalisé est conforme aux exigences de S3.
Un chargement efficace
Les appareils C2C fonctionnant souvent dans des environnements réseau difficiles, l’efficacité est cruciale. Voici des stratégies pour maximiser le débit.
Réutilisation/mise en pool de connexions TCP
L’établissement de connexions chiffrées nécessite une surcharge de négociation importante. Pour un fonctionnement efficace, réutilisez les connexions TCP lors de requêtes multiples. La plupart des bibliothèques HTTP fournissent une abstraction Client ou Session qui maintient des connexions persistantes.
Le processus de négociation pour une nouvelle connexion HTTPS implique l’établissement de liaisons cryptographiques et la validation de certificats. En réutilisant les connexions, vous n’effectuez cette surcharge qu’une seule fois au lieu de le faire pour chaque requête.
Référence d’établissement de liaison TCP
Pour des détails techniques sur les processus d’établissement de liaison TLS, consultez l’explication de Cloudflare.
Pour démontrer la réutilisation de connexion avec curl, commencez par créer une nouvelle ressource dans Frame.io comme décrit dans le guide de chargement de base.
Divisez ensuite le fichier en blocs distincts pour les tests :
Chargez maintenant les deux blocs sur une seule connexion TCP en utilisant le paramètre --next de curl :
Comparez cela à des connexions distinctes :
Réutilisation d’URL de bloc
Vous pouvez effectuer plusieurs chargements vers la même URL de bloc. N’hésitez donc pas à réutiliser les URL entre les exemples.
Lors des tests, la réutilisation de connexion améliore généralement les performances de 15 à 20 % pour les chargements séquentiels.
Chargements parallèles
Pour un débit encore plus important, chargez plusieurs blocs simultanément :
Si la bande passante est suffisante, les chargements parallèles se terminent approximativement dans le temps du chargement individuel le plus lent.
Pour un parallélisme optimal, une bonne règle empirique est de deux chargements simultanés par cœur de processeur. Dépasser ce ratio peut entraîner une contention des ressources et faire diminuer l’efficacité.
Vitesses de chargement parallèle
Les conditions réseau affectent considérablement les performances de chargement parallèle. Dans certains environnements, les chargements séquentiels peuvent surpasser les parallèles. Les implémentations avancées peuvent surveiller le débit et ajuster dynamiquement la simultanéité. Analysez toujours les performances dans l’environnement de production réel plutôt que de vous fier aux exemples.
Association des deux approches
Pour une efficacité maximale, combinez le regroupement de connexions avec les chargements parallèles. Créez plusieurs processus, chacun utilisant le regroupement de connexions pour sa propre séquence de chargements :
Fonctionnalités de bibliothèque HTTP
La plupart des bibliothèques HTTP fournissent des abstractions pour le regroupement de connexions et les requêtes parallèles. Testez les options de votre bibliothèque pour déterminer la configuration optimale pour votre environnement.
Suivi de la progression du chargement
Votre intégration doit fournir une indication de progression de base aux utilisateurs. Une certaine granularité au niveau des blocs est acceptable. Pour un chargement de trois blocs, la progression peut s’incrémenter de 0 % → 33 % → 66 % → 100 % à mesure que chaque bloc se termine.
Le reporting de progression plus précis dépend des capacités de votre bibliothèque HTTP. Contactez notre équipe si vous avez besoin d’aide pour implémenter un suivi de progression plus détaillé.
Chargement fiable
Pour une bonne gestion des erreurs, consultez notre guide des erreurs. Les sections suivantes supposent que vous avez implémenté les stratégies de gestion d’erreur qui y sont décrites.
Créer un système de chargement de qualité production nécessite des considérations supplémentaires au-delà de la gestion des erreurs de requête individuelles.
Création d’une file d’attente de chargement
Dans les scénarios réels, votre appareil peut générer des médias plus rapidement qu’il ne peut les charger, ou il peut subir des interruptions de connexion prolongées. L’implémentation d’un système de file d’attente sépare la création de médias de la gestion du chargement.
Envisagez une architecture à deux files d’attente :
- Une file d’attente de médias pour enregistrer les fichiers locaux avec Frame.io
- Une file d’attente de blocs pour charger les blocs de fichiers individuels
Voici une implémentation simplifiée :
Gestion des erreurs
Dans l’exemple ci-dessus, nous supposons que les fonctions invoquées pour les appels c2c gèrent les erreurs comme décrit dans le guide des erreurs.
File d’attente persistante entre les cycles d’alimentation
L’approche avec une file d’attente en mémoire fonctionne bien tant que l’appareil reste sous tension, mais que se passe-t-il si l’alimentation est perdue avant la fin des chargements ? Pour créer une intégration véritablement résiliente, nous devons nous assurer que l’appareil peut reprendre là où il s’était arrêté après un redémarrage.
Cela nécessite de conserver l’état de la file d’attente dans le stockage entre les cycles d’alimentation. Une base de données intégrée telle que SQLite fournit une excellente base pour cette fonctionnalité.
Votre implémentation de file d’attente persistante doit prendre en charge ces opérations clés :
- Ajout des fichiers nouvellement créés à la file d’attente de chargement
- Suivi de la création des ressources dans Frame.io
- Enregistrement des échecs de création de ressources en raison d’erreurs
- Stockage des informations de blocs de fichiers pour les tâches de chargement
- Récupération du bloc suivant à charger
- Marquage des blocs comme chargés avec succès
- Enregistrement des échecs de chargement de blocs
- Fourniture des informations de statut de fichier pour l’affichage utilisateur
Voici comment nous pourrions adapter notre exemple précédent pour utiliser un système de stockage persistant :
Avec cette approche de stockage persistant, votre intégration devient résiliente en cas d’interruption d’alimentation. Lorsque l’appareil redémarre, il continue simplement le traitement à partir de son dernier état enregistré. Cette architecture fournit également la base pour mettre en œuvre des fonctionnalités plus avancées, comme le suivi des erreurs et la détection des chargements bloqués.
Suivi des erreurs de chargement
Un système de chargement solide doit suivre attentivement les erreurs. Après avoir retenté une opération en utilisant les stratégies du guide des erreurs, enregistrez ces échecs dans votre stockage persistant. Cela permet à votre système de :
- déprioriser les chargements problématiques pour les empêcher de bloquer toute la file d’attente ;
- fournir des informations de statut précises aux utilisateurs ;
- mettre en place une intervention administrative pour les problèmes persistants.
Lorsqu’une erreur fatale se produit, marquez l’élément pour éviter de nouvelles tentatives inutiles.
Gestion des chargements bloqués
Mettez en œuvre des garde-fous contre les chargements bloqués indéfiniment. Définissez une durée maximale (par exemple, 30 minutes) après laquelle une tâche de chargement de bloc doit être interrompue et redémarrée. Cela évite les scénarios où tous les systèmes de chargement sont bloqués par des opérations qui ne répondent pas.
Récupération après des échecs silencieux
Les plantages système, les pannes de courant ou l’arrêt de processus peuvent empêcher le signalement normal des erreurs. Lors de la récupération d’éléments de votre file d’attente, enregistrez l’heure de retrait. Si un élément reste dans l’état « en cours » au-delà d’un seuil raisonnable (par exemple, 30 minutes) sans signaler de succès ou d’échec, renvoyez-le automatiquement dans le pool disponible pour traitement par un autre système.
Atténuation des chargements corrompus
Un élément de file d’attente corrompu échoue constamment en raison de problèmes inhérents aux données ou à l’environnement. Si ces éléments se remettent continuellement en file d’attente, ils peuvent effectivement bloquer tout votre système de chargement. Envisagez d’utiliser ces stratégies pour gérer de tels cas :
- Après plusieurs échecs, dépriorisez l’élément pour que le traitement du nouveau contenu puisse continuer.
- Suivez à la fois les erreurs explicites et le nombre de tentatives de traitement.
- Suivez les bonnes pratiques de connexion et d’autorisation pour faire la distinction entre les problèmes environnementaux transitoires et les problèmes de fichiers intrinsèques.
- Implémentez des limites de nouvelle tentative croissantes (par exemple, relancez les opérations individuelles 10 fois dans chacune des 3 tentatives de tâche, pour un total de 30 tentatives).
- Fournissez une interface utilisateur pour réinitialiser manuellement les chargements problématiques une fois les problèmes environnementaux résolus.
Les chargements corrompus peuvent résulter des éléments suivants :
- Des données de fichier corrompues provoquant des erreurs d’E/S
- Des pannes de processus catastrophiques qui empêchent la création de rapports d’erreur
- Des erreurs pouvant normalement donner lieu à une nouvelle tentative déclenchées par des conditions sous-jacentes permanentes
Nouvelle tentative après redémarrage du système
Avant d’abandonner définitivement les chargements problématiques, signalez-les pour une dernière tentative après le prochain redémarrage du système. Cela concerne les cas où les chargements échouent en raison de problèmes d’état temporaire du système avec la mémoire, les pilotes ou l’attribution des ressources. Si un chargement continue d’échouer après un redémarrage propre, vous pouvez le marquer avec plus de confiance comme définitivement problématique.
Vidange de la file d’attente
N’oubliez pas de supprimer les fichiers non disponibles de la file d’attente. Lorsque les médias sont physiquement supprimés ou que les fichiers sont supprimés, purgez les entrées correspondantes de la file d’attente de chargement pour éviter les erreurs inutiles.
Il est important de vider la file d’attente de chargement lors de la connexion à un nouveau projet. Les médias en file d’attente pour un projet ne doivent jamais apparaître dans un autre. Lorsqu’un utilisateur associe l’appareil à un autre projet, vérifiez si le projet a changé et, si c’est le cas, videz complètement la file d’attente existante.
Étapes suivantes
Nous vous encourageons à contacter l’équipe pour toute question et à consulter le guide de chargement avancé. Nous nous ferons un plaisir de vous aider à faire avancer votre intégration.