Lecture de l'arborescence de fichiers

Aperçu

Que l’objectif final soit la publication, la modification ou la transmission de ressources via une étape de processus, de nombreuses intégrations approfondies avec Frame.io impliquent de répertorier le contexte utilisateur et, finalement, une vue de répertoire.

Voici la hiérarchie de base des ressources (ou fichiers) dans Frame.io :

Compte > Équipe > Projet > Ressources

Cet article explique comment interagir avec l’arborescence de fichiers en effectuant des appels API séquentiels. Une stratégie courante pour travailler avec les fichiers consiste d’abord à accéder à un projet, à répertorier les dossiers, puis à travailler avec les ressources et les piles de versions qu’ils contiennent.

Concepts importants

Chaque projet possède une ressource racine unique

Les API RESTful décrivent généralement les ressources à l’aide d’identifiants uniques ; le root_asset_id est l’identifiant unique de l’arborescence de ressources de votre projet. Traitez-le comme une construction spéciale agissant comme le nœud racine d’un projet : les ressources restantes s’empilent sous la racine dans une arborescence descendante. <img alt=“root-asset-id” src=“file:docs/pages/v2/images/root-asset-id.jpg”>

Dans les processus courants, les utilisateurs d’API doivent descendre dans l’arborescence pour interagir avec les ressources plus profondes dans la hiérarchie de fichiers.

Collaborateurs et projets partagés

Un collaborateur est un rôle d’utilisateur clé dans Frame.io : ces utilisateurs ont accès à un Workspace de projet mais peuvent ne pas appartenir au compte principal de ce projet. Outre les autorisations distinctes pour les collaborateurs et membres de l’équipe, la principale différence est qu’un abonnement de collaborateur est strictement lié à un projet et peut n’avoir aucune relation avec une équipe.

Cela crée une petite complication pour les processus où les listes de répertoires sont primordiales. Bien que la hiérarchie de base ci-dessus (Compte > Équipe > Projet > Ressources) devrait fonctionner pour la majorité des cas d’usage, elle ne décrira pas les projets où un utilisateur authentifié est un collaborateur, mais pas un membre de l’équipe. Pour contourner cela lors de la liste des répertoires, vous pouvez soit :

• Récupérer les projets partagés d’un utilisateur, décompresser la hiérarchie d’équipe et de compte, et tout assembler, ou
• Récupérer les projets partagés d’un utilisateur et les répertorier tous ensemble comme un contexte séparé.

L’une ou l’autre méthode convient ; la dernière est un peu plus facile, mais la première est plus proche de la façon dont l’appli web de Frame.io présente des informations similaires. Dans tous les cas, les méthodes couvertes dans ce Guide s’appliquent aux deux.

Affichage d’un répertoire

1. Récupérer les comptes de l’utilisateur

GET https://api.frame.io/v2/accounts

Effectuez l’appel ci-dessus avec un jeton de porteur valide pour obtenir les comptes d’un utilisateur. Vous recevrez chaque compte sur lequel l’utilisateur a le statut de membre de l’équipe, de gestionnaire d’équipe ou d’administrateur. Vous pouvez également recevoir des équipes pour lesquelles un utilisateur a des droits de facturation/administrateur, mais pas d’accès à l’équipe, mais cela est rare et sera éliminé à l’étape suivante.

La charge utile pour la demande de comptes est assez détaillée, voici un résumé des données importantes que vous pourriez vouloir extraire de la réponse :

• id
• display_name
• owner (email, name)
• (facultativement) image

Notez que id et owner.email sont les seuls champs obligatoires d’un compte utilisateur. Si vous affichez des utilisateurs dans une autre application, envisagez d’écrire une logique conditionnelle pour présenter les comptes utilisateur. Nous recommandons de vérifier et, si la valeur n’est pas null, d’afficher le compte selon l’ordre de préférence suivant :

1. “display_name”
2. « Compte de owner.name »
3. « Compte de owner.email »

Une fois que votre utilisateur choisit un compte, vous voudrez probablement présenter les équipes, ce qui nécessite une requête API supplémentaire.

2. Récupérer les équipes dans le compte

GET https://api.frame.io/v2/accounts/{{account_id}}/teams Les équipes dans Frame.io peuvent être « publiques » (c’est-à-dire découvrables par tout membre de l’équipe dans le compte) ou « privées » (découvrables uniquement par des membres spécifiques de l’équipe). L’API gère le contexte pour vous, il vous suffit donc d’effectuer un appel valide en spécifiant account_id dans la requête ci-dessus.

Vous pouvez trouver plus d’informations sur la pagination en lisant Pagination and Errors. Pour chaque équipe, récupérez les attributs suivants :

• id
• name
• (facultativement) team_image

