Leer el árbol de archivos

Información general

Independientemente de si el objetivo final es la publicación, la edición o el envío de activos a través de una fase del flujo de trabajo, muchas integraciones más profundas con Frame.io implicarán enumerar el contexto del usuario y, en última instancia, una vista de directorio.

Esta es la jerarquía básica de recursos (o archivos) dentro de Frame.io:

Cuenta > Equipo > Proyecto > Activos

En este artículo se explica cómo interactuar con el árbol de archivos mediante llamadas API secuenciales. Una estrategia común para trabajar con archivos es acceder primero a un proyecto, enumerar las carpetas y luego trabajar con los activos y las pilas de versiones que contienen.

Conceptos importantes

Cada proyecto tiene un activo raíz único

Las API RESTful normalmente describen recursos mediante el uso de identificadores únicos; el root_asset_id es el identificador único para el árbol de activos de su proyecto. Trátelo como una estructura especial que actúa como el nodo raíz de un proyecto: los activos restantes se apilan debajo de la raíz en un árbol descendente. <img alt=“root-asset-id” src=“file:docs/pages/v2/images/root-asset-id.jpg”>

En flujos de trabajo comunes, los usuarios de la API necesitan descender por el árbol para interactuar con activos más profundos en la jerarquía de archivos.

Colaboradores y proyectos compartidos

Un usuario colaborador es una función clave de usuario en Frame.io: estos usuarios tienen acceso al workspace de un proyecto, pero es posible que no pertenezcan a la cuenta general de ese proyecto. Dejando de lado los permisos distintos para usuarios colaboradores e integrantes del equipo, la principal diferencia es que el abono de un usuario colaborador es estrictamente a un proyecto y puede no tener relación con un equipo.

Esto crea una pequeña complicación para flujos de trabajo donde las listas de directorios son fundamentales. Aunque la jerarquía básica anterior (Cuenta > Equipo > Proyecto > Activos) debería funcionar para la mayoría de casos de uso, no describirá los proyectos en los que un usuario autenticado es un usuario colaborador, pero no un integrante del equipo. Para evitar este problema al enumerar directorios, puede hacer lo siguiente:

• Recuperar los proyectos compartidos de un usuario, desempaquetar la jerarquía de equipo y cuenta, y unirlo todo
• Recuperar los proyectos compartidos de un usuario y enumerarlos todos juntos como un contexto separado

Ambos métodos funcionan bien; el último es un poco más fácil, pero el primero se acerca más a cómo la aplicación web de Frame.io presenta información similar. En cualquier caso, los métodos que se tratan en esta guía se aplican a ambos.

Enumerar un directorio

1. Recuperar las cuentas del usuario

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

Realice la llamada anterior con un token de portador válido para obtener las cuentas de un usuario. Recibirá cada cuenta en la que el usuario tenga el estado de integrante del equipo, responsable de equipo o administrador. También puede recibir equipos para los que un usuario tenga derechos de facturación/administrador, pero no acceso al equipo, aunque esto es poco frecuente y se solucionará en el siguiente paso.

La carga útil de la solicitud de cuentas es bastante detallada. A continuación, se muestra un resumen de los datos importantes que puede obtener de la respuesta:

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

Tenga en cuenta que id y owner.email son los únicos campos obligatorios en una cuenta de usuario. Si está mostrando usuarios en otra aplicación, plantéese la posibilidad de escribir lógica condicional para presentar las cuentas de usuario. Nuestra recomendación es comprobarlo y, si no es null, mostrar la cuenta con el siguiente orden de preferencia:

1. “display_name”
2. Cuenta de “owner.name”
3. Cuenta de “owner.email”

Una vez que su usuario elija una cuenta, lo más probable es que quiera presentar los equipos, lo que requiere una solicitud de API adicional.

2. Recuperar equipos dentro de la cuenta

La solicitud GET https://api.frame.io/v2/accounts/{{account_id}}/teams para los equipos en Frame.io puede ser “pública” (es decir, detectable para cualquier integrante del equipo en la cuenta) o “privada” (detectable solo para miembros específicos del equipo). La API gestionará el contexto por usted, por lo que todo lo que necesita hacer es realizar una llamada válida especificando el account_id en la solicitud anterior.

Puede encontrar más información sobre la paginación en Paginación y errores. De cada equipo, obtenga los siguientes atributos:

• id
• name
• (Opcionalmente) team_image

Cuando se selecciona un equipo, lo ideal es mostrar sus proyectos constitutivos.

