Leitura da árvore de arquivos

Visão geral

Seja a meta final a publicação, edição ou passagem de ativos por um estágio do fluxo de trabalho, muitas integrações mais profundas com o Frame.io envolvem listar o contexto do usuário e, por fim, uma visualização de diretório.

Esta é a hierarquia básica de recursos (ou arquivos) no Frame.io:

Conta > Equipe > Projeto > Ativos

Este artigo explica como interagir com a árvore de arquivos fazendo chamadas de API sequenciais.Uma estratégia comum para trabalhar com arquivos é primeiro acessar um projeto, listar as pastas e depois trabalhar com os ativos e pilhas de versão contidos nelas.

Conceitos importantes

Todo projeto tem um ativo raiz exclusivo

APIs RESTful normalmente descrevem recursos usando identificadores exclusivos; o root_asset_id é o identificador exclusivo da árvore de ativos do seu projeto.Trate-o como uma estrutura especial que atua como o nó raiz de um projeto: os ativos restantes se empilham abaixo da raiz em uma árvore descendente.

Em fluxos de trabalho comuns, os usuários da API precisam descer pela árvore para interagir com ativos mais profundos na hierarquia de arquivos.

Usuários colaboradores e projetos compartilhados

Um usuário colaborador é uma das principais funções de usuário no Frame.io: esses usuários têm acesso a um espaço de trabalho do projeto, mas podem não pertencer à conta abrangente desse projeto.Deixando de lado as permissões distintas para usuários colaboradores e membros da equipe, a principal diferença é que a assinatura de um usuário colaborador é estritamente a um projeto e pode não ter relação com uma equipe.

Isso cria um pequeno problema para fluxos de trabalho em que as listas de diretórios são fundamentais.Embora a hierarquia básica acima (Conta > Equipe > Projeto > Ativos) deva funcionar para a maioria dos casos de uso, ela não descreverá os projetos onde um usuário autenticado é um usuário colaborador, mas não um membro da equipe.Para contornar isso ao listar diretórios, você pode:

• Buscar os projetos compartilhados de um usuário, descompactar a hierarquia de equipe e conta e juntar tudo, ou
• Buscar os projetos compartilhados de um usuário e listá-los todos juntos como um contexto separado.

Qualquer método funciona; o último é um pouco mais fácil, mas o primeiro fica mais próximo de como o aplicativo web do Frame.io apresenta informações similares.De qualquer forma, os métodos abordados neste guia se aplicam a ambos.

Listar um diretório

1. Buscar as contas do usuário

GET https://api.frame.io/v2/accounts

Faça a chamada acima com um token bearer válido para obter as contas de um usuário.Você receberá todas as contas nas quais o usuário tem status de membro da equipe, gerente da equipe ou administrador.Você também pode receber equipes para as quais um usuário tem direitos de faturamento/administrador, mas sem acesso à equipe, mas isso é raro e será eliminado na próxima etapa.

O conteúdo para a solicitação de contas é bastante detalhado. Aqui está um resumo dos dados importantes que você pode querer obter da resposta:

• id
• display_name
• owner (email, name)
• (opcionalmente) image

Observe que id e owner.email são os únicos campos obrigatórios em uma conta de usuário.Se você estiver exibindo usuários em outro aplicativo, considere escrever lógica condicional para apresentar contas de usuário.Nossa recomendação é verificar e, se não for null, exibir a conta com a seguinte ordem de preferência:

1. “display_name”
2. “Conta de owner.name”
3. “Conta de owner.email”

Depois que seu usuário escolher uma conta, você provavelmente vai querer apresentar equipes, o que exige uma solicitação adicional de API.

2. Buscar equipes dentro da conta

GET https://api.frame.io/v2/accounts/{{account_id}}/teams As equipes no Frame.io podem ser “públicas” (ou seja, detectáveis por qualquer membro da equipe na conta) ou “privadas” (detectáveis apenas por membros específicos da equipe).A API vai lidar com o contexto para você, então tudo que você precisa fazer é uma chamada válida especificando o account_id na solicitação acima.

Você pode encontrar mais informações sobre paginação lendo Paginação e erros.De cada equipe, obtenha os seguintes atributos:

• id
• name
• (opcionalmente) team_image

Quando uma equipe é selecionada, você desejará exibir os projetos que a constituem.

