Gerenciar pilha de versões | Frame.io API Documentation

Visão geral

As pilhas de versões são um princípio organizacional no Frame.io que permite que os ativos sejam “empilhados” verticalmente sem serem colocados em pastas.As versões empilhadas facilitam a navegação de ativo para ativo na IU do Frame.io e oferecem suporte à revisão lado a lado.

No momento, não oferecemos suporte ao upload direto em uma pilha, portanto, a sequência da API para gerenciar o fluxo de trabalho básico da pilhas de versões seguirá a mesma sequência da IU do Frame.io:

Faça upload do ativo (opcional: marque como privado).
Atribua o ativo à pilha.

As pilhas de versões existentes podem ser reordenadas e versões individuais podem ser removidas de uma pilha.Por fim, as pilhas de versões podem ser excluídas sem excluir nenhum de seus ativos constituintes.

Todas as pilhas de versões têm um cover_asset

As pilhas de versões sempre terão um atributo chamado cover_asset_id no nível superior.Este é o id do ativo cuja miniatura é exibida na interface web do Frame.io e é a versão com número mais alto na pilha.

Conceitos principais

Pilhas de versões, assim como pastas, são tipos especiais de ativos.Você pode buscá-las com os mesmos pontos de acesso e, com base no valor da chave type na resposta da API, analisar e rotear adequadamente.Isso geralmente é simples na prática, mas pode apresentar algumas complicações ao gerenciar pilhas em grande escala.A chave para trabalhar com pilhas de versões é separar os quatro cenários mais comuns:

Um ativo pode ser adicionado a um ativo, o que criará uma pilha com um novo id.
Um ativo pode ser adicionado a uma pilha existente.
Uma pilha pode ser reordenada.
Versões individuais podem ser removidas.

Os dois primeiros cenários usam a mesma chamada de ponto de acesso, portanto, a única nuance real é saber se você está criando uma nova pilha (de dois ativos) ou adicionando seu ativo a uma pilha existente.Além disso, as restrições são previsíveis:

As pilhas devem corresponder ao asset_type (por exemplo, você não pode empilhar uma imagem em um fluxo).
O usuário ativo deve ter permissões para o ativo de origem e o ativo ou pilha de destino.
Empilhe ativos sequencialmente.
Não é possível empilhar uma pilha em uma pilha.
Pastas estão totalmente fora de questão.

Os dois últimos cenários também são bem simples, mas exigem saber um pouco mais sobre a pilha em si.Por exemplo, para reordenar um ativo em uma pilha, você precisará saber os ids dos ativos em ambos os lados de onde deseja que seu ativo de destino seja posicionado, e isso geralmente significa que você já buscou a pilha inteira.

Escopos obrigatórios

Antes de começar este guia, você precisará se certificar de que possui um token que inclua os seguintes escopos:

Escopo	Motivo
Ativos: Leitura, atualização	- Buscar ativos de origem e destino. - Adicionar um ativo a uma pilhas de versões. - Reordenar uma pilha. - Remover um ativo de uma pilha. - Excluir uma pilha.

Adicionar ativos às pilhas de versões

Etapa 1: localizar seu destino

A primeira etapa é identificar em qual dos dois cenários principais você se encontra: adicionar um ativo a outro ativo para criar uma pilha ou adicionar um ativo a uma pilha para ampliá-la.

Se você sabe que está trabalhando com um ativo sem versão, ou já tem um id da pilhas de versões, pode prosseguir para a Etapa 2.

Caso contrário, a maneira mais fácil de determinar se um ativo de destino já faz parte de uma pilha é:

Faça o GET do seu ativo de destino através de chamada para /v2/assets/:id
Verifique o type que retorna.

Se for version_stack, o uuid que você acabou de verificar é seu uuid de destino.Prossiga para a Etapa 2.

Se o type for file, pegue o parent_id
Faça o GET do principal por meio do mesmo ponto de acesso e verifique seu type.

