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.

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, 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 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.

Per ulteriori informazioni sulla paginazione, leggi Paginazione ed errori. 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.

| * 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

2. Visualizza i nomi delle cartelle in un elenco

3. Quando un utente fa clic su una cartella, passa l’ID della cartella nella query seguente:

4. 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 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:

1
{
2
  "next_asset_id": "<new-asset-id>"
3
}