> This page is for Plataforma, version V4 experimental. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Heredado: https://next.developer.frame.io/platform/v2/llms.txt > 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. # Acciones personalizadas Las Actions de Frame.io proporcionan acceso rápido a operaciones multimedia habituales, como descargar, cambiar el nombre y duplicar elementos, y también permiten mostrar integraciones con herramientas y servicios de terceros directamente en la interfaz de usuario de [Frame.io](https://next.frame.io/). ## Acerca de Actions Con la introducción de Custom Actions, los desarrolladores pueden configurar y gestionar sus propias Actions en Frame.io V4. Al aprovechar el mismo sistema de eventos subyacente que los [Webhooks](https://developer.adobe.com/frameio/guides/Webhooks/), Custom Actions ofrece a los desarrolladores un mecanismo alternativo para conectar sus activos con las herramientas más importantes para los usuarios de su cuenta de Frame.io. Cualquier usuario que sea Member del Workspace de Frame.io donde esté activada la Action puede ejecutarla. Al ejecutar una Action, Frame.io envía una carga útil a la URL que proporcione. La aplicación receptora responde con un código de estado HTTP para confirmar la recepción, o con una devolución de llamada personalizada para representar campos de formulario adicionales en la IU de Frame.io. La aplicación receptora puede ser un programa o servicio alojado propio, o incluso una herramienta IPaaS de bajo código o sin código, como Workfront Fusion o Zapier. Use Custom Actions para crear integraciones directamente en [Frame.io](https://next.frame.io/) como componentes de IU programables. Esto permite crear flujos de trabajo que los usuarios pueden activar desde la aplicación, aprovechando el mismo enrutamiento de eventos subyacente que los webhooks. Puede crear formularios de uno o varios pasos activados por el usuario que vuelven a Frame.io como otro formulario o como una respuesta básica. Y, cuando un usuario hace clic en una Custom Action en un Asset, Frame.io envía una carga útil a la URL que proporcione. La aplicación receptora responde con un código de estado HTTP para confirmar la recepción, o responde con una devolución de llamada personalizada que puede representar IU adicional en Frame.io. ## Mejoras de Actions en V4 A partir de lo aprendido con los usuarios de la versión heredada, hemos incluido varias mejoras en el conjunto de funciones de Actions en Frame.io V4: #### Nuevos tipos de campo Antes, se limitaban a campos de texto y de selección única. Ahora también se admiten campos de selección múltiple área de texto para cuadros de texto más grandes y booleanos para botones de opción. #### Vínculos en los que se puede hacer clic Los campos de texto no facilitan que los usuarios copien y peguen URL. Use el nuevo campo de vínculo para ofrecer una experiencia sencilla de copia con un solo clic. #### Modales dinámicos Según la cantidad de datos devueltos, el modal de la Action se redimensionará de forma dinámica para adaptarse mejor a la información del formulario, incluidos modales desplazables cuando sea necesario. #### Acciones con varios activos Configure la Action para dirigirse a un máximo de 100 Assets en una sola solicitud. \ NUEVO #### Tipos de Assets mixtos Las Actions no se limitan a un solo tipo de Asset: se pueden activar en una combinación de Files, Folders y Version Stacks. #### [Formulario de comentarios en la aplicación](https://next.frame.io/settings/actions) Queremos conocer la opinión de desarrolladores y usuarios sobre cómo usan Actions, por lo que hemos incluido un formulario de comentarios en la página de configuración de web. ## Actions migradas Hay algunos aspectos que se deben tener en cuenta al migrar a una Account de Frame.io V4 que contenga Custom Actions creadas anteriormente en la versión heredada de Frame.io. ### Estado de Action Tras la migración de una Account a Frame.io V4, todas las Custom Actions creadas en versiones anteriores tendrán el estado null y se desactivarán automáticamente. Esto permite a los usuarios actualizar primero las Actions para usar la API V4 antes de activarlas, ya que cualquier Action que no se haya actualizado fallará. Para identificar las Actions en este estado, visite la página Actions Settings y consulte la columna Status. Si usa la API, compruebe el campo is\_active. ### Recursos procesables: Files, Folders y Version Stacks Dado que los tipos de Asset se han separado como recursos independientes en la API V4 de Frame.io, es posible que deba tener en cuenta ciertos comportamientos al interpretar el ID de recurso recibido en la carga útil de la Action. El comportamiento de los Files individuales es sencillo, ya que el ID reflejará el File específico en el que se ha ejecutado la Action. Lo mismo ocurre con Folders: recibirá el ID del Folder en el que se ha ejecutado la Action. Sin embargo, según el caso de uso, tiene varias opciones al definir el comportamiento de la Action. Use este ID para realizar llamadas posteriores a la API de Frame.io si desea interactuar con este recurso. Como alternativa, puede obtener los elementos secundarios de ese Folder para seguir procesando los activos que contiene. Cuando se ejecuta una acción en un Version Stack, la carga útil contiene el ID del Head Asset, que es el File situado en la parte superior del Stack y el que se muestra en la IU de Frame.io. Puede obtener más información sobre las diferencias entre la API heredada de Frame.io y V4 en nuestra [Guía de migración](/docs/resources/migration). > **Info** > > Configure [Custom Actions](/api-reference/custom-actions/actions-show) con la API. Una Custom Action requiere lo siguiente: | Nombre del campo | Descripción | | ---------------- | ----------------------------------------------------------------------------------------------------------- | | Name | Nombre que elija para la Custom Action. Se mostrará en el menú de Custom Actions disponibles en Frame.io. | | Description | Explique qué hace la Action como referencia (la descripción no aparecerá en la aplicación web de Frame.io). | | Event | Clave de evento interno para ayudarle a diferenciar entre eventos de webhook estándar y los suyos propios. | | URL | Lugar donde se entregarán los eventos. | | Workspace | Workspace que usará la Custom Action. | ## Configuración de la Custom Action Cuando un usuario activa una Custom Action, Frame.io envía una carga útil a la URL que proporcione. La aplicación receptora puede responder con un código de estado HTTP para confirmar la recepción, o con una devolución de llamada personalizada que representa IU adicional en [Frame.io](https://next.frame.io/). > **Warning** > > Se requieren permisos de Account Admin para crear Custom Actions para un Workspace. Solicite al Admin que modifique sus permisos si no tiene acceso. ### Configuración de varios activos La compatibilidad con varios Assets se controla mediante la configuración y debe activarse explícitamente desde el modal de configuración de la Action [en web](https://next.frame.io/settings/actions). Esto se puede hacer al crear una Action nueva o al actualizar una existente. Cuando la compatibilidad con varios Assets está activada, el formato de la carga útil cambia inmediatamente. Las cargas útiles heredadas y las compatibles con varios Assets son mutuamente excluyentes. ## Carga útil de Frame.io Cuando el usuario hace clic en la Custom Action, se envía una carga útil a la URL definida en el campo URL. Use esta carga útil para identificar lo siguiente: #### Contexto de Action * En qué Custom Action se ha hecho clic * En qué recurso(s) se ha hecho clic * Qué usuario ha realizado la acción * Qué tipo de evento se ha activado #### Contexto de organización * Qué Account está asociada a la Custom Action * Qué Workspace está asociado a la Custom Action * Qué Project contiene los recursos #### Carga útil: compatibilidad con Assets individuales o varios Assets Originalmente, las Custom Actions solo aceptaban un Asset por solicitud mediante un objeto `resource` que contenía un Asset. Con la compatibilidad con varios Assets activada, la carga útil usa una lista `resources` de uno o varios Assets, con un máximo de 100 Assets en una solicitud. ```json POST /your/url { "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504", "action_id": "0aeb9feb-f8eb-4100-a8c2-b39b66d354ab", "data": { "description": "Pretty cool video.", "title": "Hey there!" }, "interaction_id": "985559de-865a-40e5-a687-2bbed4497eaa", "project": { "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea" }, "resources": [ { "id": "fe41c5a8-1b8d-417d-a7df-0b88bc19b476", "type": "file" }, { "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39", "type": "file" } ], "type": "some.event", "user": { "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935" }, "workspace": { "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f" } } ``` #### Carga útil heredada: solo compatibilidad con un Asset individual ```json POST /your/url { "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504", "action_id": "0e38b93a-9f10-4bc7-90bc-bd07a16e510a", "data": { "description": "Wow look at this.", "title": "Hey there!!" }, "interaction_id": "dff6d369-7150-41f9-8e6f-4f0895f6b416", "project": { "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea" }, "resource": { "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39", "type": "file" }, "type": "some.event", "user": { "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935" }, "workspace": { "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f" } } ``` ### Migración desde la carga útil heredada > **Carga útil heredada programada para desuso** > > La carga útil heredada está planificada para quedar en desuso, por lo que se recomienda encarecidamente a los usuarios que migren sus servicios para procesar la nueva carga útil. > > Al activar el indicador de configuración y actualizar la gestión de la carga útil, una Action puede pasar sin problemas a admitir una carga útil con varios Assets. > > 1. Sustituya el uso del objeto `resource` singular por la lista `resources`. Actualice el código para iterar por la lista `resources` > > 2. Active el indicador Multi-Asset en la configuración de Actions | Nombre del campo | Descripción | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | ID único de la Account de la Action. | | `action_id` | ID único de la Action. | | `interaction_id` | Identificador único generado por Frame.io que se usa para realizar el seguimiento de la transacción en varias solicitudes, como Message Callbacks o Form Callbacks encadenadas. Permanece igual durante toda la secuencia de la Action. | | `project_id` | ID único del Project de la Action. | | `resource.id` | ID del recurso desde el que se ha activado la Action. | | `resource.type` | Tipo de recurso desde el que se ha activado la Action. | | `type` | Nombre proporcionado en el campo `event` al configurar la Action. | | `user.id` | ID del usuario que ha activado la Action. | | `workspace.id` | ID del Workspace que usa la Action. | | `data` | Pares clave-valor que contienen los nombres de los campos de formulario y los valores seleccionados por el usuario. La aplicación recibe esta información para saber qué opciones se han elegido. | ## Interacciones, reintentos y tiempos de espera `interaction_id` es un identificador único que permite realizar el seguimiento de la interacción a medida que evoluciona con el tiempo. Si no necesita responder al usuario, devuelva un código de estado 200 y habrá terminado. Aunque es opcional, recomendamos incluir información sobre el resultado de la acción, como un mensaje de confirmación o una alerta de error. Las Custom Actions admiten Message Callbacks. > **Note** > > Frame.io espera una respuesta en menos de 10 segundos y vuelve a intentarlo hasta 5 veces mientras espera una respuesta correcta. Lo ideal es que la respuesta sea inmediata y que las acciones asíncronas se produzcan después de un activador mediante una Custom Action. ## Creación de un Message Callback En la respuesta HTTP al evento de webhook, puede devolver un objeto JSON que describa un mensaje que se devolverá al usuario que inició la acción en la IU de Frame.io. ```json { "title": "Success!", "description": "The thing worked! Nice." } ``` Los mensajes permiten proporcionar comentarios al usuario directamente en la IU de Frame.io. Si necesita recopilar información adicional del usuario, use **Form Callbacks**. ## Creación de un Form Callback Supongamos que necesita más información antes de iniciar el proceso. Por ejemplo, puede que vaya a cargar contenido en un sistema que requiere detalles adicionales. Puede describir un Form en la respuesta, que el usuario rellena y le envía de vuelta. Este es un ejemplo: ```json { "title": "Need some more info!", "description": "Getting ready to submit this file!", "fields": [ { "type": "text", "label": "Title", "name": "title", "value": "MyVideo.mp4" }, { "type": "select", "label": "Captions", "name": "captions", "options": [ { "name": "Off", "value": "off" }, { "name": "On", "value": "on" } ] } ] } ``` Cuando el usuario envía el formulario, recibirá un evento en la misma URL que el POST inicial: ```json POST /your/url { "type": "your-specified-event-name", "interaction_id": "the-same-id-as-before", "action_id": "unique-id-for-this-custom-action", "data":{ "title": "MyVideo.mp4", "captions": "off" } } ``` Todos los campos personalizados añadidos a un formulario aparecen en la sección `data` de la carga útil JSON enviada por Frame.io. Use `interaction_id` para asignar la solicitud inicial y estos nuevos datos de formulario. Puede responder con un mensaje o encadenar otro formulario. Al encadenar Actions, Forms y Messages, puede programar eficazmente flujos de trabajo de varios pasos en Frame.io con lógica empresarial de un sistema externo. ## Detalles del formulario Al igual que los mensajes, los Forms admiten los atributos `title` y `description`, que se representan en la parte superior del Form. Además, cada campo de formulario acepta los siguientes atributos base: #### Propiedades de campo * **type**: Indica a la IU de Frame.io qué tipo de datos debe esperar, así como qué componente debe representar. \* **label**: Aparece en la IU como encabezado sobre el campo. #### Datos de campo * **name**: Clave con la que se identificará el campo en la carga útil posterior. \* **value**: Valor con el que se rellenará previamente el campo. ## Tipos de campo admitidos ### Campo de texto Campo de texto simple sin parámetros adicionales. ```json { "type": "text", "label": "Title", "name": "title", "value": "MyVideo.mp4" } ``` ### Área de texto Área de texto simple sin parámetros adicionales. ```json { "type": "textarea", "label": "Description", "name": "description", "value": "This video is really, really popular." } ``` ### Lista de selección Define una lista de selección entre la que puede elegir el usuario. Debe incluir una lista `options` y cada uno de sus miembros debe incluir un `name` legible por una persona y un `value` que pueda analizar una máquina. ```json { "type": "select", "label": "Captions", "name": "captions", "value": "off", "options": [ { "name": "Off", "value": "off" }, { "name": "On", "value": "on" } ] } ``` ### Casilla Casilla simple sin parámetros adicionales. ```json { "type": "boolean", "name": "enabled", "label": "Enabled", "value": "false" } ``` ### Vínculo Vínculo simple sin parámetros adicionales. ```json { "type": "link", "name": "videoLink", "label": "Video Link", "value": "https://www.youtube.com/watch?v=XtX1zv9CEVc" } ``` ## Modelo de permisos de Frame.io Custom Actions tiene un modelo de permisos especial: pertenecen a un Workspace, no a un usuario específico que exista en una Account. Esto significa lo siguiente: #### Creación y gestión * Cualquier Admin puede crear una Custom Action en un Workspace. * Cualquier Admin puede modificar o eliminar una Custom Action que exista en un Team. #### Actualizaciones en directo * Una vez modificada, todos los usuarios verán inmediatamente el resultado del cambio. ## Seguridad y verificación De forma predeterminada, todas las Custom Actions tienen una clave de firma que se genera durante su creación. Esta clave no se puede configurar. Puede usarse para verificar que la solicitud procede de Frame.io. La solicitud `POST` incluye lo siguiente: | Nombre | Descripción | | ----------------------------- | ----------------------------------------------------- | | `X-Frameio-Request-Timestamp` | Hora a la que se ha activado la acción personalizada. | | `X-Frameio-Signature` | Firma calculada. | #### Verificación de marca de tiempo **La marca de tiempo** indica la hora a la que se firmó la solicitud al salir de la red de Frame.io. Puede usarse para evitar ataques de reproducción. Recomendamos verificar que esta hora esté dentro de un intervalo de 5 minutos con respecto a la hora local. #### Verificación de la firma **La firma** es un hash HMAC SHA-256 que usa la clave de firma proporcionada al crear la Custom Action por primera vez. ### Verificación de la firma #### Extracción de la firma Extraiga la firma de los encabezados HTTP. #### Creación del mensaje que se va a firmar Cree un mensaje para firmarlo combinando la versión, la hora de entrega y el cuerpo de la solicitud: `v0:timestamp:body`. #### Cálculo de HMAC SHA-256 Calcule la firma HMAC SHA-256 con el secreto de firma. #### Comparación de firmas Compare la firma calculada con la firma proporcionada. > **Note** > > La firma proporcionada lleva el prefijo `v0=`. Actualmente, Frame.io solo tiene esta versión para firmar solicitudes. Deberá añadir este prefijo a la firma calculada. **`Python`** ```python title="Python" import hmac import hashlib def verify_signature(curr_time, req_time, signature, body, secret): """ Verify webhook/custom action signature :Args: curr_time (float): Current epoch time req_time (float): Request epoch time signature (str): Signature provided by the frame.io API for the given request body (str): Custom Action body from the received POST secret (str): The secret for this Custom Action that you saved when you first created it """ if int(curr_time) - int(req_time) < 500: message = 'v0:{}:{}'.format(req_time, body) calculated_signature = 'v0={}'.format(hmac.new( bytes(secret, 'latin-1'), msg=bytes(message, 'latin-1'), digestmod=hashlib.sha256).hexdigest()) if calculated_signature == signature: return True return False ``` ## Comentarios Nos gustaría conocer la opinión de desarrolladores y usuarios sobre cómo les gustaría usar Actions en Frame.io V4. [Póngase en contacto con nosotros](https://forum.frame.io/) para enviarnos preguntas, ideas y casos de uso que nos ayuden a definir prioridades.