资源

Frame.io 旧版 API 到 V4 迁移指南

前言

Frame.io V4 API 是对旧版 API 的重新设计，旧版 API 通常被称为 V2 端点 或 Frame.io V3 API。 此次重新设计充分利用了 Frame V4 的新功能和新特性，同时保留了旧版 API 的所有相关功能。 本指南概述了旧版 API 和 V4 API 之间的主要差异，并提供分步指导，帮助您顺利迁移。

迁移检查表

1

身份验证

对于尚未通过 Adobe Admin Console 管理的 V4 迁移帐户，您可以继续使用在 Frame.io 开发者网站中管理的旧版开发者令牌，但您需要在 API 请求中添加密钥为 x-frameio-legacy-token-auth、值为 true 的标头。 否则，您应按照下方身份验证部分中的步骤执行。

2

更新现有 API 调用

所有旧版 API 路由均将需要映射到新的 V4 API 路由和 JSON 负载。 下面有一个相当全面的映射表，可以协助完成这个过程。

3

强烈建议进行测试

彻底测试。 由于 API 有许多更改，建议使用 V4 帐户进行测试来确保新的 API 按照预期运行。

4

实施专用登录

由于 V4 使用单独的身份验证 URL，因此需要实施专用的登录方法。 V4 身份验证 URL 与旧版 API 不同，其不会在响应中返回尚未升级到 V4 的帐户，且应被视为单独的集成。

如果下面的映射表中未列出您有疑问的端点，请通过 support@frame.io 联系我们的支持团队获取更多信息。

Adobe Developer Console 管理的身份验证

对于通过 Adobe Developer Console 管理的 V4 迁移帐户，您需要将 V4 API 与 OAuth2.0 结合使用。 您将需要执行以下步骤。

1

创建 Adobe 项目

在 Adobe Developer Console 中创建项目，然后将 Frame.io 添加为产品。

2

选择身份验证类型

身份验证 有关详细信息，请参阅身份验证指南。 如果您的 V4 帐户尚未通过 Adobe Admin Console 进行管理，则可以跳过此步骤。 * 用户身份验证：使用客户端 ID 和/或客户端密钥连接到 Frame，并要求用户使用其用户名和密码登录。 * 服务器到服务器的身份验证：使用客户端 ID 和客户端密钥连接到 Frame，但不需要用户通过浏览器登录。

3

实施持有者身份验证

JWT 持有者身份验证：对于每个 API 请求，通过具有键 Authorization 和值 Bearer 的标头传递身份验证令牌<ims_access_token></ims_access_token>.

端点映射（旧版 API 到 V4）

如果您使用的是旧版开发者令牌身份验证，则需要在您的 API 请求中添加一个标头，其中键为 x-frameio-legacy-token-auth，值为 true。

协助迁移的一般事项：

1

负载

请求和响应负载可能有所不同。

2

团队 → 工作区

旧版 API 中的“团队”相当于 V4 中的“工作区”。

3

资产

旧版 API 中的“资产”现在在 V4 中分为“文件”、“文件夹”和“版本堆栈”。

4

权限

V4 中的权限和角色有所不同，这也改变了端点的结构。 在 V4 中，您拥有工作区和项目用户角色。 有关更多详细信息，请参阅管理用户权限。

1. 帐户与用户信息

方法旧版端点方法V4 端点注意
GET/v2/accounts
（获取用户帐户）		GET/v4/accounts
（列出帐户）		V4 可以返回用户能够访问的所有帐户。
GET/v2/accounts/{account_id}
（按 ID 获取帐户）		不适用不适用有关特定帐户的信息可以在列出帐户端点中找到。
GET/v2/me
（获取当前用户）		GET/v4/me
（用户详细信息）		获取当前用户的个人资料。
GET/v2/accounts/{account_id}/membership不适用不适用角色和权限通过工作区和项目权限进行处理。

2. 工作区（替换了团队端点）