Observação: se desejar, você também pode fazer uma chamada GET https://api.frame.io/v2/teams para um usuário, e nossa API retornará cada equipe à qual um usuário pertence, independentemente do contexto da conta.Embora isso tecnicamente funcione, você corre o risco de perder seu contexto, a menos que tome outra medida para:

1. Restabelecer o contexto refletindo o nome da conta ao lado de cada equipe
2. Permitir que o usuário faça pesquisa no texto da lista

Se você está listando projetos compartilhados do nível da conta para baixo, você desejará fazer uma chamada adicional para GET https://api.frame.io/v2/projects/shared.Cada projeto retornado na resposta conterá os seguintes atributos, que você pode levar adiante conforme criar seu diretório:

• id (do próprio projeto)
• team_id
• team.account_id

Como alternativa, você pode criar uma provisão para “Projetos compartilhados” simplesmente adicionando-os como uma “equipe” em qualquer contexto de conta escolhido.Se você decidir fazer isso, é útil para o usuário final separar visualmente os projetos compartilhados dos projetos reais no âmbito da equipe, já que a lista única de projetos compartilhados pode incluir, nos bastidores, muitos contextos diferentes de contas e equipes.

3. Buscar os projetos da equipe

GET https://api.frame.io/v2/teams/{{team_id}}/projects

Em seguida, faça a chamada acima e busque todos os projetos dentro da equipe.

Para cada projeto, você desejará obter:

• id
• name
• root_asset_id
• (opcionalmente) private, caso você queira diferenciar para o usuário em sua interface

Como explicado no início do artigo, root_asset_id é uma parte importante da arquitetura de recursos do Frame.io, pois permite navegar pelo diretório de arquivos e pastas dentro de um projeto.

| * Conta

| * Equipe

| * Projetos em equipe (e root_asset_ids)

| * Projetos compartilhados (e root_asset_ids)

| E isso é tudo que precisamos para criar ou buscar ativos.

Listar pastas e ativos

4. Criar a estrutura inicial de pastas

GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder Isso listará todas as pastas de um projeto, começando pelo root_asset_id.Se não houver pastas, você receberá uma lista em branco.Se quiser incluir arquivos e pastas (por exemplo, se a próxima etapa fosse fazer uma chamada GET de um ativo do Frame.io, simplesmente omita o parâmetro da string de consulta.

As outras duas opções de filtro disponíveis para o parâmetro type são file e version_stack.Todos os três filtros são mutuamente exclusivos, e uma chamada não filtrada retornará todos os três tipos misturados.

5. Percorrer a árvore de diretórios

Para cada pasta retornada, você precisa capturar:

• id
• name

Como cada pasta é um ativo, o fluxo de trabalho para navegar por uma estrutura de pastas será assim:

1. GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder

2. Renderizar os nomes das pastas em uma lista

3. Quando um usuário clica em uma pasta, passe o id da pasta para a seguinte consulta:

4. GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder

6. Criar e fazer upload

Em uma pasta: POST https://api.frame.io/v2/{{folder_id}}/children Após ter o id da pasta na qual deseja fazer upload, simplesmente faça um POST para a pasta filha, conforme a documentação do recurso e o guia.Isso criará um ativo de espaço reservado e (dependendo do método escolhido), retornará:

• Um uuid destinado a casos de uso de rastreamento
• Uma lista de upload_urls que pode usar para fazer PUT do arquivo diretamente no armazenamento de dados back-end do Frame.io.

Em uma pilha de versões: as pilhas de versões apresentam um fluxo de trabalho similar, com uma etapa adicional abordada neste guia, resumida abaixo.Os pontos principais são lembrar que uma pilha de versões é um contêiner que parece um ativo, mas se comporta como uma pasta, e que você precisa fazer upload do ativo primeiro e depois empilhá-lo na pilha de versões como ações separadas.Portanto, se quiser fazer upload de um ativo em uma pilha de versões, será necessário:

• O id da pilha de versões
• O parent_id da pilha de versões (por exemplo, sua pasta contêiner ou raiz do projeto)

Primeiro, POST https://api.frame.io/v2/assets/{{parent_id}}/children para criar o novo ativo.Capture o novo id na resposta.Agora, você pode usar o id do novo ativo e POST https://api.frame.io/v2/assets/{{version_stack_id}}/version, com um conteúdo de corpo de:

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