> This page is for Piattaforma, version Versione precedente. > 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. # Leggere l'albero dei file ## Panoramica Che l'obiettivo finale sia la pubblicazione, la modifica o il trasferimento di risorse in una fase del flusso di lavoro, per molte integrazioni più approfondite con Frame.io occorre fornire l'elenco del contesto utente e, in definitiva, una visualizzazione della directory. Ecco la gerarchia di base delle risorse (o file) all'interno di Frame.io: #### Account > Team > Progetto > Risorse Questo articolo spiega come interagire con l'albero dei file effettuando chiamate API sequenziali. Una strategia comune per lavorare con i file è accedere prima a un progetto, elencare le cartelle, quindi lavorare con le risorse e gli stack di versioni contenuti al loro interno. ## Concetti importanti ### Ogni progetto ha una risorsa root unica Le API RESTful di solito descrivono le risorse utilizzando identificatori univoci; `root_asset_id` è l'identificatore univoco per l'albero delle risorse del progetto. Consideralo un costrutto speciale che agisce come nodo root per un progetto: le risorse rimanenti si impilano sotto la root in un albero discendente. root-asset-id Nei flussi di lavoro comuni, gli utenti delle API devono scendere nell'albero per interagire con le risorse più in profondità nella gerarchia dei file. ### Collaboratori e progetti condivisi Un **collaboratore** è uno dei ruoli utente chiave in Frame.io. Questi utenti hanno accesso a un'area di lavoro del progetto, ma potrebbero non appartenere all'account generale di quel progetto. Lasciando da parte le autorizzazioni distinte per [collaboratori e membri del team](https://support.frame.io/en/articles/6067-difference-between-team-members-vs-collaborators), la differenza principale è che *l'iscrizione di un collaboratore riguarda esclusivamente un progetto e potrebbe non avere alcuna relazione con un team*. Ciò crea un leggero inconveniente per i flussi di lavoro in cui gli elenchi di directory sono fondamentali. Mentre la gerarchia di base indicata in alto (Account > Team > Progetto > Risorse) dovrebbe funzionare per la maggior parte dei casi d'uso, non descriverà i progetti in cui un utente autenticato è un collaboratore, ma non un membro del team. Per aggirare questo problema quando si elencano le directory, puoi: * Recuperare i progetti condivisi di un utente, spacchettare la gerarchia di team e account e unirli tutti insieme oppure * Recuperare i progetti condivisi di un utente ed elencarli tutti insieme come contesto separato. Entrambi i metodi vanno bene; il secondo è un po' più semplice, ma il primo è più vicino a come la web app di Frame.io presenta informazioni simili. In ogni caso, i metodi trattati in questa guida si applicano a entrambi. ## Elencare una directory ### 1. Recupera gli account dell'utente `GET https://api.frame.io/v2/accounts` Effettua la chiamata in alto con un token bearer valido per ottenere gli account dell'utente. Riceverai tutti gli account in cui l'utente ha lo stato di membro del team, team manager o amministratore. Potresti anche ricevere dei team per i quali un utente ha diritti di fatturazione/amministratore, ma senza accesso al team. Ciò, tuttavia, è raro e verrà eliminato nel passaggio successivo. Il payload per la richiesta di account è abbastanza dettagliato. Ecco un riepilogo dei dati importanti che potresti voler recuperare dalla risposta: * `id` * `display_name` * `owner` (`email`, `name`) * (facoltativamente) `image` *Nota:* l'immagine dell'account restituita dall'API sarà una chiave S3 pre-firmata, quindi l'URL restituito "scadrà" dopo circa un giorno. Per aggirare questo problema, dovresti recuperare nuovamente l'immagine ogni volta che il servizio viene caricato o, idealmente, memorizzarla localmente. Nota che `id` e `owner.email` sono gli unici campi obbligatori per un account utente. Se stai visualizzando gli utenti in un'altra applicazione, può essere utile scrivere una logica condizionale per presentare gli account utente. Consigliamo di controllare e, se il valore non è *null*, visualizzare l'account con il seguente ordine di preferenza: 1. "`display_name`" 2. "Account di `owner.name`" 3. "Account di `owner.email`" Quando l'utente sceglie un account, probabilmente vorrai presentare i team, il che richiede una richiesta API aggiuntiva. ### 2. Recupera i team all'interno dell'account `GET https://api.frame.io/v2/accounts/{{account_id}}/teams` I team in Frame.io possono essere "pubblici" (cioè individuabili da parte di qualsiasi membro del team nell'account) o "privati" (individuabili solo da membri specifici del team). L'API gestirà il contesto per conto tuo, quindi tutto ciò che devi fare è effettuare una chiamata valida specificando l'`account_id` nella richiesta in alto. Sebbene sia improbabile che un utente faccia parte di molti account, i team sono una risorsa che può crescere rapidamente a dismisura. I limiti di frequenza delle API di Frame.io sono piuttosto alti, ma è sempre bene controllare le intestazioni di risposta e, se necessario, applicare la paginazione. Per ulteriori informazioni sulla paginazione, leggi [Paginazione ed errori](/docs/troubleshooting/troubleshooting). **Recupera i seguenti attributi di ogni team:** * `id` * `name` * (facoltativamente) `team_image` Quando selezioni un team, ti consigliamo di visualizzare i relativi progetti. **Nota**: se vuoi, puoi anche eseguire `GET https://api.frame.io/v2/teams` per un utente; l'API restituirà ogni team di appartenenza dell'utente, indipendentemente dal contesto dell'account. Anche se tecnicamente questo metodo funzioni, c'è il rischio di perdere il contesto, a meno che non esegui un altro passaggio per: 1. Ristabilire il contesto in modo da riflettere il nome dell'account accanto a ciascun team 2. Consentire all'utente di cercare il testo dell'elenco Se stai elencando progetti condivisi dal livello di account verso il basso, ti consigliamo di effettuare una chiamata aggiuntiva a `GET https://api.frame.io/v2/projects/shared`. Ogni progetto restituito nella risposta conterrà i seguenti attributi, che puoi riportare mentre crei la directory: * `id` (del progetto stesso) * `id_team` * `team.account_id` In alternativa, puoi creare un'opzione per "Progetti condivisi" semplicemente aggiungendola come "Team" in qualsiasi contesto di account scelto. Se scegli di farlo, per l'utente finale è utile avere una separazione visiva dei progetti condivisi dai veri progetti di competenza del team, poiché l'elenco singolo dei progetti condivisi può includere molti contesti diversi di account e team reali. ### 3. Recupera i progetti del team `GET https://api.frame.io/v2/teams/{{team_id}}/projects` Successivamente, effettua la chiamata in alto e recupera tutti i progetti all'interno del team. **Per ogni progetto, dovrai acquisire:** * `id` * `name` * `root_asset_id` * (facoltativamente) `private`, nel caso tu voglia mostrare all'utente una differenziazione nell'interfaccia utente Come spiegato all'inizio dell'articolo, `root_asset_id` è un elemento importante dell'architettura delle risorse di Frame.io, in quanto ti consente di navigare nella directory di file e cartelle all'interno di un progetto. Riassumiamo rapidamente quello che abbiamo fatto finora: abbiamo stabilito il contesto combinato di: | * Account | * Team | * Progetti del team (e root_asset_id) | * Progetti condivisi (e root_asset_id) | Questo è tutto ciò di cui abbiamo bisogno per creare o recuperare risorse. ## Elencare cartelle e risorse ### 4. Genera la struttura iniziale delle cartelle `GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder` Questo elencherà tutte le cartelle in un progetto, a partire da `root_asset_id`. Se non ci sono cartelle, l'elenco sarà vuoto. Se vuoi includere sia file che cartelle (ad esempio se il passaggio successivo prevede di eseguire `GET` per una risorsa da Frame.io), basta omettere il parametro della stringa di query. Le altre due opzioni di filtro disponibili per il parametro "type" sono "file" e "version_stack". Tutti e tre i filtri si escludono a vicenda e una chiamata non filtrata restituirà tutti e tre i tipi insieme. ### 5. Esplora la struttura di directory **Per ogni cartella restituita, dovrai acquisire:** * `id` * `name` Poiché ogni cartella è una risorsa, il flusso di lavoro per esplorare una struttura di cartelle sarà questo: 1. `GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder` 1. Visualizza i nomi delle cartelle in un elenco 2. Quando un utente fa clic su una cartella, passa l'ID della cartella nella query seguente: 2. `GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder` ### 6. Crea e carica **In una cartella:** `POST https://api.frame.io/v2/{{folder_id}}/children` Una volta ottenuto l'ID della cartella in cui eseguire il caricamento, basta eseguire `POST` sui relativi elementi figlio, in base alla documentazione delle risorse e alla guida. Questo creerà una risorsa segnaposto e (a seconda del metodo scelto) restituirà: * Un `uuid` destinato ai casi d'uso di tracciamento * Un elenco di upload_url da utilizzare per inserire il file direttamente nell'archivio dati di backend di Frame.io. **In uno stack di versioni:** gli stack di versioni hanno un flusso di lavoro simile, con un passaggio aggiuntivo descritto in [questa guida](doc:managing-version-stacks) e riassunto di seguito. È importante ricordare che uno stack di versioni è un contenitore che appare come una risorsa, ma si comporta come una cartella; devi prima caricare la risorsa e poi aggiungerla allo stack di versioni come azioni separate. Di conseguenza, **se desideri caricare una risorsa in uno stack di versioni, avrai bisogno di quanto segue:** * L'`id` dello stack di versioni * Il `parent_id` dello stack di versioni (ad esempio la cartella che lo contenente o la root del progetto) Prima, esegui `POST https://api.frame.io/v2/assets/{{parent_id}}/children` per creare la nuova risorsa. Acquisisci il nuovo `id` nella risposta. Ora puoi utilizzare l'ID della nuova risorsa ed eseguire `POST https://api.frame.io/v2/assets/{{version_stack_id}}/version`, con il seguente payload del corpo: ```json { "next_asset_id": "" } ```