Se o type do principal for version_stack, use o id como seu destino.Se o type for qualquer outra coisa, você está lidando com um ativo comum e pode usar o id original como seu destino.

Etapa 2: preparar seu conteúdo

Agora que você tem seu uuid de destino, precisa saber o uuid do ativo que está adicionando à pilha.

Se você estiver fazendo upload de um novo ativo, simplesmente use o id retornado com a resposta de sucesso quando você criar o ativo.
Se você estiver empilhando um ativo existente, você deve ter o id através do processo descrito acima.

O único parâmetro de corpo necessário para uma adição de pilha de versões é next_asset_id:

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

Etapa 3: adicionar seu ativo de origem ao destino

Agora que você tem ambos os parâmetros id do ativo, você está pronto para fazer POST para /assets/:id/version, onde o :id é seu ativo de destino ou pilhas de versões, e seu ativo de origem (novo) está no conteúdo do corpo.

Reordenar as pilhas de versões

As pilhas de versões dependem de um conceito ordinal simples de cada ativo ter vizinhos next_asset_id e prev_asset_id, onde a ordem se refere não à numeração da versão, mas ao atributo index de cada ativo.O index funciona oposto aos números de versão, então consequentemente:

A primeira versão (numerada mais baixa) na pilha tem um ativo prev, mas nenhum ativo next
A versão mais recente (numerada mais alta) na pilha tem um ativo next, mas nenhum ativo prev
Todas as versões “internas” têm um ativo prev e next, que são os ativos com IDs de versão mais altos e mais baixos, respectivamente.

Isso nos dá três cenários distintos, todos dependem da mesma chamada de ponto de acesso:

Chamada:

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

Corpo:

1 {
2   "prev_asset_id": "&lt;asset_id&gt;",
3   "next_asset_id": "&lt;asset_id&gt;"
4 }

Em todos os casos, o id no caminho do URL será o ativo que você está movendo.

Cenário	`prev_asset_id`	`next_asset_id`
Mover para o topo da pilha	`null`	`id` do ativo do topo anterior (número de versão mais alto).
Mover para o final da pilha	`id` do ativo final anterior (v1).	`null`
Mover versão dentro de uma pilha	`id` do ativo logo acima de onde você gostaria de mover seu ativo.	`id` do ativo logo abaixo de onde você gostaria de mover seu novo ativo.

Remover ativos e excluir pilhas de versões

Remover ativos

Quando um ativo é movido para uma pilhas de versões, ele se torna um filho da própria pilha.Para remover um ativo de uma pilha de versões, o que você precisa fazer é, na prática, reatribuir sua hierarquia de principal à pasta que contém a pilha.

GET a própria pilha de versões por meio de uma chamada para /v2/assets/:id
Obtenha o parent_id da própria pilha (que se tornará o id da sua nova pasta de destino)
Mova o ativo de destino para a pasta da seguinte forma:

Chamada:

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

Corpo:

1 {
2     "id":"&lt;asset_id&gt;"
3 }

Excluir pilhas de versões

Excluir uma pilhas de versões é extremamente simples:

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

Pronto.Excluir uma pilha retornará todos os ativos constituintes para a pasta que contém a pilha.

Pilhas de tamanho 1 devem ser excluídas

Se você remover todos os elementos de uma pilha de versões, você ficará com uma pilha de versões com um único elemento nela.Isso é fácil de identificar: se você GET a pilha de versões pelo id, verá que ela tem um atributo de "version": 1.

Tecnicamente, tudo isso está correto. A versão singleton será carregada e reproduzida, novas versões podem ser adicionadas e tudo continuará normalmente. No entanto, para evitar causar confusão aos usuários no site do Frame.io e em outros aplicativos, recomendamos excluir as pilhas singleton.

Para mais informações sobre o ponto de acesso da pilha de versões, consulte a documentação Ativos.

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

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