Azioni personalizzate

Le azioni di Frame.io permettono di accedere rapidamente alle operazioni multimediali più comuni, come scaricare, rinominare e duplicare i contenuti. Inoltre, consentono di integrare strumenti e servizi di terze parti direttamente nell’interfaccia di Frame.io.

Informazioni sulle azioni

Con l’introduzione delle azioni personalizzate, gli sviluppatori possono configurare e gestire le proprie azioni in Frame.io V4.Sfruttando lo stesso sistema di eventi alla base dei webhook, le azioni personalizzate costituiscono un meccanismo alternativo che permette agli sviluppatori di collegare le risorse agli strumenti più importanti per gli utenti del loro account Frame.io.

Le azioni possono essere eseguite da qualsiasi utente che faccia parte dell’area di lavoro Frame.io in cui è abilitata l’azione. Durante l’esecuzione di un’azione, Frame.io invia un payload a un URL fornito dall’utente. L’applicazione ricevente risponde con un codice di stato HTTP per confermare la ricezione, oppure con un callback personalizzato per visualizzare altri campi di modulo nell’interfaccia di Frame.io. L’applicazione ricevente può essere un programma in hosting, un servizio o persino uno strumento IPaaS low-code/no-code come Workfront Fusion o Zapier.

Usa le azioni personalizzate per creare delle integrazioni direttamente in Frame.io come componenti programmabili dell’interfaccia utente.In questo modo vengono abilitati vari flussi di lavoro che possono essere attivati dagli utenti all’interno dell’app, sfruttando lo stesso indirizzamento di eventi sottostante dei webhook. Puoi creare moduli con uno o più passaggi attivati dall’utente che riportano a Frame.io sotto forma di modulo diverso o risposta di base. Quando un utente fa clic su un’azione personalizzata in una risorsa, Frame.io invia un payload a un URL che fornisci. L’applicazione ricevente risponde con un codice di stato HTTP per riconoscere la ricezione oppure risponde con un callback personalizzato che permette di mostrare un’interfaccia utente aggiuntiva in Frame.io.

Miglioramenti delle azioni in V4

Sfruttando i feedback degli utenti della versione legacy, abbiamo incluso diversi miglioramenti al set di funzionalità delle azioni in Frame.io V4:

Azioni migrate

Ci sono alcune cose da tenere a mente quando si esegue la migrazione a un account Frame.io V4 contenente azioni personalizzate create nella versione legacy di Frame.io.

Stato delle azioni

Dopo la migrazione dell’account a Frame.io V4, tutte le azioni personalizzate create nelle versioni precedenti avranno uno stato “null” e verranno disabilitate automaticamente. In questo modo, gli utenti possono aggiornare preventivamente le azioni per utilizzare l’API V4 prima dell’abilitazione, poiché le azioni non aggiornate non funzioneranno. Per identificare le azioni in questo stato, visita la pagina delle impostazioni delle azioni e controlla la colonna dello stato oppure, se utilizzi l’API, controlla il campo is_active.

Risorse utilizzabili: file, cartelle e stack di versioni

Data la separazione dei tipi di risorsa come risorse a parte nell’API Frame.io V4, potrebbe esserci un comportamento da considerare quando si interpreta l’ID risorsa ricevuto nel payload dell’azione. Il comportamento per i singoli file è semplice, poiché l’ID riflette il file specifico su cui è stata eseguita l’azione. Come nel caso delle cartelle, ricevi l’ID della cartella su cui è stata eseguita l’azione; tuttavia, a seconda del caso d’uso, hai diverse opzioni per definire il comportamento dell’azione. Usa l’ID cartella per effettuare chiamate successive all’API Frame.io se vuoi interagire con la risorsa cartella stessa. In alternativa, potresti voler ottenere gli elementi figlio di quella cartella per eseguire ulteriori elaborazioni sulle risorse al suo interno. Quando un’azione viene eseguita su uno stack di versioni, il payload contiene l’ID per “Head Asset”, che è il file più in alto nello stack ed è quello mostrato nell’interfaccia utente Frame.io.

Scopri di più sulle differenze tra l’API Frame.io legacy e la V4 nella nostra guida alla migrazione.

Un’azione personalizzata richiede:

Configura l’azione personalizzata

Quando un utente attiva un’azione personalizzata, Frame.io invia un payload a un URL che fornisci. L’applicazione ricevente può rispondere con un codice di stato HTTP per riconoscere la ricezione oppure rispondere con un callback personalizzato che permette di mostrare un’interfaccia utente aggiuntiva in Frame.io.

Configurazione multi-risorsa