方法旧版端点方法V4 端点注意
GET/v2/accounts/{account_id}/teams
（获取帐户上的所有团队）		GET/v4/accounts/{account_id}/workspaces
（列出工作区）		旧版 API 概念“团队” → V4 中的“工作区”。
POST/v2/accounts/{account_id}/teams
（为给定帐户创建团队）		POST/v4/accounts/{account_id}/workspaces
（创建工作区）		请求体相似（名称等）。 响应是工作区对象，而不是团队对象。
GET/v2/teams/{team_id}
（获取团队）		GET/v4/accounts/{account_id}/workspaces/{workspace_id}
（显示工作区）		团队 ID → V4 中的工作区 ID。
GET/v2/teams/{team_id}/members
（获取团队成员）		GET/v4/accounts/{account_id}/workspaces/{workspace_id}/users
（获取工作区成员）		返回工作区中的所有用户
POST/v2/teams/{team_id}/members
（添加团队成员）		PATCH/v4/accounts/{account_id}/workspaces/{workspace_id}/users/{user_id}
（在工作区中添加或更新用户角色）		允许在工作区中添加或移除用户
GET/v2/teams/{team_id}/membership
（获取团队用户成员身份）		不适用不适用角色和权限通过工作区和项目权限进行处理。

3. 项目

方法旧版端点方法V4 端点注意
GET/v2/teams/{team_id}/projects
（按团队获取项目）		GET/v4/accounts/{account_id}/workspaces/{workspace_id}/projects
（列出项目）		在 V4 中，必须同时提供 account_id 和 workspace_id。
GET/v2/projects/sharedGET/v4/accounts/{account_id}/invited_projects
（列出受邀项目）		仅列出受邀项目 /v4/accounts/{account_id}/projects 列出所有项目，包括受邀项目
POST/v2/teams/{team_id}/projects
（创建项目）		POST/v4/accounts/{account_id}/workspaces/{workspace_id}/projects
（创建项目）		请求体类似：{ &quot;name&quot;: &quot;MyProject&quot;, ... }。
GET/v2/projects/{project_id}
（按 ID 获取项目）		GET/v4/accounts/{account_id}/projects/{project_id}
（显示项目）		需要 account_id 和 project_id
PUT/v2/projects/{project_id}
（更新项目）		PATCH/v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}
（更新项目）		V4 使用 PATCH 进行部分更新。
DELETE/v2/projects/{project_id}
（按 ID 删除项目）		DELETE/v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}
（删除项目）		移除项目。
GET/v2/projects/{project_id}/collaborators
（获取项目协作者）		GET/v4/accounts/{account_id}/projects/{project_id}/users
（列出项目用户角色）		返回项目中的所有用户（与旧版协作者端点最接近一致）
POST/v2/projects/{project_id}/collaborators
（向项目添加协作者）		PATCH/v4/accounts/{account_id}/projects/{project_id}/users/{user_id}
（更新给定项目的用户角色）		允许在项目中添加或移除用户（与旧版协作者端点最接近一致）

4. 文件夹

方法旧版端点方法V4 端点注意
GET/v2/assets/{asset_id}/children
（获取次资产）		GET/v4/accounts/{account_id}/folders/{folder_id}/children
（列出文件夹次项）		如果旧版 API 中的 asset_id 是文件夹，那么现在在 V4 中就是 folder_id。
POST/v2/assets/{parent_asset_id}/children
（创建资产）		POST/v4/accounts/{account_id}/folders/{folder_id}/folders
（创建文件夹）		在旧版 API 中您使用了 &quot;type&quot;: &quot;folder&quot;，那么在 V4 中就使用 {&quot;data&quot;: {&quot;name&quot;: &quot;Folder name&quot;}}。
GET/v2/assets/{asset_id}
（获取资产）		GET/v4/accounts/{account_id}/folders/{folder_id}
（显示文件夹）		旧版 API 需要 “type”: “folder”
V4 API 需要路径参数中的 folder_id 和 account_id
PUT/v2/assets/{asset_id}（更新资产）PATCH/v4/accounts/{account_id}/folders/{folder_id}
（更新文件夹）		旧版 API：asset_id 将是您的文件夹 ID
V4 API：请求体：{&quot;data&quot;: {&quot;name&quot;: &quot;New Folder Name&quot;}}。
DELETE/v2/assets/{asset_id}
（删除资产）		DELETE/v4/accounts/{account_id}/folders/{folder_id}
（删除文件夹）		移除文件夹。
不适用不适用GET/v4/accounts/{account_id}/folders/{folder_id}/folders
（列出文件夹）		列出给定文件夹中的文件夹。 （从显示项目路由获取 root_folder_id，您可以使用此项来列出最高级别的所有文件夹。）

