Guía de migración de la API heredada de Frame.io a V4
Guía de migración de la API heredada de Frame.io a V4
Introducción
La API V4 de Frame.io es un nuevo diseño de la API heredada, a menudo denominada puntos finales V2 o API V3 de Frame.io. El nuevo diseño aprovecha al máximo las nuevas capacidades y funciones de Frame V4, a la vez que mantiene toda la funcionalidad relevante de la API heredada. Esta guía describe las principales diferencias entre las API heredada y V4, y proporciona instrucciones paso a paso para facilitar la migración.
Lista de comprobación de la migración
Autenticación
En el caso de las cuentas migradas a V4 que aún no se administran mediante Adobe Admin Console, puede seguir usando tokens de desarrollador heredados gestionados en el sitio para desarrolladores de Frame.io, pero deberá añadir un encabezado a las solicitudes de API con la clave x-frameio-legacy-token-auth y el valor true. De lo contrario, siga los pasos de la sección Autenticación que aparece a continuación.
Actualizar llamadas de API existentes
Todas las rutas de la API heredada deberán asignarse a las nuevas rutas de la API V4 y a sus cargas útiles JSON. A continuación, se incluye una tabla de asignación bastante completa como ayuda para este proceso.
Se recomienda realizar pruebas
Realice pruebas exhaustivas. Dado que la API incluye muchos cambios, se recomienda hacer pruebas con una cuenta V4 para asegurarse de que la nueva API funcione según lo previsto.
Implementación de un inicio de sesión específico
Implemente un método de inicio de sesión independiente para V4, ya que usa URL de autenticación distintas. La URL de autenticación de V4 es distinta de la de la API heredada y no devolverá en la respuesta las cuentas que aún no se hayan actualizado a V4, por lo que debe tratarse como una integración independiente.
Si hay algún punto final que no figure en la tabla de asignación siguiente y sobre el que tenga alguna pregunta, póngase en contacto con nuestro equipo de asistencia en support@frame.io para obtener más información.
Autenticación gestionada por Adobe Developer Console
En el caso de las cuentas migradas a V4 que se gestionan mediante Adobe Developer Console, deberá usar la API V4 con OAuth 2.0. Siga los pasos que se indican a continuación.
Crear un proyecto de Adobe
Cree un proyecto en Adobe Developer Console y añada Frame.io como producto.
Elegir el tipo de autenticación
Autentíquese. Consulte la Guía de autenticación para obtener más información. Si la cuenta V4 aún no se gestiona mediante Adobe Admin Console, puede omitir este paso. * Autenticación de usuario: Se conecta a Frame mediante un ID de cliente o un secreto de cliente, y requiere que un usuario inicie sesión con su nombre de usuario y contraseña. * Autenticación de servidor a servidor: Se conecta a Frame mediante un ID de cliente y un secreto de cliente, pero no requiere que un usuario intervenga para iniciar sesión mediante un explorador.
Asignaciones de puntos finales (API heredada a V4)
Si utiliza la autenticación con token de desarrollador heredado, deberá añadir un encabezado a las solicitudes de API con la clave x-frameio-legacy-token-auth y el valor true.
Notas generales para facilitar la migración:
Permisos
Los permisos y las funciones son diferentes en V4, lo que cambia la estructura de los puntos finales. En V4, existen funciones de usuario de espacio de trabajo y de proyecto. Para obtener más información, consulte Gestión de permisos de usuario.
1. Cuentas e información de usuario
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| GET | /v2/accounts (Get Accounts for User) | GET | /v4/accounts (List accounts) | V4 devuelve todas las cuentas a las que puede acceder el usuario. |
| GET | /v2/accounts/{account_id} (Get Account by ID) | N/A | N/A | La información sobre una cuenta específica se puede encontrar en el punto final Mostrar cuentas. |
| GET | /v2/me (Get Current User) | GET | /v4/me (User details) | Obtenga el perfil del usuario actual. |
| GET | /v2/accounts/{account_id}/membership | N/A | N/A | Las funciones y permisos se gestionan mediante permisos de espacio de trabajo y de proyecto. |
2. Workspaces (sustituyen los puntos finales de Teams)
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| GET | /v2/accounts/{account_id}/teams (Get all Teams on an Account) | GET | /v4/accounts/{account_id}/workspaces (List workspaces) | Teams en la API heredada → Workspaces en V4. |
| POST | /v2/accounts/{account_id}/teams (Create a Team for the given account) | POST | /v4/accounts/{account_id}/workspaces (Create workspace) | El cuerpo es similar (nombre, etc.) La respuesta es un objeto de espacio de trabajo, no un objeto de equipo. |
| GET | /v2/teams/{team_id} (Get a Team) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id} (Show Workspace) | ID de Team → ID de Workspace en V4. |
| GET | /v2/teams/{team_id}/members (Get Team Members) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/users (Get Workspace Members) | Devuelve todos los usuarios en un espacio de trabajo |
| POST | /v2/teams/{team_id}/members (Add a Team Member)) | PATCH | /v4/accounts/{account_id}/workspaces/{workspace_id}/users/{user_id} (Add Or Update User Role In Workspace) | Permite añadir o eliminar usuarios de un espacio de trabajo |
| GET | /v2/teams/{team_id}/membership (Get user membership for team) | N/A | N/A | Las funciones y permisos se gestionan mediante permisos de espacio de trabajo y de proyecto. |
3. Proyectos
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| GET | /v2/teams/{team_id}/projects (Get Projects by Team) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects (List Projects) | Debe proporcionar tanto account_id como workspace_id en V4. |
| GET | /v2/projects/shared | GET | /v4/accounts/{account_id}/invited_projects (List Invited Projects) | Lists invited projects only /v4/accounts/{account_id}/projects enumera todos los proyectos, incluidos los proyectos invitados |
| POST | /v2/teams/{team_id}/projects (Create a Project) | POST | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects (Create project) | El cuerpo es similar: { "name": "MyProject", ... }. |
| GET | /v2/projects/{project_id} (Get Project by ID) | GET | /v4/accounts/{account_id}/projects/{project_id} (Show project) | Requiere account_id y project_id |
| PUT | /v2/projects/{project_id} (Update a Project) | PATCH | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id} (Update project) | V4 usa PATCH para actualizaciones parciales. |
| DELETE | /v2/projects/{project_id} (Delete Project by ID) | DELETE | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id} (Delete Project) | Elimina el proyecto. |
| GET | /v2/projects/{project_id}/collaborators (Get Project Collaborators) | GET | /v4/accounts/{account_id}/projects/{project_id}/users (List project user roles) | Devuelve todos los usuarios de un proyecto (el equivalente más cercano al extremo heredado de colaboradores) |
| POST | /v2/projects/{project_id}/collaborators (Add a Collaborator to a Project) | PATCH | /v4/accounts/{account_id}/projects/{project_id}/users/{user_id} (Update user roles for the given project) | Permite añadir usuarios a un proyecto o quitarlos de él (equivalente más cercano al punto final heredado de colaboradores) |
4. Carpetas
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| GET | /v2/assets/{asset_id}/children (Fetch child Assets) | GET | /v4/accounts/{account_id}/folders/{folder_id}/children (List folder children) | Si su asset_id en la API heredada era una carpeta, ahora es folder_id en V4. |
| POST | /v2/assets/\{parent_asset_id}/children <br />(Create an Asset) | POST | /v4/accounts/\{account_id}/folders/\{folder_id}/folders <br />(Create folder) | En la API heredada se usaba "type": "folder"; en V4, use {“data”: \{"name": "Folder name"}}. |
| GET | /v2/assets/{asset_id} (Get an Asset) | GET | /v4/accounts/{account_id}/folders/{folder_id} (Show folder) | La API heredada requiere “type”: “folder”; la API V4 requiere folder_id y account_id en los parámetros de ruta |
| PUT | /v2/assets/{asset_id} (Update an Asset) | PATCH | /v4/accounts/{account_id}/folders/{folder_id} (Update folder) | API heredada: asset_id será el ID de la carpeta. API V4: cuerpo: {"data": {"name": "New Folder Name"}}. |
| DELETE | /v2/assets/{asset_id} (Delete an Asset) | DELETE | /v4/accounts/{account_id}/folders/{folder_id} (Delete folder) | Elimina la carpeta. |
| N/A | N/A | GET | /v4/accounts/{account_id}/folders/{folder_id}/folders (List folders) | Muestra las carpetas en una carpeta determinada. (Obtenga root_folder_id de la ruta para mostrar el proyecto y puede usarlo para mostrar todas las carpetas del nivel superior). |
5. Pilas de versiones
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| POST | /v2/assets/{destination_folder}/copy (Copy an Asset) | POST | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/copy (Copy version stack) | Heredada: carpeta de destino en la ruta; úsela con una pila de versiones en la solicitud. V4: copie una pila de versiones. |
| POST | /v2/assets/{asset_id}/version (Version an Asset) | POST | /v4/accounts/{account_id}/folders/{folder_id}/version_stacks (Create version stack) | Crear una pila de versiones. Requiere de 2 a 10 ID de archivo en el cuerpo de la solicitud. |
| POST | /v2/assets/{asset_id}/version (Version an Asset) | PATCH | /v4/accounts/{account_id}/files/{file_id}/move (Move file to version stack) | Mueva un archivo a una pila de versiones existente. Use version_stack_id como parent_id en el cuerpo de la solicitud. |
| GET | /v2/assets/{asset_id}/children (Fetch child Assets) | GET | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/children (List version stack children) | Heredada: úselo con un asset_id de pila de versiones. V4: muestra los elementos secundarios (archivos o versiones) de una pila de versiones. |
| N/A | N/A | GET | /v4/accounts/{account_id}/folders/{folder_id}/version_stacks (List version stacks) | Muestre las pilas de versiones en una carpeta. |
| N/A | N/A | PATCH | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/move (Move version stack) | Mueva la pila de versiones a otra carpeta. |
| GET | /v2/assets/{asset_id} (Get an Asset) | GET | /v4/accounts/{account_id}/version_stacks/{version_stack_id} (Show version stack) | Heredada: úselo con un asset_id de pila de versiones. V4: muestre los detalles de la pila de versiones. |
| DELETE | /v2/assets/{asset_id}/unversion (Delete unversion) | N/A | N/A | La desvinculación de versiones no se admite actualmente en V4. |
6. Archivos
Nota: Ahora hay dos puntos finales para crear archivos en V4 (de forma local y mediante carga en S3). Para obtener más información, consulte Carga de archivos.
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| POST | /v2/assets/{parent_asset_id}/children (Create an Asset) | POST | /v4/accounts/{account_id}/folders/{folder_id}/files/local_upload (Create file (local upload)) | API heredada: requiere name, type, filetype, filesize y auto_version_id API V4: account_id y folder_id son obligatorios en los parámetros de ruta, y file_size y name son obligatorios en la carga útil |
| N/A | N/A | POST | /v4/accounts/{account_id}/folders/{folder_id}/files/remote_upload (Create file (remote upload)) | account_id y folder_id son obligatorios en los parámetros de ruta, y source_url y name son obligatorios en la carga útil |
| GET | /v2/assets/{asset_id} (Get an Asset) | GET | /v4/accounts/{account_id}/files/{file_id} (Show file) | Muestre los detalles del archivo. Hay muchos elementos include disponibles para devolver detalles adicionales del archivo en la respuesta. |
| N/A | N/A | GET | /v4/accounts/{account_id}/files/{file_id}/status (Get file metadata) | Obtenga el estado de una carga remota desde un punto final de creación de archivo mediante carga remota. |
| PUT | /v2/assets/{asset_id} (Update an Asset) | PATCH | /v4/accounts/{account_id}/files/{file_id} (Update file) | Actualice el nombre del archivo. |
| DELETE | /v2/assets/{asset_id} (Delete an Asset) | DELETE | /v4/accounts/{account_id}/files/{file_id} (Delete file) | 204 No Content si se completa correctamente. |
7. Comentarios
Actualmente se admiten la mayoría de las funciones de comentarios de la API V4.
Funciones próximamente disponibles:
- Reacciones a comentarios, es decir, emojis.
- Visualización o modificación del estado de finalización de comentarios.
- Visualización de quién ha visto un comentario (impresiones).
El campo “timestamp” representa la marca de fotograma en la que se deja el comentario (empezando por 1), no la marca de tiempo
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| GET | /v2/assets/{asset_id}/comments (Get all the Comments and Replies from a Comment thread) | GET | /v4/accounts/{account_id}/files/{file_id}/comments (List comments) | Enumera los comentarios de un archivo. |
| POST | /v2/assets/{asset_id}/comments (Create a Comment) | POST | /v4/accounts/{account_id}/files/{asset_id}/comments (Create comment) | Cree un comentario. El cuerpo es similar: {"text":"Nice","timestamp":12.3}. |
| GET | /v2/comments/{comment_id} (Get a Comment by ID) | GET | /v4/accounts/{account_id}/comments/{comment_id} (Show comment) | Obtenga un comentario individual por ID. |
| PUT | /v2/comments/{comment_id} (Update a Comment) | PATCH | /v4/accounts/{account_id}/comments/{comment_id} (Update comment) | Actualice el texto, la hora, etc. |
| DELETE | /v2/comments/{comment_id} (Delete a Comment) | DELETE | /v4/accounts/{account_id}/comments/{comment_id} (Delete comment) | Elimine un comentario. |
| GET | /v2/comments/{comment_id}/impressions (Get Impressions) | N/A | N/A | Las impresiones no se admiten actualmente en V4. |
8. Elementos de uso compartido (vínculos de revisión/presentaciones)
En Frame V4, los enlaces de uso compartido ya no se dividen entre enlaces de revisión y presentaciones. En V4, ahora el enlace de uso compartido se puede configurar con distintos estilos para adaptarse a la experiencia de revisión o presentación.
Nota: No se admite la interacción con vínculos de revisión ni presentaciones heredados mediante la API V4.
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| GET | /v2/projects/{project_id}/review_links (List Review Links in a project) | GET | /v4/accounts/{account_id}/projects/{project_id}/shares (List shares) | Enumera los elementos de uso compartido de un proyecto (tenga en cuenta que esto no incluye los vínculos de revisión ni las presentaciones heredados) |
| POST | /v2/projects/{project_id}/review_links (Create a Review Link)) | POST | /v4/accounts/{account_id}/projects/{project_id}/shares (Create share) | Crea un nuevo enlace de uso compartido. El cuerpo puede ser {"data":{"name":"Review Link","type":"review"}}. |
| POST | /v2/review_links/{link_id}/assets (Add Asset to a Review Link) | POST | /v4/accounts/{account_id}/shares/{share_id}/assets (Add new asset to share) | Añade un activo al elemento de uso compartido. Es compatible con archivos, carpetas y pilas de versiones. |
| N/D | No existe | DELETE | /v4/accounts/{account_id}/shares/{share_id}/assets/{asset_id} (Delete Share) | Elimine el activo del elemento de uso compartido |
| DELETE | /v2/review_links/{link_id} (Delete a Review Link) | DELETE | /v4/accounts/{account_id}/shares/{share_id} (Delete Share) | Elimine el vínculo del elemento de uso compartido. |
| PUT | /v2/review_links/{review_link_id} (Update a Review Link) | PATCH | /v4/accounts/{account_id}/shares/{share_id} (Update Share) | Actualice el enlace de uso compartido |
9. Webhooks
Los webhooks que usaba en V3 se migrarán y, en general, funcionarán del mismo modo. Tras la migración, estarán desactivados y deberá activarlos para que funcionen. Será necesario realizar algunos cambios en los eventos de activos, que ahora se dividen en archivos y carpetas. También hay algunos eventos específicos de V4 nuevos que conviene tener en cuenta: metadata.value.updated, los eventos relacionados con colecciones y los eventos relacionados con elementos de uso compartido.
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| POST | /v2/teams/{team_id}/hooks (Create Webhook) | POST | /v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks (Create Webhook) | Proporcione {"data":{"url":"...","events":["file.created",...]}}. |
| GET | /v2/accounts/{account_id}/webhooks (Get Webhooks for and Account) | GET | /v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks (List Webhooks) | Obtiene todos los webhooks de un espacio de trabajo. Nota: Para obtener todos los webhooks de una cuenta, debe obtener todos los espacios de trabajo de la cuenta y, a continuación, todos los webhooks de esos espacios de trabajo. |
| GET | /v2/hooks/{hook_id} (Get Webhook) | GET | /v4/accounts/{account_id}/webhooks/{webhook_id} (List Webhooks) | Obtenga información del webhook |
| PUT | /v2/hooks/{hook_id} (Update Webhook) | PATCH | /v4/accounts/{account_id}/webhooks/{webhook_id} (Update Webhook) | Actualice la configuración del webhook |
| DELETE | /v2/hooks/{hook_id} (Delete Webhook) | DELETE | /v4/accounts/{account_id}/webhooks/{webhook_id} (Delete Webhook) | Elimina el webhook. |
10. Acciones personalizadas
Las acciones personalizadas que usaba en V3 se migrarán, pero requerirán algunos cambios en las solicitudes y en la gestión de respuestas. Tras la migración, estarán desactivados y deberá activarlos para que funcionen. Para obtener más información, consulte este (documento)
Nota: los puntos finales de acciones personalizadas se encuentran actualmente en la API experimental y requieren un encabezado: “api-version: experimental”.
| Método | Punto final heredado | Método | Punto final V4 | Notas |
|---|---|---|---|---|
| POST | /v2/teams/{team_id}/actions (Create a Custom Action) | POST | /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (Create Custom Action) | Cree una acción personalizada en un espacio de trabajo. |
| DELETE | /v2/actions/{action_id} (Delete a Custom Action) | DELETE | /v4/accounts/{account_id}/actions/{action_id} (Delete Custom Action) | Elimine una acción personalizada. |
| PUT | /v2/actions/{action_id} (Update a Custom Action) | PATCH | /v4/accounts/{account_id}/actions/{action_id} (Update Custom Action) | Actualice los detalles de una acción personalizada. |
| GET | /v2/teams/{team_id}/actions (Get Custom Actions for a Team) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (List Custom Actions) | Enumere las acciones personalizadas en un espacio de trabajo determinado. |
| GET | /v2/actions/{action_id} (Get a Custom Action by ID) | GET | /v4/accounts/{account_id}/actions/{action_id} (Show Custom Action Details) | Muestre los detalles de una acción personalizada. |
Pasos de migración
Ajuste de puntos finales V2 no compatibles
Ajuste cualquier punto final V2 heredado que no sea compatible.
Actualización de solicitudes de API
Actualice las solicitudes API del código para que hagan referencia al nuevo esquema de puntos finales.
Actualización de cargas útiles JSON
Actualice las cargas útiles JSON de los esquemas de solicitud y respuesta para asegurarse de generar y consumir los campos correctos.
Actualización de terminología
Actualice la terminología en el código y en el front-end: teams → workspaces; assets → files/folders; review links o presentation links → shares.
Prueba de puntos finales
Pruebe todos los puntos finales recién actualizados. Si aparece un error 403, 404 o 422, confirme los puntos finales, la forma de la carga útil de la solicitud, etc.
Análisis de respuestas de error
Analice las nuevas respuestas de error detalladas y busque el problema en la respuesta JSON {"errors": [...]} si falla la llamada de API.
Implementación en producción
Implemente en producción después de validar con una cuenta V4 de Frame.io.
Gestión de errores y problemas comunes
Algunas rutas generan errores con descripciones personalizadas que pueden diferir ligeramente de los ejemplos siguientes.
- 400 Bad Request: Compruebe la precisión de la carga útil. * 401 Unauthorized: Token de autorización no válido o ausente. * 403 Forbidden: Falta el ámbito o el usuario no tiene acceso. * 404 Not Found: Confirme el pnto final, la versión de la API o los ID. * 422 Unprocessable Entity: Valide los datos de la solicitud. * 429 Too Many Requests: Implemente reintentos con espera.
- 500 Internal Server Error: Vuelva a intentarlo tras una breve espera.
Compatibilidad con SDK
Al igual que el SDK heredado, hay un SDK para Python disponible para desarrolladores y, por primera vez, también hay un SDK para TypeScript. Estos SDK tienen una funcionalidad similar, pero utilizan métodos completamente distintos. Si va a actualizar del SDK heredado al SDK V4, asegúrese de actualizar el código según corresponda. Puede encontrarlos en los vínculos siguientes:
Introducción a SDK SDK para Python SDK para Typescript