Lorsqu’une équipe est sélectionnée, vous voulez afficher ses projets constitutifs.

Note : si vous le souhaitez, vous pouvez également GET https://api.frame.io/v2/teams pour un utilisateur, et notre API retournera chaque équipe à laquelle appartient un utilisateur, quel que soit le contexte du compte. Bien que cela fonctionne techniquement, vous courez le risque de perdre votre contexte à moins de prendre une autre mesure pour :

1. Rétablir le contexte en reflétant le nom du compte à côté de chaque équipe
2. Permettre à votre utilisateur de rechercher dans le texte de la liste

Si vous listez les projets partagés depuis le niveau du compte vers le bas, vous voudrez faire un appel supplémentaire à GET https://api.frame.io/v2/projects/shared. Chaque projet retourné dans la réponse contiendra les attributs suivants, que vous pouvez reporter lors de la création de votre répertoire :

• id (du projet lui-même)
• team_id
• team.account_id

Alternativement, vous pouvez créer une possibilité pour les « Projets partagés » simplement en l’ajoutant comme une « Équipe » sur tout contexte de compte choisi. Si vous choisissez de le faire, il est utile pour l’utilisateur final de séparer visuellement les projets partagés des vrais projets à portée d’équipe, car la liste unique de projets partagés peut inclure de nombreux contextes de compte et d’équipe différents sous le capot.

3. Récupérer les projets de l’équipe

GET https://api.frame.io/v2/teams/{{team_id}}/projects

Ensuite, effectuez l’appel ci-dessus et récupérez tous les projets au sein de l’équipe.

Pour chaque projet, vous voulez récupérer :

• id
• name
• root_asset_id
• (facultativement) private, au cas où vous souhaiteriez différencier pour l’utilisateur dans votre interface d’utilisation

Comme expliqué au début de l’article, root_asset_id est un élément important de l’architecture des ressources de Frame.io, car il vous permet de naviguer dans le répertoire de fichiers et de dossiers au sein d’un Projet.

| * Compte

| * Équipe

| * Team Projects (et root_asset_ids)

| * Projets partagés (et root_asset_ids)

| Et c’est tout ce dont nous avons besoin pour créer ou récupérer des ressources.

Liste des dossiers et des ressources

4. Créer la structure de dossiers initiale

GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder Ceci listera tous les dossiers d’un projet, en commençant par le root_asset_id. S’il n’y a aucun dossier, vous obtiendrez une liste vide. Si vous souhaitez inclure à la fois les fichiers et les dossiers (par exemple, si votre étape suivante consiste à GET une ressource depuis Frame.io, omettez simplement le paramètre de chaîne de requête.

Les deux autres options de filtre disponibles pour le paramètre type sont file et version_stack. Les trois filtres s’excluent mutuellement, et un appel non filtré renverra les trois types mélangés.

5. Parcourir l’arborescence de répertoire

Pour chaque dossier qui revient, vous devrez capturer :

• id
• name

Comme chaque dossier est une ressource, votre processus pour parcourir une structure de dossiers ressemblera à ceci :

1. GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder

2. Affichez les noms de dossiers dans une liste

3. Lorsqu’un utilisateur clique sur un dossier, transmettez l’id du dossier dans la requête suivante :

4. GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder

6. Créer et charger

Dans un dossier : POST https://api.frame.io/v2/{{folder_id}}/children Une fois que vous avez l’identifiant du dossier dans lequel vous souhaitez effectuer le chargement, effectuez simplement un POST vers ses enfants, selon la documentation de la ressource et le Guide. Ceci créera un espace réservé de ressource et (selon la méthode que vous choisissez), renverra :

• Un uuid destiné aux cas d’usage de suivi
• Une liste d’upload_urls que vous pouvez utiliser pour placer votre fichier directement dans le stockage de données backend de Frame.io.

Dans une pile de versions : Les piles de versions présentent un processus similaire, avec une étape supplémentaire couverte dans ce Guide, résumée ci-dessous. Les éléments clés à retenir sont qu’une pile de versions est un conteneur qui ressemble à une ressource, mais se comporte comme un dossier ; et que vous devez d’abord charger votre ressource, puis l’empiler dans votre pile de versions en tant qu’actions séparées. Par conséquent, si vous souhaitez charger une ressource dans une pile de versions, vous aurez besoin de :

• L’id de la pile de versions
• Le parent_id de la pile de versions (par ex. son dossier conteneur ou la racine du Projet)

D’abord, POST https://api.frame.io/v2/assets/{{parent_id}}/children pour créer votre nouvelle ressource. Capturez le nouvel id dans votre réponse. Maintenant, vous pouvez utiliser l’identifiant de votre nouvelle ressource et POST https://api.frame.io/v2/assets/{{version_stack_id}}/version, avec une charge utile de corps de :

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