Guia de migração da API Frame.io Legacy para a V4
Guia de migração da API Frame.io Legacy para a V4
Introdução
A API Frame.io V4 é uma reformulação da API Legacy, frequentemente chamada de pontos de acesso V2 ou API Frame.io V3. A reformulação aproveita ao máximo os novos recursos e funcionalidades do Frame V4, mantendo todas as funcionalidades relevantes da API Legacy. Este guia descreve as principais diferenças entre as APIs Legacy e V4 e fornece orientações passo a passo para ajudar você a migrar sem problemas.
Lista de verificação de migração
Autenticação
Para contas migradas para a V4 que ainda não são administradas pelo Adobe Admin Console, você pode continuar usando tokens de desenvolvedor legados gerenciados no site de desenvolvedores do Frame.io, mas precisará adicionar um cabeçalho às solicitações de API com a chave x-frameio-legacy-token-auth e o valor true. Caso contrário, siga as etapas na seção Autenticação abaixo.
Atualizar chamadas de API existentes
Todas as rotas da API legada precisarão ser mapeadas para as novas rotas e conteúdos JSON da API V4. Há uma tabela de mapeamento bastante abrangente abaixo para auxiliar neste processo.
Se houver um ponto de acesso não listado na tabela de mapeamento abaixo sobre o qual você tenha dúvidas, entre em contato com nossa equipe de suporte em support@frame.io para obter mais informações.
Autenticação gerenciada pelo Adobe Developer Console
Para contas migradas para V4 que são gerenciadas através do Adobe Developer Console, você precisará usar a API V4 com OAuth2.0. Você precisará seguir as etapas abaixo.
Escolher tipo de autenticação
**Autenticar.**Consulte o Guia de autenticação para obter mais informações. Se sua conta V4 ainda não for gerenciada pelo Adobe Admin Console, você pode pular esta etapa. * Autenticação de usuário: conecta-se ao Frame usando um Client ID e/ou Client Secret, e exige que um usuário faça logon com nome de usuário e senha. * Autenticação de servidor para servidor: conecta-se ao Frame usando Client ID e Client Secret, mas não exige que um usuário faça logon em um navegador.
Mapeamentos de pontos de acesso (API Legacy para V4)
Se você estiver usando autenticação por token de desenvolvedor legado, será necessário adicionar um cabeçalho às solicitações de API com a chave x-frameio-legacy-token-auth e o valor true.
Observações gerais para ajudar na migração:
Ativos
“Ativos” na API Legacy agora são divididos em “Arquivos”, “Pastas” e “Pilhas de versões” na V4.
Permissões
Permissões e funções são diferentes na V4, o que altera a estrutura dos pontos de acesso. Na V4, há funções de usuário de espaço de trabalho e projeto. Para mais detalhes, consulte Gerenciar permissões de usuário.
1. Contas e informações do usuário
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| GET | /v2/accounts(Obter contas para usuário) | GET | /v4/accounts(Listar contas) | A V4 retorna todas as contas que o usuário pode acessar. |
| GET | /v2/accounts/{account_id}(Obter conta por ID) | N/D | N/D | As informações sobre uma conta específica podem ser encontradas no ponto de acesso Listar contas. |
| GET | /v2/me(Obter usuário atual) | GET | /v4/me(Detalhes do usuário) | Buscar perfil do usuário atual. |
| GET | /v2/accounts/{account_id}/membership | N/D | N/D | Funções e permissões são tratadas por meio de permissões de espaço de trabalho e projeto. |
2. Espaços de trabalho (substituem pontos de acesso de Equipe)
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| GET | /v2/accounts/{account_id}/teams(Obter todas as equipes em uma conta) | GET | /v4/accounts/{account_id}/workspaces(Listar espaços de trabalho) | Conceito de “equipes” da API Legacy -> “espaços de trabalho” na V4. |
| POST | /v2/accounts/{account_id}/teams(Criar uma Equipe para determinada conta) | POST | /v4/accounts/{account_id}/workspaces(Criar espaço de trabalho) | O corpo é semelhante (nome, etc.). A resposta é um objeto de espaço de trabalho, não um objeto de equipe. |
| GET | /v2/teams/{team_id}(Obter uma equipe) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}(Mostrar espaço de trabalho) | ID da equipe → ID do espaço de trabalho na V4. |
| GET | /v2/teams/{team_id}/members(Obter membros da equipe) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/users(Obter membros do Espaço de trabalho) | Retorna todos os usuários em um espaço de trabalho |
| POST | /v2/teams/{team_id}/members(Adicionar um membro da equipe)) | PATCH | /v4/accounts/{account_id}/workspaces/{workspace_id}/users/{user_id}(Adicionar ou atualizar função do usuário no espaço de trabalho) | Permite adicionar ou remover usuários de um espaço de trabalho |
| GET | /v2/teams/{team_id}/membership(Obter assinatura de usuário para equipe) | N/D | N/D | Funções e permissões são tratadas por meio de permissões de espaço de trabalho e projeto. |
3. Projetos
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| GET | /v2/teams/{team_id}/projects(Obter projetos por Equipe) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects(Listar projetos) | É necessário fornecer account_id e workspace_id no V4. |
| GET | /v2/projects/shared | GET | /v4/accounts/{account_id}/invited_projects(Listar projetos convidados) | Lista somente projetos convidados /v4/accounts/{account_id}/projects todos os projetos, incluindo projetos convidados |
| POST | /v2/teams/{team_id}/projects(Criar um projeto) | POST | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects(Criar projeto) | O corpo é semelhante: { "name": "MyProject", ... }. |
| GET | /v2/projects/{project_id}(Obter Projeto por ID) | GET | /v4/accounts/{account_id}/projects/{project_id}(Mostrar projeto) | Exige account_id e project_id |
| PUT | /v2/projects/{project_id}(Atualizar um Projeto) | PATCH | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}(Atualizar projeto) | A V4 usa PATCH para atualizações parciais. |
| DELETE | /v2/projects/{project_id}(Excluir projeto por ID) | DELETE | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}(Excluir projeto) | Remove o projeto. |
| GET | /v2/projects/{project_id}/collaborators(Obter colaboradores do projeto) | GET | /v4/accounts/{account_id}/projects/{project_id}/users(Listar funções de usuário do projeto) | Retorna todos os usuários em um projeto (equivalente mais próximo ao ponto de acesso legado de colaboradores) |
| POST | /v2/projects/{project_id}/collaborators(Adicionar colaborador a um projeto) | PATCH | /v4/accounts/{account_id}/projects/{project_id}/users/{user_id}(Atualizar funções de usuário para o projeto especificado) | Permite adicionar ou remover usuários de um projeto (equivalente mais próximo ao ponto de acesso legado de colaboradores) |
4. Pastas
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| GET | /v2/assets/{asset_id}/children(Buscar ativos de tarefas derivadas) | GET | /v4/accounts/{account_id}/folders/{folder_id}/children(Listar tarefas derivadas da pasta) | Se o asset_id na API Legacy era uma pasta, agora é folder_id na V4. |
| POST | /v2/assets/{parent_asset_id}/children(Criar um ativo) | POST | /v4/accounts/{account_id}/folders/{folder_id}/folders(Criar pasta) | Na API Legacy, você usava "type": "folder", in V4 you do {"data": {"name": "Folder name"}}. |
| GET | /v2/assets/{asset_id}(Obter um ativo) | GET | /v4/accounts/{account_id}/folders/{folder_id}(Mostrar pasta) | A API Legacy exige “type”: “folder” V4 API requires folder_id & account_id nos parâmetros de caminho |
| PUT | /v2/assets/{asset_id} (Atualizar um ativo) | PATCH | /v4/accounts/{account_id}/folders/{folder_id}(Atualizar pasta) | API Legacy: asset_id será o ID da sua pasta. API V4: Corpo: {"data": {"name": "New Folder Name"}}. |
| DELETE | /v2/assets/{asset_id}(Excluir um ativo) | DELETE | /v4/accounts/{account_id}/folders/{folder_id}(Excluir pasta) | Remove pasta. |
| N/D | N/D | GET | /v4/accounts/{account_id}/folders/{folder_id}/folders(Listar pastas) | Lista pastas em determinada pasta. (Obtenha root_folder_id pela rota Mostrar projeto e use isso para listar todas as pastas no nível mais alto.) |
5. Pilhas de versões
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| POST | /v2/assets/{destination_folder}/copy(Copiar um ativo) | POST | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/copy(Copiar pilha de versões) | Legacy: pasta de destino no caminho; use com uma pilha de versões na solicitação. V4: copia uma pilha de versões. |
| POST | /v2/assets/{asset_id}/version(Versionar um ativo) | POST | /v4/accounts/{account_id}/folders/{folder_id}/version_stacks(Criar pilha de versões) | Criar pilha de versões. Exige de 2 a 10 IDs de arquivo no corpo da solicitação. |
| POST | /v2/assets/{asset_id}/version(Versionar um ativo) | PATCH | /v4/accounts/{account_id}/files/{file_id}/move(Mover arquivo para pilha de versões) | Move um arquivo para uma pilha de versões existente. Use o version_stack_id como parent_id no corpo da solicitação. |
| GET | /v2/assets/{asset_id}/children(Buscar ativos de tarefas derivadas) | GET | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/children(Listar tarefas derivadas da pilha de versões) | Legacy: use com um asset_id de pilha de versões. V4: listar tarefas derivadas (arquivos/versões) em uma pilha de versões. |
| N/D | N/D | GET | /v4/accounts/{account_id}/folders/{folder_id}/version_stacks(Listar pilhas de versões) | Lista pilhas de versões em uma pasta. |
| N/D | N/D | PATCH | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/move(Mover pilha de versões) | Move uma pilha de versões para outra pasta. |
| GET | /v2/assets/{asset_id}(Obter um ativo) | GET | /v4/accounts/{account_id}/version_stacks/{version_stack_id}(Mostrar pilha de versões) | Legacy: use com um asset_id de pilha de versões. V4: mostra detalhes da pilha de versões. |
| DELETE | /v2/assets/{asset_id}/unversion (Excluir remoção de versão) | N/D | N/D | No momento, a remoção de versão não é compatível com a V4. |
6. Arquivos
Observação: agora há dois pontos de acesso para criar arquivos na V4 (localmente e por upload via S3). Para obter mais detalhes, consulte Fazer upload de arquivos.
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| POST | /v2/assets/{parent_asset_id}/children(Criar um ativo) | POST | /v4/accounts/{account_id}/folders/{folder_id}/files/local_upload(Criar arquivo (fazer upload local)) | API Legacy: exige name, type, filetype, filesize e auto_version_id. API V4: account_id e folder_id são obrigatórios nos parâmetros de caminho, e file_size e name são obrigatórios no conteúdo |
| N/D | N/D | POST | /v4/accounts/{account_id}/folders/{folder_id}/files/remote_upload(Criar arquivo (fazer upload remoto)) | Account_id e folder_id são obrigatórios nos parâmetros de caminho, e source url e name são obrigatórios no conteúdo |
| GET | /v2/assets/{asset_id}(Obter um ativo) | GET | /v4/accounts/{account_id}/files/{file_id}(Mostrar arquivo) | Mostra detalhes do arquivo - vários includes estão disponíveis para retornar detalhes adicionais do arquivo na resposta. |
| N/D | N/D | GET | /v4/accounts/{account_id}/files/{file_id}/status(Obter metadados do arquivo) | Obtém o status de um upload remoto a partir de um ponto de acesso. |
| PUT | /v2/assets/{asset_id}(Atualizar um ativo) | PATCH | /v4/accounts/{account_id}/files/{file_id}(Atualizar arquivo) | Atualizar nome do arquivo. |
| DELETE | /v2/assets/{asset_id}(Excluir um ativo) | DELETE | /v4/accounts/{account_id}/files/{file_id}(Excluir arquivo) | 204 No Content em caso de sucesso. |
7. Comentários
No momento, a maioria dos recursos de comentários da API V4 é compatível.
Recursos disponíveis em breve:
- Reações a comentários, ou seja, emojis
- Visualizar ou modificar o status de conclusão do comentário
- Ver quem visualizou um comentário (impressões)
O campo “carimbo de data e hora” representa o framestamp em que o comentário é deixado (começando em 1), não o carimbo de data e hora
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| GET | /v2/assets/{asset_id}/comments(Obter todos os comentários e respostas de uma thread de comentário) | GET | /v4/accounts/{account_id}/files/{file_id}/comments(Listar comentários) | Lista comentários em um arquivo. |
| POST | /v2/assets/{asset_id}/comments(Criar um comentário) | POST | /v4/accounts/{account_id}/files/{asset_id}/comments(Criar comentário) | Criar um comentário. O corpo é semelhante: {"text":"Nice","timestamp":12.3}. |
| GET | /v2/comments/{comment_id}(Obter um comentário por ID) | GET | /v4/accounts/{account_id}/comments/{comment_id}(Mostrar comentário) | Buscar comentário único por ID. |
| PUT | /v2/comments/{comment_id}(Atualizar um comentário) | PATCH | /v4/accounts/{account_id}/comments/{comment_id}(Atualizar comentário) | Atualizar texto, horário etc. |
| DELETE | /v2/comments/{comment_id}(Excluir um comentário) | DELETE | /v4/accounts/{account_id}/comments/{comment_id}(Excluir comentário) | Remover comentário. |
| GET | /v2/comments/{comment_id}/impressions(Obter impressões) | N/D | N/D | As impressões não são compatíveis atualmente na V4. |
8. Compartilhamentos (Links de revisão/Apresentações)
No Frame V4, os links de compartilhamento não são mais divididos entre links de revisão e links de apresentação. Na V4, o link de compartilhamento agora pode ser configurado com estilos diferentes para corresponder à experiência de revisão ou apresentação.
Observação: não há suporte para interação com links de revisão e apresentações legados pela API V4.
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| GET | /v2/projects/{project_id}/review_links(Listar link de revisão em um projeto) | GET | /v4/accounts/{account_id}/projects/{project_id}/shares(Listar compartilhamentos) | Lista compartilhamentos em um projeto (observe que isso não inclui links de revisão e apresentações legados) |
| POST | /v2/projects/{project_id}/review_links(Criar um link de revisão)) | POST | /v4/accounts/{account_id}/projects/{project_id}/shares(Criar compartilhamento) | Cria um novo link de compartilhamento. O corpo pode ser {"data":{"name":"Review Link","type":"review"}}. |
| POST | /v2/review_links/{link_id}/assets(Adicionar ativo a um link de revisão) | POST | /v4/accounts/{account_id}/shares/{share_id}/assets(Adicionar novo ativo ao compartilhamento) | Adiciona ativo a um compartilhamento. Isso é compatível com arquivos, pastas e pilhas de versões. |
| N/D | Não existe | DELETE | /v4/accounts/{account_id}/shares/{share_id}/assets/{asset_id}(Excluir compartilhamento) | Remover ativo do compartilhamento |
| DELETE | /v2/review_links/{link_id}(Excluir um link de revisão) | DELETE | /v4/accounts/{account_id}/shares/{share_id}(Excluir compartilhamento) | Exclui o link de compartilhamento. |
| PUT | /v2/review_links/{review_link_id}(Atualizar um link de revisão) | PATCH | /v4/accounts/{account_id}/shares/{share_id}(Atualizar compartilhamento) | Atualiza o link de compartilhamento |
9. Webhooks
Os webhooks usados na V3 serão migrados e, em grande parte, funcionarão da mesma forma. Na migração, eles serão desativados e precisarão ser ativados para funcionar. Algumas alterações serão necessárias para eventos de ativo, que agora são divididos em arquivos e pastas. Há alguns novos eventos específicos da V4 que devem ser observados: metadata.value.updated, eventos relacionados a coleções e eventos relacionados a compartilhamentos.
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| POST | /v2/teams/{team_id}/hooks(Criar webhook) | POST | /v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks(Criar webhook) | Forneça {"data":{"url":"...","events":["file.created",...]}}. |
| GET | /v2/accounts/{account_id}/webhooks(Obter webhooks de uma conta) | GET | /v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks(Listar webhooks) | Obtém todos os webhooks de um espaço de trabalho. Observação: para obter todos os webhooks de uma conta, é necessário obter todos os espaços de trabalho da conta e depois obter todos os webhooks desses espaços de trabalho. |
| GET | /v2/hooks/{hook_id}(Obter webhook) | GET | /v4/accounts/{account_id}/webhooks/{webhook_id}(Listar webhooks) | Obter informações do webhook |
| PUT | /v2/hooks/{hook_id}(Atualizar webhook) | PATCH | /v4/accounts/{account_id}/webhooks/{webhook_id}(Atualizar webhook) | Atualiza as configurações do webhook |
| DELETE | /v2/hooks/{hook_id}(Excluir webhook) | DELETE | /v4/accounts/{account_id}/webhooks/{webhook_id}(Excluir webhook) | Remove o webhook. |
10. Ações personalizadas
As ações personalizadas usadas na V3 serão migradas, mas exigirão algumas modificações nas solicitações e no processamento de respostas. Na migração, eles serão desativados e precisarão ser ativados para funcionar. Para mais detalhes, consulte este (documento)
Observação: os pontos de acesso de ações personalizadas estão atualmente na API experimental e exigirão um cabeçalho: “api-version: experimental”.
| Método | Ponto de acesso Legacy | Método | Ponto de acesso V4 | Observações |
|---|---|---|---|---|
| POST | /v2/teams/{team_id}/actions (Criar uma ação personalizada) | POST | /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (Criar ação personalizada) | Cria uma ação personalizada em um espaço de trabalho. |
| DELETE | /v2/actions/{action_id} (Excluir uma ação personalizada) | DELETE | /v4/accounts/{account_id}/actions/{action_id} (Excluir ação personalizada) | Excluir uma ação personalizada. |
| PUT | /v2/actions/{action_id} (Atualizar uma ação personalizada) | PATCH | /v4/accounts/{account_id}/actions/{action_id} (Atualizar ação personalizada) | Atualizar detalhes da ação personalizada. |
| GET | /v2/teams/{team_id}/actions (Obter ações personalizadas para uma equipe) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (Listar ações personalizadas) | Lista Ações personalizadas em determinado Espaço de trabalho. |
| GET | /v2/actions/{action_id} (Obter uma ação personalizada por ID) | GET | /v4/accounts/{account_id}/actions/{action_id} (Expandir detalhes de ação personalizada) | Expandir detalhes de ação personalizada. |
Etapas da migração
Ajustar pontos de acesso V2 não compatíveis
Ajuste Ajuste todos os pontos de acesso Legacy V2 sem suporte.
Atualizar solicitações de API
Atualize as solicitações de API no código para referenciar o esquema dos novos pontos de acesso.
Atualizar cargas JSON
Atualize as cargas JSON dos esquemas de solicitação/resposta para garantir que você esteja produzindo e consumindo os campos corretos.
Atualizar terminologia
Atualize a terminologia: “teams” → “workspaces”; “assets” → “files/folders”; “review links” ou “presentation links” → “shares” no código e no front-end.
Testar pontos de acesso
Teste todos os pontos de acesso recém-atualizados. Se vir 403, 404 ou 422, confirme os pontos de acesso, o formato do conteúdo da solicitação etc.
Tratamento de erros e problemas comuns
Algumas rotas geram erros com descrições personalizadas que podem diferir ligeiramente dos exemplos abaixo.
- 400 Solicitação inválida: verifique a precisão do conteúdo. * 401 Não autorizado: token de autorização inválido ou ausente. * 403 Proibido: escopo ausente ou usuário sem acesso. * 404 Não encontrado: confirme o ponto de acesso, a versão da API ou os IDs. * 422 Entidade não processável: valide os dados da solicitação * 429 Muitas solicitações: implemente nova tentativa com backoff.
- 500 Erro interno do servidor: tentar novamente após uma breve pausa.
Suporte a SDK
Semelhante ao SDK Legacy, há um SDK para Python disponível para desenvolvedores, e, pela primeira vez, também há um SDK para TypeScript disponível. Esses SDKs terão funcionalidade semelhante, mas métodos completamente diferentes. Se você estiver atualizando do SDK Legacy para o SDK V4, atualize o código adequadamente. Você pode encontrá-los nos links abaixo:
Introdução a SDKsSDK para PythonSDK para TypeScript