5. 版本堆栈

方法旧版端点方法V4 端点注意
POST/v2/assets/{destination_folder}/copy
（复制资产）		POST/v4/accounts/{account_id}/version_stacks/{version_stack_id}/copy
（复制版本堆栈）		旧版：路径中的目标文件夹；在请求中与版本堆栈一起使用。 V4：复制版本堆栈。
POST/v2/assets/{asset_id}/version
（对资产进行版本控制）		POST/v4/accounts/{account_id}/folders/{folder_id}/version_stacks
（创建版本堆栈）		创建版本堆栈。 请求体中需要有 2–10 个文件 ID。
POST/v2/assets/{asset_id}/version
（对资产进行版本控制）		PATCH/v4/accounts/{account_id}/files/{file_id}/move
（将文件移动到版本堆栈）		将文件移动到现有版本堆栈。 使用 version_stack_id 作为请求体中的 parent_id。
GET/v2/assets/{asset_id}/children
（获取次资产）		GET/v4/accounts/{account_id}/version_stacks/{version_stack_id}/children
（列出版本堆栈次项）		旧版：与版本堆栈 asset_id 一起使用。 V4：列出版本堆栈中的次项（文件/版本）。
不适用不适用GET/v4/accounts/{account_id}/folders/{folder_id}/version_stacks
（列出版本堆栈）		列出文件夹中的版本堆栈。
不适用不适用PATCH/v4/accounts/{account_id}/version_stacks/{version_stack_id}/move
（移动版本堆栈）		将版本堆栈移动到另一个文件夹。
GET/v2/assets/{asset_id}
（获取资产）		GET/v4/accounts/{account_id}/version_stacks/{version_stack_id}
（显示版本堆栈）		旧版：与版本堆栈 asset_id 一起使用。 V4：显示版本堆栈详细信息。
DELETE/v2/assets/{asset_id}/unversion（删除取消版本控制）不适用不适用V4 目前不支持取消版本控制。

6. 文件

注意：现在 V4 中有两个端点用于创建文件（本地和通过 S3 上传）。 有关更多详细信息，请参阅上传文件。

方法旧版端点方法V4 端点注意
POST/v2/assets/{parent_asset_id}/children
（创建资产）		POST/v4/accounts/{account_id}/folders/{folder_id}/files/local_upload
（创建文件（本地上传））		旧版 API：需要 name、type、filetype、filesize 和 auto_version_id
V4 API：路径参数中需要 account_id 和 folder_id，负载上需要 file_size 和 name
不适用不适用POST/v4/accounts/{account_id}/folders/{folder_id}/files/remote_upload
（创建文件（远程上传））		路径参数中需要 account_id 和 folder_id，负载上需要 source url 和 name
GET/v2/assets/{asset_id}
（获取资产）		GET/v4/accounts/{account_id}/files/{file_id}
（显示文件）		显示文件详细信息 - 许多包含项可用于在响应中返回其他文件详细信息。
不适用不适用GET/v4/accounts/{account_id}/files/{file_id}/status
（获取文件元数据）		从创建文件远程上传端点获取远程上传的状态。
PUT/v2/assets/{asset_id}
（更新资产）		PATCH/v4/accounts/{account_id}/files/{file_id}
（更新文件）		更新文件名称。
DELETE/v2/assets/{asset_id}
（删除资产）		DELETE/v4/accounts/{account_id}/files/{file_id}
（删除文件）		成功时返回 204 No Content。

