Gestisci gli stack di versioni

Panoramica

Gli stack di versioni sono un principio organizzativo in Frame.io che consente di impilare verticalmente le risorse senza inserirle in cartelle. Le versioni impilate rendono più semplice la navigazione da risorsa a risorsa all’interno dell’interfaccia di Frame.io e supportano la revisione affiancata.

Al momento non supportiamo il caricamento diretto in uno stack, quindi la sequenza API per gestire il flusso di lavoro di base per uno stack di versioni seguirà la stessa sequenza dell’interfaccia di Frame.io:

1. Carica la risorsa (se vuoi, contrassegnala come privata).
2. Assegna la risorsa nello stack.

Gli stack di versioni esistenti possono essere riordinati e le singole versioni possono essere rimosse da uno stack. Infine, gli stack di versioni possono essere eliminati senza però rimuovere le risorse che li costituiscono.

Concetti fondamentali

Gli stack di versioni, come le cartelle, sono tipi (type) speciali di risorse. Puoi recuperarli con gli stessi endpoint e, in base al valore della chiave type nella risposta API, analizzarli e instradarli di conseguenza. Questo è abbastanza semplice da mettere in pratica, ma può presentare alcuni problemi quando si gestiscono gli stack su larga scala. Il segreto per lavorare con gli stack di versioni è separare i quattro scenari più comuni:

1. Una risorsa può essere aggiunta a una risorsa, creando così uno il stack con un nuovo id.
2. Una risorsa può essere aggiunta a uno stack esistente.
3. Uno stack può essere riordinato.
4. Le singole versioni possono essere rimosse.

I primi due scenari utilizzano la stessa chiamata di endpoint, quindi l’unica vera sfumatura è sapere se stai creando un nuovo stack (partendo da due risorse) o aggiungendo la risorsa a uno stack esistente. A parte questo, i vincoli sono prevedibili:

1. Gli stack devono corrispondere per asset_type. Ad esempio, non puoi impilare un’immagine (image) su un flusso (stream).
2. L’utente coinvolto deve avere le autorizzazioni sia per la risorsa di origine che per la risorsa di destinazione o lo stack.
3. Le risorse vengono impilate in sequenza.
4. Non puoi impilare uno stack su un altro stack.
5. Le cartelle sono completamente escluse.

Gli ultimi due scenari sono abbastanza semplici, ma richiedono delle conoscenze un po’ più approfondite sullo stack. Ad esempio, per riordinare una risorsa in uno stack, devi conoscere gli id delle risorse su entrambi i lati del punto in cui vuoi che arrivi la risorsa di destinazione. Di solito, ciò significa che hai già recuperato l’intero stack.

Ambiti richiesti

Prima di iniziare questa guida, assicurati di avere un token che includa i seguenti ambiti:

Aggiunta di risorse agli stack di versioni

Passaggio 1: individua la destinazione

Il primo passaggio consiste nell’identificare quale dei due scenari principali si applica al tuo caso: aggiungere una risorsa a un’altra risorsa per creare uno stack oppure aggiungere una risorsa a uno stack esistente per estenderlo.

Se sai di lavorare con una risorsa senza controllo delle versioni o hai già un id dello stack di versioni, puoi andare al passaggio 2.

In caso contrario, il modo più semplice per determinare se una risorsa di destinazione fa già parte di uno stack è:

1. Recupera con GET la risorsa di destinazione tramite una chiamata a /v2/assets/:id​

2. Controlla il tipo (type) che viene restituito.

• Se è version_stack, l’uuid che hai appena controllato è il tuo uuid di destinazione.Vai al passaggio 2.

3. Se il tipo (type) è file, prendi il parent_id
4. Usa GET per recuperare l’elemento padre tramite lo stesso endpoint e controlla il suo tipo (type).

Se il type dell’elemento padre è version_stack, usa il suo id come destinazione. Se il type è un valore diverso, stai lavorando con una risorsa normale e puoi usare l’ID originale come destinazione.

Passaggio 2: prepara il payload

Ora che hai l’uuid di destinazione, devi conoscere l’uuid della risorsa che stai aggiungendo allo stack.

1. Se stai caricando una nuova risorsa, usa semplicemente l’ID restituito con la risposta di successo quando crei la risorsa.
2. Se stai creando impilando una risorsa esistente, dovresti poter ottenere l’id tramite il processo descritto sopra.

L’unico parametro del corpo richiesto per l’aggiunta di uno stack di versioni è next_asset_id:

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

Passaggio 3: aggiungi la risorsa di origine alla destinazione

Ora che hai entrambi i parametri di id della risorsa, puoi eseguire POST su /assets/:id/version, dove :id è la risorsa di destinazione o lo stack di versioni, mentre la risorsa di origine (nuova) è nel payload del corpo.

Riordinamento degli stack di versioni

Gli stack di versioni si basano su un concetto ordinale semplice in cui ogni risorsa ha dei vicini next_asset_id e prev_asset_id. L’ordine non si riferisce alla numerazione delle versioni, ma all’attributo index di ogni risorsa. L’index funziona in modo opposto ai numeri di versione, quindi di conseguenza:

• La prima versione (con numero più basso) nello stack ha una risorsa prev, ma nessuna risorsa next
• La versione più recente (con numero più alto) nello stack ha una risorsa next, ma nessuna risorsa prev
• Tutte le versioni “interne” hanno una risorsa sia prev che next, ovvero le risorse con ID versione superiore e inferiore, rispettivamente.

Si possono verificare, perciò, tre scenari distinti, tutti basati sulla stessa chiamata endpoint:

Chiamata:

PUT https://api.frame.io/v2/asset/:id/tween

Corpo:

1
{
2
  "prev_asset_id": "<asset_id>",
3
  "next_asset_id": "<asset_id>"
4
}

In tutti i casi, l’id nel percorso URL sarà la risorsa che stai spostando.

Rimozione di risorse ed eliminazione degli stack di versioni

Rimozione delle risorse

Quando una risorsa viene spostata in uno stack di versioni, diventa un elemento figlio dello stack stesso. Per spostare una risorsa fuori da uno stack di versioni, devi effettivamente riassegnarla come elemento padre nella cartella che contiene lo stack.

1. Usa GET per ottenere lo stack di versioni stesso tramite chiamata a /v2/assets/:id
2. Prendi il parent_id dello stack (che diventa il nuovo id della cartella di destinazione)
3. Sposta la risorsa di destinazione nella cartella come segue:

Chiamata:

POST https://api.frame.io/v2/assets/:parent_id/move

Corpo:

1
{
2
    "id":"<asset_id>"
3
}

Eliminazione degli stack di versioni

Eliminare uno stack di versioni è molto facile:

DELETE https://api.frame.io/v2/assets/:version_stack_id/unversion

Ecco fatto. L’eliminazione di uno stack riporterà tutte le risorse che lo compongono nella cartella che contiene lo stack.

Tutto questo è tecnicamente corretto: la versione singola verrà caricata e riprodotta, è possibile aggiungere nuove versioni e tutto continuerà normalmente. Per, al fine di evitare di presentare uno scenario confuso per gli utenti nelle applicazioni web e di altro tipo di Frame.io, consigliamo di eliminare gli stack singoli.

Per ulteriori informazioni sull’endpoint per gli stack di versioni, consulta la documentazione sulle risorse.