Información general sobre las acciones personalizadas

<Info title=“Aplicaciones de ejemplo”>

Si desea crear su propia aplicación de acciones personalizadas, nuestras aplicaciones de muestra le ayudarán a empezar:

</Info>

• JavaScript
• Python

Las acciones personalizadas son una forma de crear integraciones directamente en Frame.io como componentes de la IU programables. Esto permite una clase completa de flujos de trabajo que los usuarios pueden activar dentro de la aplicación, aprovechando el mismo enrutamiento de eventos subyacente que los webhooks. Actualmente, las acciones personalizadas están disponibles para activos y se muestran en el menú desplegable contextual/clic con el botón derecho del ratón disponible en cualquier activo, como se muestra en la imagen que aparece a continuación. <img alt=“actions-1” src=“file:docs/pages/v2/images/actions-1.png”>

Un activo es una representación sólida de un archivo en S3 y su contexto en Frame.io. Esto incluye transcodificaciones, contexto de usuario/equipo/proyecto y metadatos. Cuando un usuario hace clic en una acción personalizada en un activo, Frame.io enviará una carga útil a una URL que proporcione. La aplicación de recepción puede entonces responder con un código de estado HTTP para simplemente confirmar la recepción, o puede responder con una devolución de llamada personalizada que puede renderizar la IU adicional en Frame.io.

Configurar su acción personalizada

<Info title=“Compruebe sus permisos”>

Se requieren permisos de responsable de equipo para crear acciones de cliente para un equipo. Pida a su administrador que modifique sus permisos si no tiene acceso.

</Info> Las acciones personalizadas se pueden configurar en el área Acciones personalizadas de developer.frame.io. Una acción requiere:

Clic: Qué contiene la carga útil que recibe de Frame.io

Cuando el usuario haga clic en su acción personalizada, se enviará una carga útil a la URL que especificó en el campo URL.

1
POST /your/url
2
\{
3
  "action_id": "2444cccc-7777-4a11-8ddd-05aa45bb956b",
4
  "interaction_id": "aafa3qq2-c1f6-4111-92b2-4aa64277c33f",
5
  "project": \{
6
    "id": "a7d6a74b-d45d-4019-9069-24651e0b9f64"
7
  },
8
  "resource": \{
9
    "id": "9q2e5555-3a22-44dd-888a-abbb72c3333b",
10
    "type": "asset"
11
  },
12
  "team": \{
13
    "id": "54353cd2-c6ee-4aa1-954a-ce9e19602aa9"
14
  },
15
  "type": "my.action",
16
  "user": \{
17
    "id": "fb57eee0-79f2-4bc7-9b70-99fbc175175c"
18
  }
19
}

Puede usar esta carga útil para identificar:

• En cuáles de sus acciones personalizadas se hizo clic
• En qué recurso se hizo clic
• Qué usuario realizó la acción

<Info title=“Acerca de las interacciones”> El interaction_id se proporciona como un identificador único para ayudarle a realizar el seguimiento de la interacción a medida que evoluciona con el tiempo. Si no necesita responder al usuario, simplemente devuelva un código de estado 200 y listo. Aunque es opcional, recomendamos incluir información sobre el resultado de la acción, como un mensaje sencillo que indique que la operación se ha realizado correctamente o una alerta de error. Las acciones personalizadas admiten devoluciones de llamada de mensajes. </Info>

<Info title=“Reintentos y tiempos de espera”>

Nuestra aplicación espera una respuesta en menos de 5 segundos y lo reintentará hasta 5 veces mientras espera una respuesta correcta. Idealmente debería responder de inmediato y realizar cualquier acción de forma asíncrona después de activarse mediante una acción personalizada.

</Info>

Crear una devolución de llamada de mensaje

En su respuesta HTTP al evento de webhook, puede devolver un objeto JSON que describa un mensaje que se devolverá al usuario que lo inició en la IU de Frame.io. Si quiere probar a generar un mensaje y ver cuál es el resultado, puede utilizar nuestro Generador de acciones personalizadas, que le permite configurar devoluciones de llamada de mensajes o formularios y ver cómo aparecerían en la aplicación web de Frame.io.

A continuación, se muestra un objeto de ejemplo:

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

