Gérer les piles de versions

Vue d’ensemble

Les piles de versions constituent un principe organisationnel dans Frame.io qui permet aux fichiers d’être « empilés » verticalement sans être placés dans des dossiers. Les versions empilées facilitent la navigation de fichier à fichier dans l’interface utilisateur Frame.io et prennent en charge la révision côte à côte.

Nous ne prenons actuellement pas en charge le chargement direct dans une pile, donc la séquence API pour gérer le processus de pile de versions de base suivra la même séquence que l’interface utilisateur Frame.io :

1. Chargez le fichier (facultatif : marquez comme privé).
2. Attribuez le fichier à la pile.

Les piles de versions existantes peuvent être réorganisées et les versions individuelles peuvent être retirées d’une pile. Enfin, les piles de versions peuvent être supprimées sans supprimer leurs fichiers constituants.

Concepts fondamentaux

Les piles de versions — comme les dossiers — constituent des types spéciaux de fichiers. Vous pouvez les récupérer avec les mêmes points d’entrée et, selon la valeur de la clé type dans la réponse API, analyser et acheminer en conséquence. Cette approche est généralement simple en pratique, mais peut présenter quelques difficultés lors de la gestion de piles à grande échelle. La clé pour travailler avec les piles de versions consiste à séparer les quatre scénarios les plus courants :

1. Un fichier peut être ajouté à un fichier, ce qui créera une pile avec un nouvel id.
2. Un fichier peut être ajouté à une pile existante.
3. Une pile peut être réorganisée.
4. Les versions individuelles peuvent être supprimées.

Les deux premiers scénarios utilisent le même appel de point d’entrée, donc la seule vraie nuance consiste à savoir si vous créez une nouvelle pile (à partir de deux fichiers) ou si vous ajoutez votre fichier à une pile existante. Outre cela, les contraintes sont prévisibles :

1. Les piles doivent correspondre sur asset_type (par exemple, vous ne pouvez pas empiler une image sur un flux).
2. L’utilisateur agissant doit avoir des autorisations pour l’asset source et l’asset ou la pile de destination.
3. Pile d’asset de manière séquentielle.
4. Vous ne pouvez pas empiler une pile sur une pile.
5. Les dossiers sont exclus.

Ces deux derniers scénarios sont également assez simples, mais nécessitent de connaître davantage la pile elle-même. Par exemple, pour réorganiser un asset dans une pile, vous devrez connaître les identifiants des assets de chaque côté de l’endroit où vous voulez que votre asset cible atterrisse ; et cela signifie généralement que vous avez déjà récupéré la pile entière.

Portées requises

Avant de commencer ce Guide, vous devrez vous assurer que vous avez un jeton qui inclut les portées suivantes :

Ajout de ressources aux piles de version

Étape 1 : localisez votre destination

La première étape consiste à identifier lequel des deux scénarios clés s’applique à votre cas : ajouter une ressource à une autre ressource pour créer une pile, ou ajouter une ressource à une pile pour étendre cette pile.

Si vous savez que vous travaillez avec une ressource non versionnée, ou si vous avez déjà un id de pile de version, vous pouvez passer à l’étape 2.

Dans le cas contraire, le moyen le plus simple de déterminer si une ressource de destination fait déjà partie d’une pile est de :

1. Effectuer un GET sur votre ressource cible via un appel à /v2/assets/:id​

2. Vérifier le type renvoyé.

• S’il s’agit de version_stack, l’uuid que vous venez de vérifier est votre uuid de destination. Passez à l’étape 2.

3. Si le type est file, récupérez le parent_id
4. Effectuez un GET sur le gabarit via le même point d’entrée, et vérifiez son type.

Si le type du gabarit est version_stack, utilisez son id comme destination. Si le type est autre chose, vous travaillez avec une ressource normale et pouvez utiliser l’identifiant original comme destination.

```json { “trancreatedText”: [ “Étape 2 : préparez votre charge utile

Maintenant que vous avez l’uuid de votre destination, vous devez connaître l’uuid de l’asset que vous ajoutez à la pile.

1. Si vous chargez un nouvel asset, utilisez simplement l’id renvoyé avec la réponse de succès lorsque vous créez l’asset.
2. Si vous empilez un asset existant, vous devriez avoir l’id via le processus décrit ci-dessus.

Le seul paramètre de corps requis pour un ajout de pile de versions est next_asset_id :

1
{
2
    "next_asset_id": "<source-asset-id>"
3
}

Étape 3 : ajoutez votre asset source à la destination

Maintenant que vous avez les deux paramètres id d’asset, vous êtes prêt à POST vers /assets/:id/version, où le :id est votre asset de destination ou pile de versions, et votre asset source (nouveau) est dans la charge utile du corps.

Réorganisation des piles de versions

Les piles de versions reposent sur un concept ordinal simple où chaque asset a des voisins next_asset_id et prev_asset_id, où l’ordre ne fait pas référence à la numérotation des versions, mais à l’attribut index de chaque asset.L’index s’exécute à l’opposé des numéros de version, donc en conséquence :

• La première version (numérotée le plus bas) de la pile a un asset prev, mais pas d’asset next
• La version la plus récente (numérotée le plus haut) de la pile a un asset next, mais pas d’asset prev
• Toutes les versions « internes » ont à la fois un asset prev et next, qui sont les assets avec des ID de version supérieurs et inférieurs, respectivement.

Cela nous donne trois scénarios distincts, qui reposent tous sur le même appel de point d’entrée :

Appel :

PUT https://api.frame.io/v2/asset/:id/tween

Corps :

1
{
2
  "prev_asset_id": "<asset_id>",
3
  "next_asset_id": "<asset_id>"
4
}

Dans tous les cas, l’id dans le chemin d’accès URL sera l’asset que vous déplacez.

Suppression de fichiers et suppression de piles de versions

Suppression de fichiers

Lorsqu’un fichier est déplacé dans une pile de versions, il devient un enfant de la pile elle-même.Pour déplacer un fichier hors d’une pile de versions, vous devez effectivement le reparenter dans le dossier contenant la pile.

1. GET la pile de versions elle-même via un appel à /v2/assets/:id
2. Récupérez le parent_id de la pile elle-même (qui devient votre nouveau dossier cible id)
3. Déplacez votre fichier cible dans le dossier comme suit :

Appel :

POST https://api.frame.io/v2/assets/:parent_id/move

Corps :

1
{
2
    "id":"<asset_id>"
3
}

Suppression de piles de versions

La suppression d’une pile de versions est extrêmement simple :

DELETE https://api.frame.io/v2/assets/:version_stack_id/unversion

C’est tout.La suppression d’une pile renverra tous ses fichiers constitutifs dans le dossier contenant la pile.

Tout ceci est techniquement correct — la version singleton se chargera et se lira, de nouvelles versions peuvent être ajoutées, et tout continuera normalement ; mais pour éviter de présenter un scénario déroutant pour les utilisateurs dans le Web Frame.io et d’autres applications, nous recommandons de supprimer les piles singleton.

Pour plus d’informations sur le point d’entrée d’empilement de versions, veuillez consulter la documentation Fichiers.