Il supporto multi-risorsa è basato sulla configurazione e deve essere abilitato esplicitamente dalla finestra di configurazione dell’azione sul web. Questa operazione può essere eseguita durante la creazione di una nuova azione o quando aggiorni un’azione esistente. 

Se il supporto multi-risorsa è abilitato, il formato del payload cambia immediatamente. I payload legacy e quelli che supportano più risorse si escludono a vicenda.

Payload da Frame.io

Quando l’utente fa clic sull’azione personalizzata, un payload verrà inviato all’URL specificato nel campo URL. Usa questo payload per identificare:

  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"
    }
  }

  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"
      }
  }                                  

Migrazione dal payload legacy

Interazioni, nuovi tentativi e timeout

L’interaction_id è un identificatore univoco per tenere traccia dell’interazione mentre si evolve nel tempo. Se non è necessario rispondere all’utente, restituisce un codice di stato 200. Sebbene sia facoltativo, consigliamo di includere delle informazioni sul risultato dell’azione, come un messaggio di operazione riuscita o un avviso di errore. Le azioni personalizzate supportano i callback dei messaggi.

Crea un callback del messaggio

Nella risposta HTTP all’evento webhook, puoi restituire un oggetto JSON che descrive un messaggio che verrà restituito all’utente che ha avviato l’azione nell’interfaccia utente di Frame.io.

{
  "title": "Success!",
  "description": "The thing worked! Nice."
}

I messaggi consentono di fornire feedback all’utente direttamente nell’interfaccia utente di Frame.io. Se devi raccogliere informazioni aggiuntive dall’utente, usa i callback dei moduli.

Crea un callback del modulo

Supponiamo che tu abbia bisogno di maggiori informazioni prima di iniziare il processo. Ad esempio, potresti caricare dei contenuti in un sistema che richiede dettagli aggiuntivi. Puoi descrivere un modulo nella risposta, che l’utente compila e ti invia. Ecco un esempio:

{
  "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"
        }
      ]
    }
  ]
}

Quando l’utente invia il modulo, riceverai un evento sullo stesso URL del POST iniziale:

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"
  }
}

Tutti i campi personalizzati aggiunti a un modulo appaiono nella sezione data del payload JSON inviato da Frame.io. Utilizza l’interaction_id per mappare la richiesta iniziale e questi nuovi dati del modulo. Puoi rispondere con un messaggio o concatenare un altro modulo. Concatenando azioni, moduli e messaggi, puoi programmare in modo efficace flussi di lavoro multi-fase in Frame.io, usando la logica di business di un sistema esterno.

Dettagli del modulo

Come per i messaggi, i moduli supportano gli attributi title e description che vengono visualizzati nella parte superiore del modulo. Oltre a questo, ogni campo del modulo accetta i seguenti attributi di base:

Tipi di campi supportati

Campo di testo

Un semplice campo di testo senza parametri aggiuntivi.

{  
  "type": "text",
  "label": "Title",
  "name": "title",
  "value": "MyVideo.mp4"
}

Area di testo

Una semplice area di testo senza parametri aggiuntivi.

{  
  "type": "textarea",
  "label": "Description",
  "name": "description",
  "value": "This video is really, really popular."
}

Elenco di selezione

Definisce un elenco di selezione da cui l’utente può scegliere. Deve includere un elenco di opzioni (options), ognuna delle quali deve includere un nome (name) leggibile dall’uomo e un valore (value) analizzabile dalla macchina.

{
  "type": "select",
  "label": "Captions",
  "name": "captions",
  "value": "off",
  "options": [
       {
         "name": "Off",
         "value": "off"
       },
       {
         "name": "On",
         "value": "on"
      }
   ]
}

Casella di controllo

Una semplice casella di controllo senza parametri aggiuntivi.

{ 
   "type": "boolean", 
   "name": "enabled", 
   "label": "Enabled", 
   "value": "false"
}

Link

Un semplice link senza parametri aggiuntivi.

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

Il modello di autorizzazioni di Frame.io

Le azioni personalizzate seguono un modello di autorizzazioni speciale: appartengono a un’area di lavoro, non a un utente specifico che esiste in un account. Ciò significa che:

Sicurezza e verifica

Per impostazione predefinita, per tutte le azioni personalizzate viene generata una chiave di firma durante la creazione. Non è configurabile. Questa chiave può essere utilizzata per verificare che la richiesta provenga da Frame.io. Nella richiesta POST sono inclusi i seguenti elementi:

Verifica della firma

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

Feedback

Ci piacerebbe conoscere l’opinione di sviluppatori e utenti finali su come vorrebbero utilizzare le azioni in Frame.io V4. Assicurati di comunicarci domande, idee e casi d’uso per aiutarci nella definizione delle priorità.