Eso mostrará una alerta al usuario que tiene el siguiente aspecto:

<img alt=“actions-3” src=“file:docs/pages/v2/images/actions-3.png”>

Los mensajes son una manera sencilla de cerrar el bucle del ciclo de vida de las acciones, ya que proporcionan contexto variable al usuario que realiza la acción sin pedirle que cambie de contexto.

Esto es suficiente para satisfacer muchos casos de uso, pero a veces la carga útil inicial y las llamadas posteriores a la API de Frame.io no proporcionarán suficiente contexto para la aplicación de recepción. Para estos escenarios, también admitimos Devoluciones de llamada de formulario.

Crear una devolución de llamada de formulario

Supongamos que necesita más información antes de iniciar su proceso. Por ejemplo, puede que esté cargando contenido a un sistema que requiere detalles y configuración adicionales. Puede “describir” un formulario en su respuesta, que el usuario verá realmente. Podrá rellenarlo y se le enviará directamente de vuelta.

A continuación, se muestra un formulario de ejemplo que procesará un formulario en la IU de Frame.io que el usuario inicial que realiza la acción puede rellenar y enviar:

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
}

<img alt=“actions-form” src=“file:docs/pages/v2/images/actions-form.png”>

Cuando el usuario envía el formulario, recibirá un evento en la misma URL que la solicitud 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 que añadió en su formulario aparecen en la sección data de la carga útil JSON enviada por Frame.io. Utilice el interaction_id para asignar la solicitud inicial y estos nuevos datos del formulario. Y de nuevo, si lo desea, puede responder con un mensaje (o incluso otro formulario).

Al encadenar acciones, formularios y mensajes, puede programar eficazmente flujos de trabajo completos de activos en Frame.io con lógica empresarial desde un sistema externo.

Dé rienda suelta a su creatividad. El cielo es el límite.

Detalles del formulario

Al igual que los mensajes, los formularios son compatibles con los atributos title y description que se procesan en la parte superior del formulario. Además, cada campo del formulario acepta los siguientes atributos base:

• type: Indica a la IU de Frame.io qué tipo de datos debe esperar, además de qué componente y procesamiento.
• label: Aparece en la IU como encabezado sobre el 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 campos compatibles

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
}

Select list Defines a picklist that the user can choose from. Must include an options list, each member of which should include a human-readable name, and a machine-parseable value.

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
}

**Lista de selección** Define una lista de selección entre la que puede elegir el usuario. Debe incluir una lista deoptionsy cada uno de sus miembros debe incluir unnamelegible por una persona y unvalue` que pueda analizar una máquina. ```json

{

“type”: “select”,

“label”: “Captions”,

“name”: “captions”,

“value”: “off”,

“options”: [

{

“name”: “Off”,

“value”: “off”

},

{

“name”: “On”,

“value”: “on”

}

]

}

## Acciones personalizadas y el modelo de permisos de Frame.io
Los webhooks y las acciones personalizadas tienen un modelo de permisos especial: pertenecen a un **equipo**, no a un usuario específico que exista en un equipo o cuenta. Esto significa lo siguiente:
* Cualquier administrador o responsable de equipo puede crear una acción personalizada en un equipo.
* Cualquier administrador o responsable de equipo puede modificar o eliminar una acción personalizada que exista en un equipo. Una vez modificada, todos los usuarios verán inmediatamente el resultado del cambio.
## Seguridad
De forma predeterminada, todas las acciones personalizadas 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.
### Verificación
La solicitud `POST` incluye lo siguiente:
| Nombre | Descripción |
| ---------- | ---------- |
| X-Frameio-Request-Timestamp\<code>` | Hora a la que se ha activado la acción personalizada. |
| X-Frameio-Signature`` | Firma calculada. |
**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. **La firma** es un hash HMAC SHA-256 que usa la clave de firma proporcionada al crear la acción personalizada por primera vez.
#### Verificación de la firma
1. Extraiga la firma de los encabezados HTTP
2. Cree un mensaje para firmarlo combinando la versión, la hora de entrega y el cuerpo de la solicitud
* \</code>v0:timestamp:body`
3. Calcule la firma HMAC SHA-256 con el secreto de firma.
* Nota: 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.
4. Haga una comparación.
```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