> This page is for Piattaforma, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Versione precedente: 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. # 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](https://next.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](https://developer.adobe.com/frameio/guides/Webhooks/), 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](https://next.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: #### Nuovi tipi di campo Prima erano supportati solo campi di testo e a selezione singola, mentre ora supportiamo anche la selezione multipla, un'area di testo (per una casella di testo più grande) e un campo booleano (per un pulsante di scelta). #### Link cliccabili I campi di testo non facilitano le operazioni per copiare e incollare gli URL da parte degli utenti. Ora è possibile usare il nuovo campo del link per semplificare l'operazione di copia con un solo clic. #### Finestre dinamiche In base alla quantità di dati restituiti, la finestra delle azioni si ridimensiona in modo dinamico e si adatta al meglio alle informazioni nel modulo. Se necessario, le finestre sono anche scorrevoli. #### Azioni multi-risorsa Configura un'azione in modo che includa fino a 100 risorse in una singola richiesta. \ NOVITÀ #### Tipi di risorsa misti Le azioni non sono limitate a un solo tipo di risorsa: possono essere attivate in base a una combinazione di file, cartelle e stack di versioni. #### [Modulo di feedback in-app](https://next.frame.io/settings/actions) Vogliamo sapere da sviluppatori e utenti finali come vengono utilizzate le azioni, perciò abbiamo inserito un modulo di feedback nella pagina delle impostazioni sul web. ## 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](/docs/resources/migration). > **Info** > > Configura le [azioni personalizzate](/api-reference/custom-actions/actions-show) con l'API. Un'azione personalizzata richiede: | Nome campo | Descrizione | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | Nome | Il nome che scegli per l'azione personalizzata. Verrà mostrato nel menu delle azioni personalizzate disponibili in Frame.io. | | Descrizione | Spiega cosa fa l'azione e serve da riferimento (la descrizione non verrà visualizzata nell'app web Frame.io). | | Evento | Chiave di evento interna per distinguere meglio tra eventi webhook normali e personalizzati. | | URL | Dove consegnare gli eventi. | | Area di lavoro | L'area di lavoro che utilizzerà l'azione personalizzata. | ## 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](https://next.frame.io/). > **Warning** > > Sono richieste autorizzazioni come amministratore dell'account per creare azioni personalizzate per un'area di lavoro. Chiedi al tuo amministratore di modificare le tue autorizzazioni se non hai accesso. ### Configurazione multi-risorsa Il supporto multi-risorsa è basato sulla configurazione e deve essere abilitato esplicitamente dalla finestra di configurazione dell'azione [sul web](https://next.frame.io/settings/actions). 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: #### Contesto dell'azione * Su quale azione personalizzata è stato fatto clic * Su quali risorse è stato fatto clic * Quale utente ha eseguito l'azione * Quale tipo di evento è stato attivato #### Contesto dell'organizzazione * Quale account è associato all'azione personalizzata * Quale area di lavoro è associata all'azione personalizzata * Quale progetto contiene le risorse #### Payload - Supporto per singola risorsa o multi-risorsa Le azioni personalizzate accettavano originariamente solo una risorsa per richiesta, utilizzando un oggetto `resource` contenente una sola risorsa. Con il supporto multi-risorsa abilitato, il payload utilizza un elenco di `resources` con una o più risorse (con un massimo di 100 risorse in una richiesta). ```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" } } ``` #### Payload legacy - Solo supporto per singola risorsa ```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" } } ``` ### Migrazione dal payload legacy > **Payload legacy pianificato per essere deprecato** > > Il payload legacy è pianificato per essere deprecato. Suggeriamo fortemente agli utenti di migrare i loro servizi per elaborare il nuovo payload. > > Abilitando il flag della configurazione e aggiornando la gestione del payload, un'azione può passare senza problemi al supporto di un payload multi-risorsa. > > 1. Sostituisci l'utilizzo del singolo oggetto `resource` con l'elenco di `resources` 2. Aggiorna il codice per iterare sull'elenco di `resources` > > 2. Abilita il flag multi-risorsa nella configurazione delle azioni | Nome campo | Descrizione | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id_account` | L'ID account univoco dell'azione. | | `action_id` | L'ID univoco dell'azione. | | `interaction_id` | Un identificatore univoco generato da Frame.io e utilizzato per tenere traccia della transazione in più richieste, ad esempio i callback concatenati di messaggi o moduli. Rimane invariato durante ogni sequenza dell'azione. | | `project_id` | L'ID progetto univoco dell'azione. | | `resource.id` | L'ID della risorsa da cui hai attivato l'azione. | | `resource.type` | Il tipo di risorsa da cui hai attivato l'azione. | | `type` | Il nome fornito nel campo `event` durante la configurazione dell'azione. | | `user.id` | L'ID dell'utente che ha attivato l'azione. | | `workspace.id` | L'ID dell'area di lavoro che utilizza l'azione. | | `data` | Coppie chiave-valore contenenti i nomi dei campi del modulo e i valori selezionati dall'utente. L'app riceve queste informazioni per sapere quali scelte sono state effettuate. | ## 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. > **Note** > > Frame.io si aspetta una risposta in meno di 10 secondi e tenta di riprovare fino a 5 volte in attesa di una risposta positiva. Idealmente la risposta è immediata e le azioni asincrone si verificano dopo un trigger tramite un'azione personalizzata. ## 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. ```json { "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: ```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" } ] } ] } ``` Quando l'utente invia il modulo, riceverai un evento sullo stesso URL del POST iniziale: ```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" } } ``` 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: #### Proprietà del campo * **type:**: indica all'interfaccia utente di Frame.io che tipo di dati aspettarsi e quale componente e rendering. \* **label**: appare nell'interfaccia utente come intestazione sopra il campo. #### Dati del campo * **name**: chiave con cui il campo verrà identificato nel payload successivo. \* **value**: valore con cui precompilare il campo. ## Tipi di campi supportati ### Campo di testo Un semplice campo di testo senza parametri aggiuntivi. ```json { "type": "text", "label": "Title", "name": "title", "value": "MyVideo.mp4" } ``` ### Area di testo Una semplice area di testo senza parametri aggiuntivi. ```json { "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. ```json { "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. ```json { "type": "boolean", "name": "enabled", "label": "Enabled", "value": "false" } ``` ### Link Un semplice link senza parametri aggiuntivi. ```json { "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: #### Creazione e gestione * Qualsiasi amministratore può creare un'azione personalizzata su un'area di lavoro. * Qualsiasi amministratore può modificare o eliminare un'azione personalizzata che esiste in un team. #### Aggiornamenti in tempo reale * Una volta apportata la modifica, tutti gli utenti potranno vederne immediatamente il risultato. ## 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: | Nome | Descrizione | | ----------------------------- | ----------------------------------------------------------- | | `X-Frameio-Request-Timestamp` | Il momento in cui è stata attivata l'azione personalizzata. | | `X-Frameio-Signature` | La firma calcolata. | #### Verifica della marca temporale **La marca temporale** è il momento in cui la richiesta è stata firmata in uscita dalla rete Frame.io. Può essere utilizzata per evitare attacchi di tipo replay. Si consiglia di verificare che questo orario rientri nei 5 minuti dall'orario locale. #### Verifica della firma **La firma** è un hash HMAC SHA-256 che utilizza la chiave di firma fornita quando viene creata per la prima volta l'azione personalizzata. ### Verifica della firma #### Estrai la firma Estrai la firma dalle intestazioni HTTP. #### Crea un messaggio da firmare Crea un messaggio da firmare combinando la versione, l'ora di consegna e il corpo della richiesta: `v0:timestamp:body`. #### Calcola HMAC SHA256 Calcola la firma HMAC SHA256 utilizzando il secret di firma. #### Confronta le firme Confronta la firma calcolata con quella fornita. > **Note** > > La firma fornita ha il prefisso `v0=`. Al momento Frame.io ha solo questa versione per firmare le richieste. Dovrai aggiungere questo prefisso alla firma calcolata. **`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 ``` ## Feedback Ci piacerebbe conoscere l'opinione di sviluppatori e utenti finali su come vorrebbero utilizzare le azioni in Frame.io V4. Assicurati di [comunicarci](https://forum.frame.io/) domande, idee e casi d'uso per aiutarci nella definizione delle priorità.