Nota: Si lo desea, también puede realizar una solicitud GET https://api.frame.io/v2/teams para un usuario, y nuestra API devolverá cada equipo al que pertenece un usuario, independientemente del contexto de la cuenta. Aunque esto funciona técnicamente, corre el riesgo de perder su contexto a menos que siga otro paso para:

1. Reestablecer el contexto reflejando el nombre de la cuenta junto a cada equipo
2. Permitir que su usuario busque el texto de la lista

Si está enumerando proyectos compartidos desde el nivel de cuenta hacia abajo, lo ideal es hacer una llamada adicional a GET https://api.frame.io/v2/projects/shared. Cada proyecto que se devuelve en la respuesta contendrá los siguientes atributos, que puede transferir al generar su directorio:

• id (del proyecto mismo)
• team_id
• team.account_id

También puede hacer una prestación para “Proyectos compartidos” simplemente añadiéndola como un “Equipo” en cualquier contexto de cuenta elegido. Si elige hacer eso, es útil para el usuario final si separa visualmente los proyectos compartidos de los proyectos con verdadero ámbito de equipo, ya que la lista única de proyectos compartidos puede incluir muchos contextos diferentes de cuenta y equipo verdaderos.

3. Recuperar los proyectos del equipo

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

Después, realice la llamada anterior y obtenga todos los proyectos que hay dentro del equipo.

Para cada proyecto, lo ideal es obtener:

• id
• name
• root_asset_id
• (opcionalmente) private, en caso de que quiera diferenciar para el usuario en su IU

Como se ha explicado al comienzo del artículo, root_asset_id es una parte importante de la arquitectura de recursos de Frame.io, en el sentido de que le permite desplazarse por el directorio de archivos y carpetas dentro de un proyecto.

| * Cuenta

| * Equipo

| * Proyectos del equipo (y root_asset_ids)

| * Proyectos compartidos (y root_asset_ids)

| Y eso es todo lo que necesitamos para crear o recuperar activos.

Enumerar carpetas y activos

4. Generar la estructura inicial de carpetas

Realice la solicitud GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder. Esto enumerará todas las carpetas que hay en un proyecto, comenzando desde el root_asset_id. Si no hay carpetas, obtendrá una lista vacía. Si desea incluir tanto archivos como carpetas (por ejemplo, si su siguiente paso sería realizar una solicitud GET a un activo desde Frame.io, simplemente omita el parámetro de cadena de consulta.

Las otras dos opciones de filtro disponibles para el parámetro de tipo son file y version_stack. Los tres filtros son mutuamente excluyentes, y una llamada sin filtrar devolverá los tres tipos mezclados.

5. Navegar por el árbol de directorio

Para cada carpeta que se devuelve, necesitará capturar:

• id
• name

Como cada carpeta es un activo, su flujo de trabajo para navegar por una estructura de carpetas tendrá este aspecto:

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

1. Procesar los nombres de las carpetas en una lista

2. Cuando un usuario haga clic en una carpeta, pase el id de la carpeta a la siguiente consulta:

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

6. Crear y cargar

En una carpeta: Realice la solicitud POST https://api.frame.io/v2/{{folder_id}}/children. Una vez que tenga el id de la carpeta en la que le gustaría cargar, simplemente realice una solicitud POST a sus elementos secundarios, según la documentación del recurso y la guía. Esto creará un activo de marcador de posición, y (en función del método que elija), devolverá:

• Un uuid destinado para casos de uso de seguimiento
• Una lista de upload_urls que se puede usar para realizar una solicitud PUT de su archivo directamente en el almacenamiento de datos backend de Frame.io.

En una pila de versiones: Las pilas de versiones presentan un flujo de trabajo similar, con un paso adicional cubierto en esta guía, que se resume a continuación. Las claves son recordar que una pila de versiones es un contenedor que tiene un aspecto similar al de un activo, pero se comporta como una carpeta; luego, que tiene que cargar su activo primero y luego apilarlo en su pila de versiones como acciones separadas. Por lo tanto, si quiere cargar un activo en una pila de versiones, necesitará:

• El id de la pila de versiones
• El parent_id de la pila de versiones (por ejemplo, su carpeta contenedora o raíz del proyecto)

Primero, realice la solicitud POST https://api.frame.io/v2/assets/{{parent_id}}/children para crear su activo nuevo. Capture el id nuevo en su respuesta. Ahora, puede usar el id de su activo nuevo y la solicitud POST https://api.frame.io/v2/assets/{{version_stack_id}}/version, con una carga útil del cuerpo de:

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