7. 评论

目前支持大多数 V4 API 评论功能。

即将发布的特性：

  • 评论反应，例如表情符号
  • 查看或修改评论完成状态
  • 了解谁查看过评论（曝光量）

“timestamp”字段表示留下评论的帧戳（从 1 开始），而不是时间戳

方法旧版端点方法V4 端点注意
GET/v2/assets/{asset_id}/comments
（从评论线程获取所有评论和回复）		GET/v4/accounts/{account_id}/files/{file_id}/comments
（列出评论）		列出文件上的评论。
POST/v2/assets/{asset_id}/comments
（创建评论）		POST/v4/accounts/{account_id}/files/{asset_id}/comments
（创建评论）		创建评论。 请求体类似：{&quot;text&quot;:&quot;Nice&quot;,&quot;timestamp&quot;:12.3}。
GET/v2/comments/{comment_id}
（通过 ID 获取评论）		GET/v4/accounts/{account_id}/comments/{comment_id}
（显示评论）		通过 ID 获取单个评论。
PUT/v2/comments/{comment_id}
（更新评论）		PATCH/v4/accounts/{account_id}/comments/{comment_id}
（更新评论）		更新文本、时间等。
DELETE/v2/comments/{comment_id}
（删除评论）		DELETE/v4/accounts/{account_id}/comments/{comment_id}
（删除评论）		移除评论。
GET/v2/comments/{comment_id}/impressions
（获取曝光量）		不适用不适用V4 当前不支持曝光量。

8. 共享项（审阅链接/演示文稿）

在 Frame V4 中，共享链接不再分为审阅链接和演示文稿链接。 在 V4 中，现在可以配置不同的样式来设置分享链接，匹配审阅或演示文稿体验。

注意：不支持通过 V4 API 与旧版审阅链接和演示文稿进行交互。

方法旧版端点方法V4 端点注意
GET/v2/projects/{project_id}/review_links
（列出项目中的审阅链接）		GET/v4/accounts/{account_id}/projects/{project_id}/shares
（列出共享项）		列出项目中的共享项（注意，这不包括旧版审阅链接和演示文稿）
POST/v2/projects/{project_id}/review_links
（创建审阅链接）		POST/v4/accounts/{account_id}/projects/{project_id}/shares
（创建共享项）		创建新的共享链接。 请求体可能是 {&quot;data&quot;:{&quot;name&quot;:&quot;Review Link&quot;,&quot;type&quot;:&quot;review&quot;}}。
POST/v2/review_links/{link_id}/assets
（将资产添加到审阅链接）		POST/v4/accounts/{account_id}/shares/{share_id}/assets
（将新资产添加到共享项）		将资产添加到共享项。 支持文件、文件夹和版本堆栈。
不适用不存在DELETE/v4/accounts/{account_id}/shares/{share_id}/assets/{asset_id}
（删除共享）		从共享中移除资产
DELETE/v2/review_links/{link_id}
（删除审阅链接）		DELETE/v4/accounts/{account_id}/shares/{share_id}
（删除共享项）		删除共享链接。
PUT/v2/review_links/{review_link_id}
（更新审阅链接）		PATCH/v4/accounts/{account_id}/shares/{share_id}
（更新共享项）		更新共享链接

9. Webhook

您在 V3 中使用的 Webhook 将被迁移，且在大部分情况下功能保持不变。 迁移时它们将被禁用，需要启用后才能正常使用。 资产事件需要进行一些更改，现在分为文件和文件夹。 需要注意一些新的 V4 特定事件：metadata.value.updated、收藏集相关事件和共享相关事件。

