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.

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, 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 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:

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.

Una Custom Action requiere lo siguiente:

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.

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. 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:

1
  POST /your/url
2
  {
3
    "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
4
    "action_id": "0aeb9feb-f8eb-4100-a8c2-b39b66d354ab",
5
    "data": {
6
        "description": "Pretty cool video.",
7
        "title": "Hey there!"
8
    },
9
    "interaction_id": "985559de-865a-40e5-a687-2bbed4497eaa",
10
    "project": {
11
        "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
12
    },
13
    "resources": [
14
        {
15
            "id": "fe41c5a8-1b8d-417d-a7df-0b88bc19b476",
16
            "type": "file"
17
        },
18
        {
19
            "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
20
            "type": "file"
21
        }
22
    ],
23
    "type": "some.event",
24
    "user": {
25
        "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
26
    },
27
    "workspace": {
28
        "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
29
    }
30
  }

1
  POST /your/url
2
  {
3
      "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
4
      "action_id": "0e38b93a-9f10-4bc7-90bc-bd07a16e510a",
5
      "data": {
6
          "description": "Wow look at this.",
7
          "title": "Hey there!!"
8
      },
9
      "interaction_id": "dff6d369-7150-41f9-8e6f-4f0895f6b416",
10
      "project": {
11
          "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
12
      },
13
      "resource": {
14
          "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
15
          "type": "file"
16
      },
17
      "type": "some.event",
18
      "user": {
19
          "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
20
      },
21
      "workspace": {
22
          "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
23
      }
24
  }                                  

Migración desde la carga útil heredada

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.

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.

1
{
2
  "title": "Success!",
3
  "description": "The thing worked! Nice."
4
}

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:

1
{
2
  "title": "Need some more info!",
3
  "description": "Getting ready to submit this file!",
4
  "fields": [
5
    {
6
      "type": "text",
7
      "label": "Title",
8
      "name": "title",
9
      "value": "MyVideo.mp4"
10
    },
11
    {
12
      "type": "select",
13
      "label": "Captions",
14
      "name": "captions",
15
      "options": [
16
        {
17
          "name": "Off",
18
          "value": "off"
19
        },
20
        {
21
          "name": "On",
22
          "value": "on"
23
        }
24
      ]
25
    }
26
  ]
27
}

Cuando el usuario envía el formulario, recibirá un evento en la misma URL que el POST inicial:

1
POST /your/url
2
{
3
  "type": "your-specified-event-name",
4
  "interaction_id": "the-same-id-as-before",
5
  "action_id": "unique-id-for-this-custom-action",
6
  "data":{
7
    "title": "MyVideo.mp4",
8
    "captions": "off"
9
  }
10
}

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:

Tipos de campo admitidos

Campo de texto

Campo de texto simple sin parámetros adicionales.

1
{  
2
  "type": "text",
3
  "label": "Title",
4
  "name": "title",
5
  "value": "MyVideo.mp4"
6
}

Área de texto

Área de texto simple sin parámetros adicionales.

1
{  
2
  "type": "textarea",
3
  "label": "Description",
4
  "name": "description",
5
  "value": "This video is really, really popular."
6
}

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.

1
{
2
  "type": "select",
3
  "label": "Captions",
4
  "name": "captions",
5
  "value": "off",
6
  "options": [
7
       {
8
         "name": "Off",
9
         "value": "off"
10
       },
11
       {
12
         "name": "On",
13
         "value": "on"
14
      }
15
   ]
16
}

Casilla

Casilla simple sin parámetros adicionales.

1
{ 
2
   "type": "boolean", 
3
   "name": "enabled", 
4
   "label": "Enabled", 
5
   "value": "false"
6
}

Vínculo

Vínculo simple sin parámetros adicionales.

1
{
2
  "type": "link",
3
  "name": "videoLink",
4
  "label": "Video Link",
5
  "value": "https://www.youtube.com/watch?v=XtX1zv9CEVc"
6
}

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:

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:

Verificación de la firma

1
import hmac
2
import hashlib
3
4
def verify_signature(curr_time, req_time, signature, body, secret):
5
    """
6
    Verify webhook/custom action signature
7
    :Args:
8
        curr_time (float): Current epoch time
9
        req_time (float): Request epoch time
10
        signature (str): Signature provided by the frame.io API for the given request
11
        body (str): Custom Action body from the received POST
12
        secret (str): The secret for this Custom Action that you saved when you first created it
13
    """
14
    if int(curr_time) - int(req_time) < 500:
15
        message = 'v0:{}:{}'.format(req_time, body)
16
        calculated_signature = 'v0={}'.format(hmac.new(
17
            bytes(secret, 'latin-1'),
18
            msg=bytes(message, 'latin-1'),
19
            digestmod=hashlib.sha256).hexdigest())
20
        if calculated_signature == signature:
21
            return True
22
    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 para enviarnos preguntas, ideas y casos de uso que nos ayuden a definir prioridades.