Guida alla migrazione dall'API Frame.io legacy a V4
Introduzione
L’API Frame.io V4 è una versione completamente riprogettata dell’API legacy, spesso chiamata endpoint V2 o API Frame.io V3. La riprogettazione sfrutta appieno le nuove capacità e funzionalità di Frame V4, mantenendo tutte le funzionalità rilevanti dell’API legacy. Questa guida illustra le principali differenze tra l’API legacy e V4, oltre a fornire istruzioni dettagliate per eseguire la migrazione senza problemi.
Elenco di controllo per la migrazione
Autenticazione
Per gli account migrati a V4 e non ancora amministrati tramite Adobe Admin Console, puoi continuare a utilizzare i token sviluppatore legacy gestiti nel sito per sviluppatori di Frame.io, ma dovrai aggiungere un’intestazione alle chiamate API con la chiave x-frameio-legacy-token-auth e un valore true. In caso contrario, segui i passaggi nella sezione Autenticazione di seguito.
Aggiorna le chiamate API esistenti
Tutte le route dell’API legacy devono essere mappate alle nuove route API V4 e ai payload JSON. Di seguito puoi trovare una tabella di mappatura abbastanza completa per semplificare questo processo.
Si consiglia di eseguire dei test
Esegui test accurati. Date le molte modifiche all’API, è consigliabile eseguire i test con un account V4 per assicurarti che la nuova API funzioni come previsto.
Implementa un accesso dedicato
Devi implementare un metodo di accesso dedicato per V4 per via degli URL di autenticazione separati. L’URL di autenticazione V4 è diverso da quello dell’API legacy e non restituirà nella risposta gli account non ancora aggiornati a V4, perciò dovrebbe essere trattato come un’integrazione separata.
Se nella tabella di mappatura in basso non trovi un endpoint per il quale hai domande, contatta il nostro team di assistenza per maggiori informazioni all’indirizzo support@frame.io.
Autenticazione gestita da Adobe Developer Console
Per gli account migrati a V4 che sono gestiti tramite Adobe Developer Console, dovrai utilizzare l’API V4 con Oauth2.0. Devi seguire questi passaggi.
Crea un progetto Adobe
Crea un progetto in Adobe Developer Console e aggiungi Frame.io come prodotto.
Scegli il tipo di autenticazione
Esegui l’autenticazione. Consulta la guida all’autenticazione per ulteriori informazioni. Se il tuo account V4 non è ancora gestito tramite Adobe Admin Console, puoi saltare questo passaggio. * Autenticazione utente: la connessione a Frame avviene utilizzando un ID client e/o un secret del client e l’utente deve accedere con nome utente e password. * Autenticazione server-to-server: la connessione a Frame avviene utilizzando l’ID client e il secret del client, ma non richiede che un utente acceda tramite browser.
Mappature degli endpoint (da API legacy a V4)
Se utilizzi l’autenticazione con token sviluppatore legacy, dovrai aggiungere un’intestazione alle richieste API con la chiave x-frameio-legacy-token-auth e il valore true.
Note generali per la migrazione:
Risorse
Le “risorse” nell’API legacy ora si dividono in “file”, “cartelle” e “stack di versioni” in V4.
Autorizzazioni
Le autorizzazioni e i ruoli sono diversi in V4, il che modifica la struttura degli endpoint. In V4 esistono ruoli utente per aree di lavoro e progetti. Per maggiori dettagli, consulta Gestione delle autorizzazioni utente.
1. Account e informazioni utente
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| GET | /v2/accounts (Recupera gli account per l’utente) | GET | /v4/accounts (Elenca account) | V4 restituisce tutti gli account a cui l’utente può accedere. |
| GET | /v2/accounts/{account_id} (Recupera account per ID) | N/A | N/A | Le informazioni su un account specifico sono disponibili nell’endpoint dell’elenco degli account. |
| GET | /v2/me (Recupera utente corrente) | GET | /v4/me (Dettagli utente) | Recupera il profilo dell’utente corrente. |
| GET | /v2/accounts/{account_id}/membership | N/A | N/A | I ruoli e le autorizzazioni vengono gestiti tramite le autorizzazioni per l’area di lavoro e il progetto. |
2. Aree di lavoro (endpoint per i team sostituiti)
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| GET | /v2/accounts/{account_id}/teams (Recupera tutti i team di un account) | GET | /V4/accounts/{account_ID}/workspaces (Elenca aree di lavoro) | Concetto di “team” nell’API legacy → “Area di lavoro” in V4. |
| POST | /v2/accounts/{account_id}/teams (Crea un team per l’account specificato) | POST | /v4/accounts/{account_id}/workspaces (Crea area di lavoro) | Il corpo è simile (nome ecc.). La risposta è un oggetto di area di lavoro, non un oggetto di team. |
| GET | /v2/teams/{team_id} (Recupera un team) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id} (Mostra area di lavoro) | ID team → ID area di lavoro in V4. |
| GET | /v2/teams/{team_id}/members (Recupera i membri del team) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/users (Recupera membri dell’area di lavoro) | Restituisce tutti gli utenti in un’area di lavoro |
| POST | /v2/teams/{team_id}/members (Aggiungi un membro del team)) | PATCH | /v4/accounts/{account_id}/workspaces/{workspace_id}/users/{user_id} (Aggiungi o aggiorna il ruolo utente nell’area di lavoro) | Consente di aggiungere o rimuovere gli utenti da un’area di lavoro |
| GET | /v2/teams/{team_id}/membership (Recupera l’iscrizione utente per il team) | N/A | N/A | I ruoli e le autorizzazioni vengono gestiti tramite le autorizzazioni per l’area di lavoro e il progetto. |
3. Progetti
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| GET | /v2/teams/{team_id}/projects (Recupera progetti per team) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects (Elenca progetti) | È necessario fornire sia account_id che workspace_id in V4. |
| GET | /v2/projects/shared | GET | /V4/accounts/{account_ID}/Invited_projects (List Invited Projects) | Elenca solo i progetti invitati /v4/accounts/{account_id}/projects elenca tutti i progetti, inclusi quelli invitati |
| POST | /v2/teams/{team_id}/projects (Crea un progetto) | POST | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects (Crea progetto) | Il corpo è simile: { "name": "MyProject", … }. |
| GET | /v2/projects/{project_id} (Recupera progetto per ID) | GET | /v4/accounts/{account_id}/projects/{project_id} (Mostra progetto) | Richiede account_id e project_id |
| PUT | /v2/projects/{project_id} (Aggiorna un progetto) | PATCH | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id} (Aggiorna progetto) | V4 utilizza PATCH per gli aggiornamenti parziali. |
| DELETE | /v2/projects/{project_id} (Elimina progetto per ID) | DELETE | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id} (Elimina progetto) | Rimuove il progetto. |
| GET | /v2/projects/{project_id}/collaborators (Recupera collaboratori del progetto) | GET | /v4/accounts/{account_id}/projects/{project_id}/users (Elenca i ruoli utente del progetto) | Restituisce tutti gli utenti di un progetto (equivalente più simile all’endpoint legacy dei collaboratori) |
| POST | /v2/projects/{project_id}/collaborators (Aggiungi un collaboratore a un progetto) | PATCH | /v4/accounts/{account_id}/projects/{project_id}/users/{user_id} (Aggiorna i ruoli utente per il progetto specificato) | Consente di aggiungere o rimuovere gli utenti da un progetto (equivalente più simile all’endpoint legacy dei collaboratori) |
4. Cartelle
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| GET | /v2/assets/{asset_id}/children (Recupera risorse figlio) | GET | /v4/accounts/{account_id}/folders/{folder_id}/children (Elenca elementi figlio della cartella) | Se il tuo asset_id nell’API legacy era una cartella, ora è folder_id in V4. |
| POST | /v2/assets/{parent_asset_id}/children (Crea una risorsa) | POST | /v4/accounts/{account_id}/folders/{folder_id}/folders (Crea cartella) | Nell’API legacy si usava "type": "folder", mentre in V4 si usa {"data": {"name": "Folder name"}}. |
| GET | /v2/assets/{asset_id} (Recupera una risorsa) | GET | /v4/accounts/{account_id}/folders/{folder_id} (Mostra cartella) | L’API richiede “type”: “folder” L’API V4 richiede folder_id e account_id nei parametri del percorso |
| PUT | /v2/assets/{asset_id} (Aggiorna una risorsa) | PATCH | /v4/accounts/{account_id}/folders/{folder_id} (Aggiorna cartella) | API legacy: asset_id sarà l’ID della cartella API V4: corpo: {"data": {"name": "New Folder Name"}}. |
| DELETE | /v2/assets/{asset_id} (Elimina una risorsa) | DELETE | /v4/accounts/{account_id}/folders/{folder_id} (Elimina cartella) | Rimuove la cartella. |
| N/A | N/A | GET | /V4/accounts/{account_ID}/folders/{folder_ID}/folders (Elenca cartelle) | Elenca le cartelle presenti in una cartella specificata. Recupera root_folder_id dalla route per mostrare il progetto. Puoi utilizzarlo per elencare tutte le cartelle al livello più alto. |
5. Stack di versioni
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| POST | /v2/assets/{destination_folder}/copy (Copia una risorsa) | POST | /v4/account/{account_id}/version_stacks/{version_stack_id}/copy (Copia stack di versioni) | Legacy: cartella di destinazione nel percorso; da utilizzare con uno stack di versioni nella richiesta. V4: copia uno stack di versioni. |
| POST | /v2/assets/{asset_id}/version (Crea una versione di una risorsa) | POST | /v4/accounts/{account_id}/folders/{folder_id}/version_stacks (Crea stack di versioni) | Crea uno stack di versioni. Richiede da 2 a 10 ID file nel corpo della richiesta. |
| POST | /v2/assets/{asset_id}/version (Crea una versione di una risorsa) | PATCH | /v4/account/{account_id}/files/{file_id}/move (Sposta file nello stack di versioni) | Sposta un file in uno stack di versioni esistente. Usa il version_stack_id come parent_id nel corpo della richiesta. |
| GET | /v2/assets/{asset_id}/children (Recupera risorse figlio) | GET | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/children (Elenca elementi figlio dello stack di versioni) | Legacy: da usare con l’asset_id di uno stack di versioni. V4: elenca gli elementi figlio (file/versioni) in uno stack di versioni. |
| N/A | N/A | GET | /v4/accounts/{account_id}/folders/{folder_id}/version_stacks (Elenca stack di versioni) | Elenca gli stack di versioni in una cartella. |
| N/A | N/A | PATCH | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/move (Sposta stack di versioni) | Sposta uno stack di versioni in un’altra cartella. |
| GET | /v2/assets/{asset_id} (Recupera una risorsa) | GET | /v4/accounts/{account_id}/version_stacks/{version_stack_id} (Mostra stack di versioni) | Legacy: da usare con l’asset_id di uno stack di versioni. V4: mostra i dettagli dello stack di versioni. |
| DELETE | /v2/assets/{asset_id}/unversion (Elimina annullamento della versione) | N/A | N/A | L’eliminazione dell’annullamento della versione non è attualmente supportata in V4. |
6. File
Note: ora ci sono due endpoint per creare file in V4 (localmente e tramite caricamento S3). Per maggiori dettagli, consulta Caricamento dei file.
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| POST | /v2/assets/{parent_asset_id}/children (Crea una risorsa) | POST | /v4/accounts/{account_id}/folders/{folder_id}/files/local_upload (Crea file (caricamento locale)) | API legacy: richiede name, type, filetype, filesize e auto_version_id API V4: account_id e folder_id sono obbligatori nei parametri del percorso, file_size e name sono obbligatori nel payload |
| N/A | N/A | POST | /v4/accounts/{account_id}/folders/{folder_id}/files/remote_upload (Crea file (caricamento remoto)) | Account_id e folder_id sono obbligatori nei parametri del percorso, URL di origine e nome sono obbligatori nel payload |
| GET | /v2/assets/{asset_id} (Recupera una risorsa) | GET | /v4/accounts/{account_id}/files/{file_id} (Mostra file) | Mostra i dettagli del file: sono disponibili molte inclusioni per restituire dettagli aggiuntivi del file nella risposta |
| N/A | N/A | GET | /v4/accounts/{account_id}/files/{file_id}/status (Recupera metadati del file) | Recupera lo stato di un caricamento remoto da un endpoint di creazione file con caricamento remoto |
| PUT | /v2/assets/{asset_id} (Aggiorna una risorsa) | PATCH | /v4/accounts/{account_id}/files/{file_id} (Aggiorna file) | Aggiorna il nome file. |
| DELETE | /v2/assets/{asset_id} (Elimina una risorsa) | DELETE | /v4/accounts/{account_id}/files/{file_id} (Elimina file) | 204 (No Content) in caso di successo. |
7. Commenti
La maggior parte delle funzionalità dell’API V4 per i commenti è attualmente supportata.
Funzionalità disponibili a breve:
- Reazioni ai commenti, ovvero emoji
- Visualizzazione o modifica dello stato di completamento dei commenti
- Visualizzazione di chi ha visto un commento (impressioni)
Il campo “timestamp” rappresenta la marca del fotogramma in cui viene lasciato il commento (a partire da 1), non la marca temporale
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| GET | /v2/assets/{asset_id}/comments (Recupera tutti i commenti e tutte le risposte di un thread di commenti) | GET | /v4/accounts/{account_id}/files/{file_id}/comments (Elenca commenti) | Elenca i commenti su un file. |
| POST | /v2/assets/{asset_id}/comments (Crea un commento) | POST | /v4/accounts/{account_id}/files/{asset_id}/comments (Crea commento) | Crea un commento. Il corpo è simile: {"text":"Nice","timestamp":12.3}. |
| GET | /v2/comments/{comment_id} (Recupera un commento per ID) | GET | /v4/accounts/{account_id}/comments/{comment_id} (Mostra commento) | Recupera un singolo commento per ID. |
| PUT | /v2/comments/{comment_id} (Aggiorna un commento) | PATCH | /v4/accounts/{account_id}/comments/{comment_id} (Aggiorna commento) | Aggiorna testo, ora ecc. |
| DELETE | /v2/comments/{comment_id} (Elimina un commento) | DELETE | /v4/accounts/{account_id}/comments/{comment_id} (Elimina commento) | Rimuove un commento. |
| GET | /v2/comments/{comment_id}/impressions (Recupera impressioni) | N/A | N/A | Le impressioni non sono attualmente supportate in V4. |
8. Condivisioni (link di revisione/presentazioni)
In Frame V4 i link di condivisione non sono più suddivisi tra link di revisione e di presentazione. In V4, il link di condivisione può ora essere configurato con stili diversi per adattarsi all’esperienza di revisione o presentazione.
Nota: l’interazione con link di revisione e presentazioni legacy tramite API V4 non è supportata.
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| GET | /v2/projects/{project_id}/review_links (Elenca i link di revisione in un progetto) | GET | /v4/accounts/{account_id}/projects/{project_id}/shares (Elenca condivisioni) | Elenca le condivisioni in un progetto (tieni presente che non include i link di revisione e le presentazioni legacy) |
| POST | /v2/projects/{project_id}/review_links (Crea un link di revisione) | POST | /v4/accounts/{account_id}/projects/{project_id}/shares (Crea condivisione) | Crea un nuovo link di condivisione. Il corpo potrebbe essere {"data":{"name":"Review Link","type":"review"}}. |
| POST | /v2/review_links/{link_id}/assets (Aggiungi risorsa a un link di revisione) | POST | /v4/accounts/{account_id}/shares/{share_id}/assets (Aggiungi nuova risorsa alla condivisione) | Aggiunge una risorsa a una condivisione. Supporta file, cartelle e stack di versioni. |
| N/A | Non esiste | DELETE | /v4/accounts/{account_id}/shares/{share_id}/assets/{asset_id} (Elimina condivisione) | Rimuovi risorsa dalla condivisione |
| DELETE | /v2/review_links/{link_id} (Elimina un link di revisione) | DELETE | /v4/accounts/{account_id}/shares/{share_id} (Elimina condivisione) | Elimina il link di condivisione. |
| PUT | /v2/review_links/{review_link_id} (Aggiorna un link di revisione) | PATCH | /v4/accounts/{account_id}/shares/{share_id} (Aggiorna condivisione) | Aggiorna il link di condivisione. |
9. Webhook
I webhook utilizzati in V3 verranno migrati e nella maggior parte dei casi funzionano allo stesso modo. Durante la migrazione vengono disabilitati ed è necessario abilitarli per farli funzionare. Occorre apportare alcune modifiche per gli eventi di risorsa, ora divisi in file e cartelle. Ci sono alcuni nuovi eventi specifici di V4 da tenere presenti: metadata.value.updated, eventi relativi alle raccolte ed eventi relativi alle condivisioni.
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| POST | /v2/teams/{team_id}/hooks (Crea webhook) | POST | /v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks (Crea webhook) | Fornisci {"data":{"url":"…","events":["file.created",…]}}. |
| GET | /v2/accounts/{account_id}/webhooks (Recupera webhook per un account) | GET | /v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks (Elenca webhook) | Recupera tutti i webhook per un’area di lavoro. Nota: per recuperare tutti i webhook di un account, devi recuperare tutte le aree di lavoro per l’account e poi recuperare tutti i webhook per quelle aree di lavoro. |
| GET | /v2/hooks/{hook_id} (Recupera webhook) | GET | /v4/accounts/{account_id}/webhooks/{webhook_id} (Elenca webhook) | Recupera le informazioni sul webhook |
| PUT | /v2/hooks/{hook_id} (Aggiorna webhook) | PATCH | /v4/accounts/{account_id}/webhooks/{webhook_id} (Aggiorna webhook) | Aggiorna le impostazioni del webhook |
| DELETE | /v2/hooks/{hook_id} (Elimina webhook) | DELETE | /v4/accounts/{account_id}/webhooks/{webhook_id} (Elimina webhook) | Rimuove il webhook. |
10. Azioni personalizzate
Le azioni personalizzate utilizzate in V3 vengono migrate, ma richiedono alcune modifiche alle richieste e alla gestione delle risposte. Durante la migrazione vengono disabilitati ed è necessario abilitarli per farli funzionare. Per maggiori dettagli consulta questo documento
Nota: gli endpoint delle azioni personalizzate sono attualmente nell’API sperimentale e richiederanno un’intestazione: “api-version: experimental”.
| Metodo | Endpoint legacy | Metodo | Endpoint V4 | Note |
|---|---|---|---|---|
| POST | /v2/teams/{team_id}/actions (Crea un’azione personalizzata) | POST | /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (Crea azione personalizzata) | Crea un’azione personalizzata in un’area di lavoro. |
| DELETE | /v2/actions/{action_id} (Elimina un’azione personalizzata) | DELETE | /v4/accounts/{account_id}/actions/{action_id} (Elimina azione personalizzata) | Elimina un’azione personalizzata. |
| PUT | /v2/actions/{action_id} (Aggiorna un’azione personalizzata) | PATCH | /v4/accounts/{account_id}/actions/{action_id} (Aggiorna azione personalizzata) | Aggiorna i dettagli dell’azione personalizzata. |
| GET | /v2/teams/{team_id}/actions (Recupera azioni personalizzate per un team) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (Elenca azioni personalizzate) | Elenca le azioni personalizzate in una determinata area di lavoro. |
| GET | /v2/actions/{action_id} (Recupera un’azione personalizzata tramite ID) | GET | /v4/accounts/{account_id}/actions/{action_id} (Mostra i dettagli dell’azione personalizzata) | Mostra i dettagli dell’azione personalizzata. |
Passaggi di migrazione
Aggiorna le richieste API
Aggiorna le richieste API nel codice in modo che facciano riferimento al nuovo schema endpoint.
Aggiorna i payload JSON
Aggiorna i payload JSON degli schemi di richiesta/risposta per assicurarti di produrre e consumare i campi corretti.
Aggiorna la terminologia
Aggiorna la terminologia: “team” → “area di lavoro”; “risorsa” → “file/cartella”; “link di revisione” o “link di presentazione” → “condivisioni” nel codice e nel front-end.
Testa gli endpoint
Testa tutti gli endpoint appena aggiornati. Se vedi messaggi 403, 404, 422, verifica gli endpoint, la forma del payload di richiesta ecc.
Analizza le risposte di errore
Analizza le nuove risposte di errore dettagliate, cercando il problema nella risposta JSON {"errors": […]} se la chiamata API non riesce.
Distribuisci in produzione
Distribuisci in produzione dopo la convalida usando un account Frame.io V4.
Gestione degli errori e problemi comuni
Alcuni percorsi restituiscono errori con descrizioni personalizzate che potrebbero differire leggermente dagli esempi riportati di seguito.
- 400 Bad Request: verifica l’accuratezza del payload. * 401 Unauthorized: token di autorizzazione non valido o mancante. * 403 Forbidden: ambito mancante o l’utente non dispone dell’accesso. * 404 Not Found: conferma endpoint, versione API o ID. * 422 Unprocessable Entity: convalida i dati della richiesta * 429 Too Many Requests: implementa un nuovo tentativo con backoff.
- 500 Internal Server Error: riprova dopo una breve pausa.
Supporto dell’SDK
Come per l’SDK legacy, è disponibile un SDK Python che gli sviluppatori possono utilizzare e per la prima volta è disponibile anche un SDK Typescript. Questi SDK avranno funzionalità simili, ma metodi completamente diversi. Se stai aggiornando dall’SDK legacy all’SDK V4, assicurati di aggiornare il codice di conseguenza. Puoi trovarli ai link seguenti:
Guida introduttiva agli SDK SDK Python SDK Typescript