方法旧版端点方法V4 端点注意
POST/v2/teams/{team_id}/hooks
（创建 Webhook）		POST/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks
（创建 Webhook）		提供 {&quot;data&quot;:{&quot;url&quot;:&quot;...&quot;,&quot;events&quot;:[&quot;file.created&quot;,...]}}。
GET/v2/accounts/{account_id}/webhooks
（获取帐户的 Webhook）		GET/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks
（列出 Webhook）		获取工作区的所有 Webhook。 注意：要获取帐户的所有 Webhook，您需要先获取该帐户的所有工作区，然后获取这些工作区的所有 Webhook。
GET/v2/hooks/{hook_id}
（获取 Webhook）		GET/v4/accounts/{account_id}/webhooks/{webhook_id}
（列出 Webhook）		获取 Webhook 信息
PUT/v2/hooks/{hook_id}
（更新 Webhook）		PATCH/v4/accounts/{account_id}/webhooks/{webhook_id}
（更新 Webhook）		更新 Webhook 设置
DELETE/v2/hooks/{hook_id}
（删除 Webhook）		DELETE/v4/accounts/{account_id}/webhooks/{webhook_id}
（删除 Webhook）		移除 Webhook。

10. 自定义操作

您在 V3 中使用的自定义操作将被迁移，但将需要对请求和响应处理进行一些修改。 迁移时它们将被禁用，需要启用后才能正常使用。 有关更多详细信息，请参阅此（文档）

注意：自定义操作端点目前处于实验性 API 中，需要标头：“api-version: experimental”。

方法旧版端点方法V4 端点注意
POST/v2/teams/{team_id}/actions（创建自定义操作）POST/v4/accounts/{account_id}/workspaces/{workspace_id}/actions（创建自定义操作）在工作区中创建自定义操作。
DELETE/v2/actions/{action_id}（删除自定义操作）DELETE/v4/accounts/{account_id}/actions/{action_id}（删除自定义操作）删除自定义操作。
PUT/v2/actions/{action_id}（更新自定义操作）PATCH/v4/accounts/{account_id}/actions/{action_id}（更新自定义操作）更新自定义操作详细信息。
GET/v2/teams/{team_id}/actions（获取团队的自定义操作）GET/v4/accounts/{account_id}/workspaces/{workspace_id}/actions（列出自定义操作）列出给定工作区中的自定义操作。
GET/v2/actions/{action_id}（通过 ID 获取自定义操作）GET/v4/accounts/{account_id}/actions/{action_id}（显示自定义操作详细信息）显示自定义操作详细信息。

迁移步骤

1

调整不支持的 V2 端点

调整任何不支持的旧版 V2 端点。

2

更新基础 URL

更新基础 URL，从 api.frame.io/v2/... 改为 api.frame.io/v4/...。

3

更新 API 请求

更新代码中的 API 请求，以引用新的端点架构。

4

更新 JSON 负载

更新请求/响应架构的 JSON 负载，确保您生成和使用正确的字段。

5

更新术语

更新术语：在您的代码和前端中，“团队” → “工作区”；“资产” → “文件/文件夹”；“审阅链接”或“演示文稿链接” → “共享项”。

6

测试端点

测试所有新更新的端点。 如果遇到 403、404、422 错误，请确认端点、请求负载形式等。

7

解析错误响应

解析新的详细错误响应，如果您的 API 调用失败，请在 {&quot;errors&quot;: [...]} JSON 响应中查找问题。

8

部署到生产环境

使用 V4 Frame.io 帐户验证后，即可部署到生产环境。

错误处理和常见问题

某些路由会给出自定义错误描述，这些描述可能与以下示例略有不同。

客户端错误 (4xx)
  • 400 错误请求：检查负载准确性。 * 401 未授权：授权令牌无效或缺失。 * 403 禁止访问：缺少权限范围或用户没有访问权限。 * 404 未找到：确认端点、API 版本或 ID。 * 422 实体无法处理：验证请求数据 * 429 请求过多：实施有退避机制的重试。
服务器错误 (5xx)
  • 500 内部服务器错误：短暂延迟后重试。

SDK 支持

与旧版 SDK 类似，开发者可以使用 Python SDK，且首次提供了 Typescript SDK。 这些 SDK 的功能相似，但方法完全不同。如果您要从旧版 SDK 更新到 V4 SDK，请务必相应地更新您的代码。 您可以在以下链接中找到它们：

快速入门 SDK Python SDK Typescript SDK