Administrar pilas de versiones

Información general

Las pilas de versiones son un principio organizativo en Frame.io que permite que los activos se “apilen” verticalmente sin colocarlos en carpetas. Las versiones apiladas facilitan la navegación entre activos dentro de la IU de Frame.io y admiten la revisión en paralelo.

Actualmente, no admitimos la carga directa en una pila, por lo que la secuencia de API para administrar el flujo de trabajo básico de pila de versiones seguirá la misma secuencia que la IU de Frame.io:

1. Cargue el activo (opcional: márquelo como privado).
2. Asigne el activo a la pila.

Las pilas de versiones existentes se pueden reordenar y las versiones individuales se pueden sacar de una pila. Finalmente, las pilas de versiones se pueden eliminar sin quitar ninguno de sus activos constituyentes.

Conceptos fundamentales

Las pilas de versiones, al igual que las carpetas, son tipos especiales de activos. Puede recuperarlos con los mismos puntos finales y, según el valor de la clave type en la respuesta de la API, se pueden analizar y enrutar según corresponda. Por lo general, esto es sencillo en la práctica, pero puede presentar algunas complicaciones cuando se administran pilas a escala. La clave para trabajar con pilas de versiones es separar los cuatro escenarios más comunes:

1. Se puede añadir un activo a un activo, lo que creará una pila con un id nuevo.
2. Se puede añadir un activo a una pila existente.
3. Se puede reordenar una pila.
4. Se pueden quitar versiones individuales.

Los primeros dos escenarios utilizan la misma llamada de punto final, por lo que el único matiz real es saber si está creando una pila nueva (a partir de dos activos) o añadiendo su activo a una pila existente. Aparte de eso, las restricciones son predecibles:

1. Las pilas deben coincidir en asset_type (por ejemplo, no puede apilar una imagen en un flujo).
2. El usuario que realiza la acción debe tener permisos tanto para el activo de origen como para el activo o la pila de destino.
3. Los activos se apilan secuencialmente.
4. No se puede apilar una pila en una pila.
5. Las carpetas están totalmente descartadas.

Los dos últimos escenarios también son bastante simples, pero requieren un poco más de conocimiento sobre la pila en sí. Por ejemplo, para reordenar un activo en una pila, necesitará saber cuáles son los id de los activos que hay en cada lado de donde quiere colocar su activo de destino, y eso, por lo general, significará que ya ha recuperado toda la pila.

Ámbitos necesarios

Antes de comenzar a leer esta guía, asegúrese de tener un token que incluya los siguientes ámbitos:

Añadir activos a pilas de versiones

Paso 1: Localizar su destino

El primer paso consiste en identificar en cuál de los dos escenarios clave se encuentra: añadir un activo a otro para crear una pila, o añadir un activo a una pila para ampliar esa pila.

Si sabe que está trabajando con un activo sin versiones o ya tiene un id de pila de versiones, puede continuar con el paso 2.

Si no, la forma más fácil de determinar si un activo de destino ya forma parte de una pila es la siguiente:

1. Realice una solicitud GET a su activo de destino mediante una llamada a /v2/assets/:id.

2. Compruebe el type que se devuelve.

* Si es version_stack, el uuid que acaba de comprobar es su uuid de destino. Vaya al paso 2.

3. Si el type es file, anote el parent_id.
4. Realice una solicitud GET al elemento principal mediante el mismo punto final y compruebe su type.

Si el type del elemento principal es version_stack, use su id como su destino. Si el type es cualquier otra cosa, está trabajando con un activo normal y puede usar el identificador original como su destino.

Paso 2: Preparar su carga útil

Ahora que tiene su uuid de destino, necesita saber cuál es el uuid del activo que va a añadir a la pila.

1. Si está cargando un activo nuevo, simplemente use el id que se devuelve con la respuesta correcta cuando cree el activo.
2. Si está apilando un activo existente, debería tener el id a través del proceso descrito anteriormente.

El único parámetro de cuerpo necesario para una adición de pila de versiones es next_asset_id:

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

Paso 3: Añadir su activo de origen al destino

Ahora que tiene ambos parámetros de id de activo, ya tiene todo lo que necesita para realizar una solicitud POST a /assets/:id/version, donde :id es su activo de destino o pila de versiones, y su activo de origen (nuevo) está en la carga útil del cuerpo.

Reordenar pilas de versiones

Las pilas de versiones se basan en un concepto ordinal simple de que cada activo tiene elementos circundantes next_asset_id y prev_asset_id, donde el orden no se refiere a la numeración de versiones, sino al atributo index de cada activo. El index funciona de forma contraria a los números de versión, por lo tanto:

• La primera versión (con el número más bajo) en la pila tiene un activo prev, pero no tiene activo next.
• La versión más reciente (con el número más alto) en la pila tiene un activo next, pero no tiene activo prev.
• Todas las versiones “internas” tienen tanto un activo prev como un activo next, que son los activos con ID de versión más altos y más bajos, respectivamente.

Esto nos da tres escenarios distintos, todos los cuales dependen de la misma llamada de punto final:

Llamada:

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

Cuerpo:

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

En todos los casos, el id en la ruta de la URL será el activo que esté moviendo.

Quitar activos y eliminar pilas de versiones

Quitar activos

Cuando un activo se mueve a una pila de versiones, se convierte en elemento secundario de la propia pila. Para mover un activo fuera de una pila de versiones, lo que necesitará hacer es efectivamente volver a asignarlo como elemento principal en la carpeta que contiene la pila.

1. Realice una solicitud GET a la pila de versiones en sí mediante una llamada a /v2/assets/:id
2. Obtenga el parent_id de la pila en sí (que se convierte en su nuevo id de carpeta de destino)
3. Mueva su activo de destino a la carpeta de la siguiente manera:

Llamada:

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

Cuerpo:

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

Eliminar pilas de versiones

Eliminar una pila de versiones es extremadamente sencillo:

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

Eso es todo. Eliminar una pila devolverá todos sus activos constituyentes a la carpeta que contiene la pila.

Todo esto es técnicamente correcto: la versión singleton se cargará y reproducirá, se pueden añadir versiones nuevas y todo continuará con normalidad; pero para evitar presentar un escenario confuso para los usuarios en las aplicaciones web y otras aplicaciones de Frame.io, recomendamos eliminar las pilas singleton.

Para obtener más información sobre el punto final de la pila de versiones, consulte la documentación Activos.