Guía práctica: Organizar activos

Introducción

En esta guía aprenderemos cómo y en qué medida podemos controlar dónde se cargan los activos de su integración.

¿Qué necesitaré?

Si no ha leído la guía Implementar C2C: Configuración, échele un vistazo rápido antes de continuar. También necesitará el access_token que recibió durante la guía sobre la autenticación y autorización de hardware de C2C o aplicaciones de C2C.

Estructura de carpetas de activos

De forma predeterminada, los activos se crean con la siguiente estructura de carpetas:

Cloud Devices > {YYYY}_{MM}_{DD} > {ASSET_TYPE} > {YOUR_DEVICE} > {ASSET_NAME} Donde {ASSET_TYPE} es VIDEO, AUDIO o DATA (configurado para su modelo de dispositivo por canal), {YOUR_DEVICE} es el nombre del dispositivo de proyecto conectado al proyecto del usuario, y {ASSET_NAME} es el nombre del activo que ha cargado y el activo reproducible real en Frame.io.

Enrutamiento de extensiones

Puede configurar su dispositivo para enrutar diferentes activo a carpetas {ASSET_TYPE} personalizadas basándose en una extensión de archivo en {ASSET_NAME}. Por ejemplo, digamos que su integración produce varios tipos de archivo diferentes y cada uno tiene una procedencia específica. Puede decirnos que asignemos esos activos de la siguiente manera:

.mov -> VIDEO
.mp4 -> VIDEO
.raw -> STILLS
.jpeg -> STILLS
.pdf -> CAMERA REPORTS
.las -> LiDAR Scans

Ahora cuando crea el siguiente activo:

$
{
>
curl -X POST https://api.frame.io/v2/assets \
>
    --header 'Authorization: Bearer [access_codes]' \
>
    --header 'Content-Type: application/json' \
>
    --header 'x-client-version: 2.0.0' \
>
    --data-binary @- <<'__JSON__' 
>
        {
>
            "name": "IMAGE_0001.jpeg", 
>
            "filetype": "image/jpeg", 
>
            "filesize": 21136250,
>
            "offset": 10
>
        }
>
__JSON__
>
} | python -m json.tool

… se enrutará a una ubicación como: Cloud Devices > 2022_04_01 > STILLS > MY_DEVICE > IMAGE_0001.jpeg. Si en su lugar el archivo se llamara A001_C001.mov, se enrutaría a: Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > A001_C001.mov.

Rutas de carga tokenizadas

Puede que algunas integraciones deseen tener más control sobre la estructura de carpetas que crea su dispositivo. A su vez, nosotros en Frame.io necesitamos asegurarnos de que haya cierto nivel de coherencia en cómo se cargan los archivos en Frame.io desde un dispositivo de C2C, y específicamente hacer garantías a los clientes de Frame.io sobre con qué parte de su proyecto puede interactuar un dispositivo de C2C. Para ello, permitimos a los integradores personalizar sus ubicaciones de carga de activos dentro de la carpeta {YOUR_DEVICE}, pero no permitimos que los activos se carguen fuera de esa carpeta.

Para cargar en una estructura de carpetas personalizada, tendrá que trabajar con su administrador de partners. Las estructuras de carpetas personalizadas son un conjunto de metadatos tokenizados que deben proporcionarse al crear activos. Realicemos un ejemplo sencillo:

Digamos que tenemos una estructura de cámara en 3D que tiene valores reel_name como "A001", "A002", "A003", etc., y valores clip_number como "C001", "C002", etc. Queremos crear carpetas para cada clip y rellenarlas con los archivos de los ojos izquierdo y derecho, por lo que los archivos tendrían este aspecto en un proyecto:

Para ello, necesitaremos configurar dos ajustes:

• Campos de metadatos obligatorios
• Ruta de archivo tokenizada

Los campos de metadatos obligatorios son una lista sencilla de claves que deben establecerse al crear activos para su integración:

[reel_name, clip_number]

Luego puede usar cualquiera de estas claves para crear una ruta delimitada por /, usando {field_name} para indicar dónde debe inyectarse el valor de un campo:

REEL_{reel_name}/{reel_name}_{clip_number}

Deberá proporcionar ambos ajustes a nuestro equipo en Frame.io para añadirlos como parte de los detalles de su integración. Tras configurarlos, cuando cree un activo, esos valores deberán proporcionarse en la raíz de la carga útil para que el activo se cree correctamente:

$
{
>
curl -X POST https://api.frame.io/v2/assets \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'Content-Type: application/json' \
>
    --header 'x-client-version: 2.0.0' \
>
    --data-binary @- <<'__JSON__' 
>
        {
>
            "name": "A001_C001_LEFT.mp4", 
>
            "filetype": "video/mp4", 
>
            "filesize": 21136250,
>
            "offset": 10,
>
            "metadata": {
>
              "reel_name": "A001",
>
              "clip_number": "C001"
>
            },
>
        }
>
__JSON__
>
} | python -m json.tool

