> This page is for De cámara a la nube. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Cómo realizar cargas (conceptos avanzados) ## Introducción Poder cargar activos de manera fiable es esencial en las integraciones de C2C. Esta guía ofrece técnicas avanzadas y prácticas recomendadas para crear un sistema de carga sólido, resistente y eficiente que funcione bien incluso en entornos complejos. ## Requisitos previos Si aún no lo ha hecho, revise la guía [Implementar C2C: Configuración](./implementing-c2c-setting-up) antes de continuar. Necesitará el `access_token` que se obtiene durante el [proceso de autenticación y autorización](./implementing-c2c-authentication-and-authorization). Seguiremos usando el [mismo activo de prueba](https://f.io/Rq1q5CzB) de la [guía de conceptos básicos sobre las cargas](./how-to-basic-upload). ## Parámetros avanzados de activos Al crear activos en Frame.io, puede usar varios parámetros avanzados para personalizar el comportamiento de la carga. El parámetro `offset` es especialmente importante para que la integración funcione correctamente. ### Offset: Gestión de dispositivos en pausa Es esencial proporcionar un valor preciso para `offset`. Este parámetro especifica cuándo se creó un elemento multimedia y garantiza que su dispositivo no cargue contenido que no deba compartirse. Cuando un dispositivo está en pausa en Frame.io, el usuario está indicando que los medios creados durante la pausa no deben cargarse. Para obtener más detalles, consulte nuestra [guía sobre la funcionalidad de pausa](./how-to-heartbeats-connection-info-and-status#handling-the-paused-status). ### Ventajas adicionales del parámetro offset El parámetro `offset` proporciona otra ventaja significativa para organizar medios en Frame.io. Al cargar contenido capturado en una fecha anterior, como cuando un usuario selecciona una foto realizada la semana anterior durante la reproducción, el parámetro `offset` garantiza que estos medios aparezcan en carpetas correspondientes a su fecha de captura original en lugar de la fecha de carga actual. Esta organización cronológica mantiene una línea de tiempo lógica en la estructura del proyecto de Frame.io. Sin el parámetro `offset`, los medios históricos se agruparían incorrectamente con el contenido de hoy, lo que podría confundir a los editores y otros colaboradores. Puede que desee permitir que los usuarios tengan opciones en lo que respecta a esta cuestión a través de su interfaz. Si los usuarios prefieren organizar todas las cargas por la fecha actual independientemente de cuándo se capturaron los medios, puede simplemente omitir el parámetro `offset`, ya que su valor predeterminado es `0` cuando no se especifica. Debido al diseño de nuestra API, su dispositivo no tiene que hacer un seguimiento del estado de pausa. En su lugar, al cargar un archivo, indica hace cuántos segundos se creó el archivo. Nuestro servidor compara ese valor con las ventanas de pausa y rechaza la carga si se creó durante una pausa. Para demostrar esta funcionalidad, ponga en pausa su dispositivo desde el menú de tres puntos en la pestaña Conexiones de C2C. Ahora intente cargar un activo: ```shell { 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": 0 } __JSON__ } | python -m json.tool ``` La documentación para `/v2/devices/assets` está disponible [aquí](/camera-to-cloud/api-reference/device-asset-create). Recibirá este error: ```json { "code": 409, "errors": [ { "code": 409, "detail": "The channel you're uploading from is currently paused.", "status": 409, "title": "Channel Paused" } ], "message": "Channel Paused" } ``` Si reanuda el dispositivo y vuelve a intentar realizar la misma solicitud, se creará el activo. Sin embargo, si el activo se creó durante la ventana de pausa, debe establecer el parámetro `offset` para reflejar cuándo se creó realmente: ```shell { 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": 60 } __JSON__ } | python -m json.tool ``` Esto le dice a Frame.io que el activo se creó hace 60 segundos (durante la pausa), lo que activa correctamente el error `Channel Paused`. *Definir valores precisos para `offset` es esencial* para evitar que se cargue contenido confidencial en contra de los deseos del usuario, lo que incluye propiedad intelectual protegida, metraje sensible u otro material restringido. Al volver a intentar realizar una llamada de creación de activo que ha fallado, recuerde actualizar el valor de `offset`. Durante periodos de reintento prolongados, un valor estático para offset podría salirse de la ventana de pausa relevante, lo que podría permitir cargas que deberían bloquearse. ### Cargar en un canal concreto Si su dispositivo tiene varios canales, puede especificar cuál desea usar: ```shell { 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, "channel": 2 } __JSON__ } | python -m json.tool ``` Si no se especifica ninguno, el canal predeterminado es `0`. Para la mayoría de las integraciones, no será necesario cambiar este valor. ### Solicitar un recuento de fragmentos personalizado De forma predeterminada, el backend de Frame.io divide los archivos en fragmentos de aproximadamente 25 MB. Para redes muy congestionadas, podría preferir fragmentos más pequeños. Puede solicitar un número específico de fragmentos con el parámetro `parts`: ```shell { 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": 0, "parts": 4 } __JSON__ } | python -m json.tool ``` La respuesta incluirá cuatro URL de carga: ```json { ... "upload_urls": [ "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-01-path]", "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-02-path]", "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-03-path]", "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-04-path]" ], ... } ``` El tamaño de los fragmentos será: **`Python`** ```python title="Python" math.ceiling(float(21136250) / float(4)) # 5284063 bytes ``` El último fragmento ocupará 5 284 061 bytes (calculado como `21136250 - 5284063 * 3`). Al solicitar recuentos de fragmentos personalizados, tenga en cuenta las [limitaciones de carga multiparte de AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html): * Cada parte debe ocupar al menos 5 MiB (5 242 880 bytes), excepto la parte final * No puede haber más de 10 000 partes Si su solicitud infringe estas restricciones, recibirá un mensaje `500: INTERNAL SERVER ERROR`: ``` { "code": 500, "errors": [ { "code": 500, "detail": "There was a problem with your request", "status": 500, "title": "Something went wrong" } ], "message": "Something went wrong" } ``` Asegúrese siempre de que su recuento de partes personalizado cumple los requisitos de S3. ## Realizar la carga de manera eficiente Los dispositivos de C2C suelen operar en entornos de red complejos, por lo que la eficiencia es crucial. A continuación, se muestran algunas estrategias para maximizar el rendimiento. ### Reutilizar/Agrupar las conexiones TCP Para establecer conexiones cifradas se necesita una sobrecarga de negociación significativa. Para que el funcionamiento sea eficiente, reutilice las conexiones TCP al realizar varias solicitudes. La mayoría de las bibliotecas HTTP proporcionan una abstracción de tipo `Client` o `Session` que mantiene conexiones persistentes. El proceso de negociación para una nueva conexión HTTPS incluye protocolos de enlace criptográficos y la validación de los certificados. Al reutilizar conexiones, solo realiza esta sobrecarga una vez en lugar de hacerlo para cada solicitud. Para obtener detalles técnicos sobre los procesos de protocolo de enlace TLS, consulte la [explicación de Cloudflare](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake/). Para demostrar la reutilización de conexiones con `curl`, primero cree un nuevo activo en Frame.io como se describe en la [guía de conceptos básicos sobre las cargas](/camera-to-cloud/how-to-basic-upload#step-1-creating-an-asset). A continuación, divida el archivo en fragmentos independientes para realizar pruebas: ```shell head -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 > "C2C_TEST_CLIP-Chunk01" tail -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 > "C2C_TEST_CLIP-Chunk02" ``` Ahora cargue ambos fragmentos a través de una sola conexión TCP mediante el parámetro `--next` de curl: ```shell curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-1-path] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk01 \ --next -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-2-path] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk02 ``` Compare esto con conexiones independientes: ```shell curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-1-path] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk01 \ && curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-2-path] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk02 ``` Puede cargar varias veces en la misma URL de fragmento, así que no dude en reutilizar URL para diferentes ejemplos. En las pruebas, reutilizar conexiones suele mejorar el rendimiento en un 15-20 % para las cargas secuenciales. ### Cargas paralelas Para mejorar aún más el rendimiento, cargue varios fragmentos al mismo tiempo: ```shell curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-1-path] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk01 \ & \ curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part-2-path]\ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk02 \ & ``` Con suficiente ancho de banda, las cargas paralelas se completan aproximadamente en el tiempo de la carga individual más lenta. Para disfrutar de un paralelismo óptimo, una buena regla general es realizar dos cargas simultáneas por núcleo de CPU. Superar esta proporción puede provocar que se contengan recursos y el rendimiento disminuya. Las condiciones de red afectan significativamente al rendimiento de la carga paralela. En algunos entornos, las cargas secuenciales pueden superar el rendimiento de las paralelas. Las implementaciones avanzadas pueden monitorizar el rendimiento y ajustar dinámicamente la concurrencia. Establezca siempre perfiles de rendimiento en su entorno de producción operativo en lugar de confiar en los tiempos de ejemplo. ### Combinar ambos enfoques Para maximizar la eficiencia, combine la agrupación de conexiones con las cargas paralelas. Cree varios procesos de modo que cada uno use la agrupación de conexiones para su propia secuencia de cargas: ```shell curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[asset01-chunk01] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk01 \ --next -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[asset01-chunk02] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk02 \ & \ curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[asset02-chunk01] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk01 \ --next -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[asset02-chunk02] \ --include \ --header 'content-type: video/mp4' \ --header 'x-amz-acl: private' \ --data-binary @C2C_TEST_CLIP-Chunk02 \ & ``` La mayoría de las bibliotecas HTTP proporcionan abstracciones para la agrupación de conexiones y las solicitudes paralelas. Experimente con las opciones de su biblioteca para determinar la configuración óptima para su entorno. ## Realizar un seguimiento del progreso de carga Su integración debe proporcionar indicaciones básicas de progreso a los usuarios. La granularidad en el nivel de fragmento es aceptable: para una carga de tres fragmentos, el progreso podría incrementar de 0 % → 33 % → 66 % → 100 % a medida que se complete cada fragmento. Los informes de progreso más detallados dependen de las capacidades de su biblioteca HTTP. Póngase en contacto con nuestro equipo si necesita orientación para implementar un seguimiento del progreso más detallado. ## Realizar cargas fiables Para gestionar adecuadamente los errores, revise nuestra [guía sobre los errores](/camera-to-cloud/how-to-handle-errors). En las siguientes secciones se asume que ha implementado las estrategias de gestión de errores que se describen en ese documento. Crear un cargador con calidad de producción requiere consideraciones adicionales más allá de la gestión de errores de solicitudes individuales. ### Crear una cola de carga En escenarios reales, es posible que su dispositivo genere medios más rápido de lo que puede cargarlos, o que experimente interrupciones de conexión prolongadas. Implementar un sistema de colas permite separar la creación de medios de la administración de las cargas. Plantéese una arquitectura con dos colas: 1. Una **cola de medios** para registrar archivos locales con Frame.io 2. Una **cola de fragmentos** para cargar fragmentos de archivos individuales A continuación, se muestra una implementación simplificada: **`Python`** ```python title="Python" # Where we are going to queue new files. FILE_QUEUE = Queue() # Where we are going to queue new chunks. CHUNK_QUEUE = Queue() # The http session that will handle TCP # connection pooling for us. HTTP_SESSION = http.Session() def take_picture(): """Snaps a picture for the user.""" image = MY_DEVICE.capture() file_path = MY_DEVICE.write_image(image) FILE_QUEUE.add(file_path) def task_register_assets(): """ Pulls snapped pictures from the FILE_QUEUE, registers with Frame.io, and adds the chunks to the CHUNK_QUEUE. """ while True: # Get the latest file added to the queue and register # a C2C Asset for it. new_file = FILE_QUEUE.get() asset = c2c.crete_asset_for_file(HTTP_SESSION, new_file) # Calculate the size for each chunk chunk_size = c2c.calculate_chunk_size(asset, new_file) # Create a message for each chunk with it's parameters # and add it to the # queue. chunk_start = 0 for chunk_url in asset.upload_urls: message = { "file_path": new_file, "chunk_url": chunk_url, "chunk_start": chunk_start, "chunk_size": chunk_size, } # Put the message in the queue and CHUNK_QUEUE.put(message) chunk_start += chunk_size def task_upload_chunk(): """Takes a chunks and uploads them.""" while True: info = CHUNK_QUEUE.get() c2c.upload_chunk(HTTP_SESSION, info) def launch_upload_tasks(): """Lauches our Frame.io upload tasks.""" # Create a list to hold all of our tasks. tasks = list() # Create one task for registering assets. asset_task = run_task_in_thread(task_register_assets) tasks.append(asset_task) # Create 2 tasks per CPU core for uploading chunks. for _ in range(0, GET_CPU_COUNT() * 2): chunk_task = run_task_in_thread(task_upload_chunk) tasks.append(chunk_task) # Run these tasks until shutdown run_forever(tasks) ``` En el ejemplo anterior, asumimos que las funciones invocadas para las llamadas a C2C están gestionando errores como se analiza en la [guía sobre los errores](/camera-to-cloud/how-to-handle-errors). ### Colas persistentes entre ciclos de encendido El enfoque de cola en memoria funciona bien mientras el dispositivo permanece encendido, pero ¿qué sucede si se pierde la alimentación antes de que se completen las cargas? Para crear una integración verdaderamente resistente, debemos garantizar que el dispositivo pueda continuar desde donde se quedó tras un reinicio. Esto requiere persistir el estado de la cola en el almacenamiento entre ciclos de encendido. Una base de datos integrada como [SQLite](https://www.sqlite.org/index.html) proporciona unos cimientos excelentes para esta funcionalidad. Su implementación de cola persistente debe admitir estas operaciones clave: * Añadir los nuevos archivos creados a la cola de carga * Monitorizar cuándo se crean correctamente los activos en Frame.io * Registrar cuándo falla la creación de activos debido a errores * Almacenar información de fragmentos de archivos para tareas de carga * Recuperar el próximo fragmento que se va a cargar * Marcar fragmentos como cargados correctamente * Registrar fallos en la carga de fragmentos * Proporcionar al usuario información sobre el estado de los archivos A continuación, se muestra cómo podríamos adaptar nuestro ejemplo anterior para usar un sistema de almacenamiento persistente: **`Python`** ```python title="Python" # Our persistence layer for queuing uploads, potentially using SQLite # or another embedded database C2C_UPLOAD_STORE = NewC2CUploadStore() # HTTP session for connection pooling HTTP_SESSION = http.Session() def take_picture(): """Captures an image and adds it to the upload queue.""" image = MY_DEVICE.capture() file_path = MY_DEVICE.write_image(image) # Register the file with our persistent store C2C_UPLOAD_STORE.add_file(file_path) def task_register_assets(): """ Processes files from persistent storage and registers them with Frame.io for upload. """ while True: # Get the next available file from our store file_record = C2C_UPLOAD_STORE.get_file() try: # Register the asset with Frame.io asset = c2c.create_asset_for_file(HTTP_SESSION, file_record) chunk_size = c2c.calculate_chunk_size(asset, file_record) # Create entries for each chunk in our persistent store chunk_start = 0 for chunk_url in asset.upload_urls: message = { "file_path": file_record, "chunk_url": chunk_url, "chunk_start": chunk_start, "chunk_size": chunk_size, } C2C_UPLOAD_STORE.new_chunk(message) chunk_start += chunk_size except BaseException as error: # Record the error in our persistent store C2C_UPLOAD_STORE.file_asset_create_error(file_record, error) else: # Mark the asset as successfully created C2C_UPLOAD_STORE.file_asset_created(file_record) def task_upload_chunk(): """Uploads individual file chunks from the persistent queue.""" while True: # Get the next chunk, marking it as "in progress" to prevent # other tasks from processing it simultaneously chunk_record = C2C_UPLOAD_STORE.get_chunk() try: c2c.upload_chunk(HTTP_SESSION, chunk_record) except BaseException as error: # Record the error for potential retry C2C_UPLOAD_STORE.chunk_error(chunk_record, error) else: # Mark successful completion C2C_UPLOAD_STORE.chunk_success(chunk_record) def launch_upload_tasks(): """Launches Frame.io upload processing tasks.""" tasks = [] # Asset registration task asset_task = run_task_in_thread(task_register_assets) tasks.append(asset_task) # Multiple parallel chunk upload tasks worker_count = GET_CPU_COUNT() * 2 for _ in range(worker_count): chunk_task = run_task_in_thread(task_upload_chunk) tasks.append(chunk_task) # Run indefinitely run_forever(tasks) ``` Con este enfoque de almacenamiento persistente, su integración se vuelve resistente a las interrupciones de alimentación. Cuando el dispositivo se reinicia, simplemente sigue procesando desde su último estado guardado. Esta arquitectura también proporciona la base para implementar funciones más avanzadas, como el seguimiento de errores y la detección de cargas detenidas. ### Realizar un seguimiento de los errores de carga Un sistema de carga sólido debe realizar un seguimiento cuidadoso de los errores. Tras volver a intentar una operación usando las estrategias de la [guía sobre los errores](/camera-to-cloud/how-to-handle-errors), registre estos fallos en su almacén de persistencia. Esto permite a su sistema: 1. Dar menor prioridad a las cargas problemáticas para evitar que bloqueen toda la cola 2. Proporcionar a los usuarios información precisa sobre el estado 3. Admitir intervenciones administrativas para problemas persistentes Cuando se produce un error grave, marque el elemento para evitar reintentos innecesarios. ### Administrar cargas detenidas Implemente medidas de protección contra cargas detenidas indefinidamente. Establezca una duración máxima (por ejemplo, 30 minutos) después de la cual una tarea de carga de fragmentos debe terminarse y reiniciarse. Esto evita escenarios donde todos los trabajadores de carga se bloquean debido a operaciones que no responden. ### Recuperarse de fallos silenciosos Los bloqueos del sistema, la pérdida de alimentación o la finalización de procesos pueden impedir que se informe adecuadamente de los errores. Al recuperar elementos de su cola, registre la hora de comprobación. Si un elemento permanece en el estado "in progress" más de un umbral razonable (por ejemplo, 30 minutos) sin que se informe de éxito o fallo, devuélvalo automáticamente al grupo disponible para que lo procese otro trabajador secundario. ### Mitigar las cargas envenenadas Un elemento de cola "envenenado" falla constantemente debido a problemas inherentes con los datos o el entorno. Si estos elementos se ponen continuamente en una cola, pueden acabar bloqueando efectivamente todo su sistema de carga. Considere estas estrategias para abordar tales casos: * Tras varios fallos, dar menor prioridad al elemento para que el contenido más nuevo pueda proceder * Realizar un seguimiento tanto de los errores explícitos como del número de intentos de procesar * Seguir las prácticas recomendadas de conexión y autorización para distinguir entre problemas del entorno transitorios y problemas intrínsecos del archivo * Implementar límites de reintento escalonados (por ejemplo, volver a intentar operaciones individuales 10 veces por cada uno de tres intentos del trabajo, lo que equivale a 30 intentos totales) * Proporcionar una interfaz de usuario para restablecer manualmente las cargas problemáticas cuando se resuelvan los problemas del entorno Las cargas envenenadas pueden ser el resultado de: * Datos de archivo dañados que provocan errores de E/S * Fallos irrecuperables de procesos que impiden crear informes de errores * Errores normalmente reintentables activados por condiciones subyacentes permanentes ### Volver a intentarlo después de un reinicio del sistema Antes de abandonar permanentemente las cargas problemáticas, márquelas para un último reintento después del siguiente reinicio del sistema. Esto aborda los casos en los que las cargas fallan debido a problemas temporales del estado del sistema con la memoria, los controladores o la asignación de recursos. Si una carga sigue fallando después de un reinicio limpio, puede marcarla con más confianza como permanentemente problemática. ## Limpiar la cola Recuerde quitar los archivos no disponibles de su cola. Cuando se quiten medios físicamente o se eliminen archivos, purgue las entradas correspondientes de su cola de carga para evitar errores innecesarios. *Es importante que limpie su cola de carga al conectarse a un nuevo proyecto.* Los medios en cola de un proyecto nunca deben aparecer en otro. Cuando un usuario empareja el dispositivo con un proyecto diferente, verifique si el proyecto ha cambiado y, de ser así, limpie completamente la cola existente. ## Próximos pasos Le recomendamos que se ponga en contacto con nuestro equipo si tiene alguna pregunta y a continuar con la [guía avanzada sobre las cargas](/camera-to-cloud/how-to-advanced-uploads). Esperamos poder ayudarle con el progreso de su integración.