Cómo realizar cargas (conceptos básicos)

Introducción

Hemos llegado a un punto emocionante en nuestro proceso de integración: cargar activos en Frame.io. En esta guía se explica el proceso básico de carga.

Requisitos previos

Si aún no lo ha hecho, revise la guía Implementar C2C: Configuración antes de continuar. Necesitará el access_token que se obtiene durante el proceso de autenticación y autorización. Para esta guía, usaremos un activo de muestra disponible en este enlace de Frame.io. Descargue este archivo para seguir nuestros ejemplos, ya que le permitirá hacer coincidir los valores de nuestros comandos de muestra.

Paso 1: Crear un activo

Carguemos nuestro archivo de muestra, que asumiremos que se creó hace 10 segundos. Primero, debemos crear una referencia de activo en Frame.io:

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

Examinemos los parámetros de la carga útil JSON:

name: El nombre del activo que se muestra en Frame.io. No es necesario que coincida con el nombre del archivo en el disco. filetype: El tipo MIME del archivo. La mayoría de los lenguajes de programación proporcionan utilidades para detectar los tipos MIME (ejemplos: Go, Python). filesize: El tamaño del archivo en bytes. Nuestro archivo de muestra ocupa aproximadamente 21,1 MB. offset: El número de segundos transcurridos desde la creación del archivo. El valor predeterminado es 0 si se omite. Es necesario proporcionar este parámetro, ya que ayuda a determinar si los archivos deben rechazarse si el dispositivo se pone en pausa. Trataremos esto con más detalle en la guía avanzada sobre las cargas.

La respuesta tendrá un aspecto similar a este (con algunos campos omitidos):

1
{
2
    "_type": "file",
3
    ...
4
    "id": "9a280f99-8f4f-46b0-a4b4-ec4c2f95138e",
5
    ...
6
    "upload_urls": [
7
        "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path]",
8
        "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path]"
9
    ],
10
    ...
11
}

Llegados a este punto, solo hemos informado a Frame.io de nuestra intención de cargar un archivo; no se han transferido datos de archivo reales. Si revisa la carpeta del dispositivo en su proyecto, verá un marcador de posición del activo en el estado “uploading”.

El campo upload_urls contiene las URL en las que cargaremos nuestros fragmentos de archivo. Para nuestro archivo de prueba, deberíamos recibir dos URL de carga.

Paso 2: Dividir el archivo en fragmentos

La respuesta contenía varias URL de carga. Al cargar en Frame.io, dividimos los archivos en fragmentos y los cargamos por separado, lo que ofrece varias ventajas:

• Más fiabilidad: Si un fragmento falla, no hace falta reiniciar toda la carga
• Cargas más rápidas: Podemos cargar varios fragmentos en paralelo (se trata en la guía sobre las cargas avanzadas)

Para determinar el tamaño óptimo de los fragmentos, use esta fórmula:

1
# We use math.ceil() to ensure we get the upper bound in the division
2
chunk_size = math.ceil(float(file.size) / float(len(response.upload_urls)))

Para nuestro archivo de muestra, el cálculo es:

1
math.ceil(21136250 / 2)
2
# 10568125

Esto significa que cada fragmento debe ocupar 10 568 125 bytes. Los tamaños de fragmento suelen rondar los 25 MB, y puede obtener información sobre los cálculos exactos en la guía avanzada sobre las cargas.

Para esta demostración, usaremos los comandos head y tail para extraer los fragmentos de archivo.

Paso 3: Cargar los fragmentos

Para cargar el primer fragmento:

$
head -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 | \
>
curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path] \
>
        --include \
>
        --header 'content-type: video/mp4' \
>
        --header 'x-amz-acl: private' \
>
        --data-binary @-

La solicitud necesita estos encabezados:

content-type: El mismo valor del tipo MIME utilizado al crear el activo x-amz-acl: Para los permisos de AWS S3, se debe establecer siempre en private

Una carga correcta devuelve:

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
...

De manera similar, cargue el segundo fragmento:

$
tail -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 | \
>
curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path] \
>
        --include \
>
        --header 'content-type: video/mp4' \
>
        --header 'x-amz-acl: private' \
>
        --data-binary @-

Cuando ambas cargas se hayan completado, su activo debería poder reproducirse en Frame.io. 🎉

Unión de todos los pasos

A continuación, se muestra un ejemplo de pseudocódigo simplificado similar a Python para el proceso de carga completo:

1
file = open("~/Downloads/C2C_TEST_CLIP.mp4")
2
mimetype = mimetypes.for_file("~/Downloads/C2C_TEST_CLIP.mp4")[0]
3
created_at = time.ctime(file.stat.ST_CTIME)
4
5
asset = c2c.asset_create(
6
    name="C2C_TEST_CLIP.mp4", 
7
    filetype=mimetype, 
8
    filesize=file.size,
9
    offset=datetime.now() - created_at,
10
    channel=0,
11
)
12
13
chunk_size = math.ceil(float(file.size) / float(len(asset.upload_urls)))
14
15
for chunk_url in asset.upload_urls:
16
   chunk = file.read(bytes=chunk_size)
17
   c2c.upload_chunk(chunk, chunk_url, mimetype)

Este ejemplo demuestra el flujo básico sin gestión de errores o cargas paralelas, aspectos que se tratarán en la guía sobre la gestión de errores y la guía avanzada sobre las cargas.

Próximos pasos

Enhorabuena por cargar correctamente su primer activo en Frame.io. La guía avanzada sobre las cargas tratará los requisitos y las técnicas más sofisticados para preparar las implementaciones para producción. Le recomendamos que se ponga en contacto con nuestro equipo si tiene alguna pregunta y a continuar con la guía sobre las cargas en tiempo real para obtener más información sobre cómo cargar activos mientras se están creando.