El código anterior creará un archivo con una ruta completa como: Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > REEL_A001 > A001_C001 > A001_C001_LEFT.mp4

La carga útil aceptará cualquier valor JSON válido. Los valores que no son cadenas se representan de la siguiente manera:

• integers: Se representan en base-10: 10 -> "10"
• floats: Usa la representación más corta según el algoritmo descrito en “Printing Floating-Point Numbers Quickly and Accurately” en Proceedings of the SIGPLAN ‘96 Conference on Programming Language Design and Implementation.
• booleans: true y false se representan como "true" y "false"
• null: Se representa como una cadena vacía. Si reel_name se estableciera en null, la primera carpeta personalizada se representaría como REEL_

En general, sugerimos que limite sus valores a cadenas y formatee otros valores como considere adecuado (por ejemplo, los enteros siempre se imprimirán sin ceros a la izquierda, algo que tal vez desee cambiar).

Generalmente, solo deben usarse campos que tengan un valor válido para cada clip; si un campo no siempre tiene un valor válido, debe tener un plan para cómo representar valores no establecidos o nulos.

Apilar versiones

Frame.io admite pilas de versiones: una manera de agrupar varias iteraciones del mismo contenido en la interfaz de usuario. La API de C2C permite que los dispositivos carguen nuevas iteraciones de un activo que se colocarán en una pila de versiones con sus versiones anteriores. Para crear una pila de versiones, debe proporcionar un autoversion_id para identificar a qué pila de versiones pertenecen los activos. Este valor puede ser cualquier cosa: un UUID, un nombre de archivo, etc. Tenga cuidado de usar solamente valores que nunca se repitan accidentalmente en una carpeta de activos. Por ejemplo, si es posible que su integración pueda crear el mismo nombre de archivo más de una vez, entonces el nombre de archivo no es un buen candidato para usar como autoversion_id.

Proporcionamos un autoversion_id de esta forma:

$
{
>
curl -X POST https://api.frame.io/v2/assets \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'Content-Type: application/json' \
>
    --header 'x-client-version: 2.0.0' \
>
    --data-binary @- <<'__JSON__' 
>
        {
>
            "name": "A001_C001_v01.mov", 
>
            "filetype": "video/webm", 
>
            "filesize": 21136250,
>
            "offset": 10,
>
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>
        }
>
__JSON__
>
} | python -m json.tool

Ahora, cada vez que cargue un nuevo activo, si usa el mismo autoversion_id, el activo se añadirá como la última versión en una pila con el activo original:

$
{
>
curl -X POST https://api.frame.io/v2/assets \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'Content-Type: application/json' \
>
    --header 'x-client-version: 2.0.0' \
>
    --data-binary @- <<'__JSON__' 
>
        {
>
            "name": "A001_C001_v02_with_color.mov", 
>
            "filetype": "video/webm", 
>
            "filesize": 21136250,
>
            "offset": 10,
>
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>
        }
>
__JSON__
>
} | python -m json.tool

Los activos solo se apilarán si se cargan en la misma carpeta, por lo que deberá tener en cuenta un par de cosas si desea implementar pilas de versiones:

• Los metadatos tokenizados deben resolverse a la misma carpeta principal para que se cree la pila de versiones.
• Dado que la fecha de creación es parte de la ruta del archivo, puede que las nuevas versiones creadas después de la medianoche (UTC) no se apilen correctamente a menos que proporcione un desplazamiento para el tiempo de creación de la carga original.

Este segundo punto es importante. Digamos que 48 horas después de la carga inicial, se crea una nueva versión del activo. Para que se apile con el activo original, debemos proporcionar un desplazamiento de 48 horas en el pasado: 172 800 segundos.

$
{
>
curl -X POST https://api.frame.io/v2/assets \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'Content-Type: application/json' \
>
    --header 'x-client-version: 2.0.0' \
>
    --data-binary @- <<'__JSON__' 
>
        {
>
            "name": "A001_C001_v03_with_color.mov", 
>
            "filetype": "video/webm", 
>
            "filesize": 21136250,
>
            "offset": 172800,
>
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>
        }
>
__JSON__
>
} | python -m json.tool

Si el activo actual se habría cargado en la fecha 2022_04_03, ahora se cargará en la fecha 2022_04_01 y se apilará con el activo correcto.

Próximos pasos

Esta es la última guía para crear una gran integración con C2C. Tómese su tiempo para celebrarlo. A lo mejor le apetece tomarse un tentempié. Lo único que queda por hacer es revisar la lista de comprobación para integradores, donde encontrará un resumen de todo lo necesario para crear una integración a prueba de balas.

Si aún no lo ha hecho, le recomendamos que se ponga en contacto con nuestro equipo y que luego continúe con la siguiente guía. Quedamos a la espera de tener noticias suyas.