> This page is for Plataforma, version Herdado. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Herdado: 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. # 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. root-asset-id 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](https://support.frame.io/en/articles/6067-difference-between-team-members-vs-collaborators), 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` *Observação:* a imagem da conta retornada pela nossa API será uma chave S3 pré-assinada, então o URL retornado vai "expirar" depois de cerca de um dia.Para contornar isso, você deve buscar novamente a imagem toda vez que seu serviço carregar ou, idealmente, armazená-la localmente. 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. Embora seja improvável que um usuário faça parte de mais do que algumas contas, as equipes são um recurso que pode crescer rapidamente.Os limites de taxa da API do Frame.io são bastante altos, mas é sempre bom verificar os cabeçalhos de resposta e, se necessário, paginar. Você pode encontrar mais informações sobre paginação lendo [Paginação e erros](/docs/troubleshooting/troubleshooting).**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. Vamos rapidamente recapitular o que fizemos até agora: estabelecemos o contexto combinado de: | * 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` 1. Renderizar os nomes das pastas em uma lista 2. Quando um usuário clica em uma pasta, passe o id da pasta para a seguinte consulta: 2. `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](doc:managing-version-stacks), 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: ```json { "next_asset_id": "" } ```