> This page is for 平台, version V4 (default). > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 实验版: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - 旧版: 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. # Frame.io 旧版 API 到 V4 迁移指南 ## 前言 Frame.io V4 API 是对旧版 API 的重新设计，旧版 API 通常被称为 *V2 端点* 或 *Frame.io V3 API*。 此次重新设计充分利用了 Frame V4 的新功能和新特性，同时保留了旧版 API 的所有相关功能。 本指南概述了旧版 API 和 V4 API 之间的主要差异，并提供分步指导，帮助您顺利迁移。 ## 迁移检查表 #### 身份验证 对于尚未通过 Adobe Admin Console 管理的 V4 迁移帐户，您可以继续使用在 [Frame.io 开发者网站](/)中管理的旧版开发者令牌，但您需要在 API 请求中添加密钥为 `x-frameio-legacy-token-auth`、值为 `true` 的标头。 否则，您应按照下方[身份验证](#adobe-developer-console-managed-authentication)部分中的步骤执行。 #### 更新现有 API 调用 所有旧版 API 路由均将需要映射到新的 V4 API 路由和 JSON 负载。 下面有一个相当全面的[映射](#endpoint-mappings-legacy-api-to-v4)表，可以协助完成这个过程。 #### 强烈建议进行测试 **彻底测试。** 由于 API 有许多更改，建议使用 V4 帐户进行测试来确保新的 API 按照预期运行。 #### 实施专用登录 由于 V4 使用单独的身份验证 URL，因此需要实施专用的登录方法。 V4 身份验证 URL 与旧版 API 不同，其不会在响应中返回尚未升级到 V4 的帐户，且应被视为单独的集成。 > **Note** > > 如果下面的映射表中未列出您有疑问的端点，请通过 [support@frame.io](mailto:support@frame.io) 联系我们的支持团队获取更多信息。 ## Adobe Developer Console 管理的身份验证 对于通过 [Adobe Developer Console](https://developer.adobe.com/developer-console/) 管理的 V4 迁移帐户，您需要将 V4 API 与 OAuth2.0 结合使用。 您将需要执行以下步骤。 #### 创建 Adobe 项目 **在 Adobe Developer Console 中创建项目**，然后将 Frame.io 添加为产品。 #### 选择身份验证类型 **身份验证** 有关详细信息，请参阅[身份验证指南](https://developer.adobe.com/frameio/guides/Authentication/)。 如果您的 V4 帐户尚未通过 Adobe Admin Console 进行管理，则可以跳过此步骤。 \* **用户身份验证**：使用客户端 ID 和/或客户端密钥连接到 Frame，并要求用户使用其用户名和密码登录。 \* **服务器到服务器的身份验证**：使用客户端 ID 和客户端密钥连接到 Frame，但不需要用户通过浏览器登录。 #### 实施持有者身份验证 **JWT 持有者身份验证**：对于每个 API 请求，通过具有键 `Authorization` 和值 `Bearer 的标头传递身份验证令牌`. ## 端点映射（旧版 API 到 V4） > **Note** > > 如果您使用的是旧版开发者令牌身份验证，则需要在您的 API 请求中添加一个标头，其中键为 x-frameio-legacy-token-auth，值为 true。 协助迁移的一般事项： #### 负载 请求和响应负载可能有所不同。 #### 团队 → 工作区 旧版 API 中的“团队”相当于 V4 中的“工作区”。 #### 资产 旧版 API 中的“资产”现在在 V4 中分为“文件”、“文件夹”和“版本堆栈”。 #### 权限 V4 中的权限和角色有所不同，这也改变了端点的结构。 在 V4 中，您拥有工作区和项目用户角色。 有关更多详细信息，请参阅[管理用户权限](/platform/v4/docs/guides/managing-user-permissions)。 ### 1. 帐户与用户信息 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ------- | ------------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------ | ---------------------- | | **GET** | `/v2/accounts` （[获取用户帐户](/platform/v2/api-reference/accounts/get-accounts)） | **GET** | `/v4/accounts` （[列出帐户](/platform/v4/api-reference/accounts/index)） | V4 可以返回用户能够访问的所有帐户。 | | **GET** | `/v2/accounts/{account_id}` （[按 ID 获取帐户](/platform/v2/api-reference/accounts/get-account)） | 不适用 | 不适用 | 有关特定帐户的信息可以在列出帐户端点中找到。 | | **GET** | `/v2/me` （[获取当前用户](/platform/v2/api-reference/users/get-me)） | **GET** | `/v4/me` （[用户详细信息](/platform/v4/api-reference/users/show)） | 获取当前用户的个人资料。 | | **GET** | `/v2/accounts/{account_id}/membership` | 不适用 | 不适用 | 角色和权限通过工作区和项目权限进行处理。 | ### 2. 工作区（替换了团队端点） | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | -------- | -------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | **GET** | `/v2/accounts/{account_id}/teams` （[获取帐户上的所有团队](/platform/v2/api-reference/teams/get-teams-by-account)） | **GET** | `/v4/accounts/{account_id}/workspaces` （[列出工作区](/platform/v4/api-reference/workspaces/index)） | 旧版 API 概念“团队” → V4 中的“工作区”。 | | **POST** | `/v2/accounts/{account_id}/teams` （[为给定帐户创建团队](/platform/v2/api-reference/teams/create-team)） | **POST** | `/v4/accounts/{account_id}/workspaces` （[创建工作区](/platform/v4/api-reference/workspaces/create)） | 请求体相似（名称等）。 响应是工作区对象，而不是团队对象。 | | **GET** | `/v2/teams/{team_id}` （[获取团队](/platform/v2/api-reference/teams/get-team)） | **GET** | `/v4/accounts/{account_id}/workspaces/{workspace_id}` （[显示工作区](/platform/v4/api-reference/workspaces/show)） | 团队 ID → V4 中的工作区 ID。 | | **GET** | `/v2/teams/{team_id}/members` （[获取团队成员](/platform/v2/api-reference/teams/get-team-members)） | **GET** | `/v4/accounts/{account_id}/workspaces/{workspace_id}/users` [（获取工作区成员）](/platform/v4/api-reference/workspace-permissions/index) | 返回工作区中的所有用户 | | **POST** | `/v2/teams/{team_id}/members` （[添加团队成员](/platform/v2/api-reference/teams/add-team-member)） | **PATCH** | `/v4/accounts/{account_id}/workspaces/{workspace_id}/users/{user_id}` （[在工作区中添加或更新用户角色](/platform/v4/api-reference/workspace-permissions/workspace-user-roles-update)） | 允许在工作区中添加或移除用户 | | **GET** | `/v2/teams/{team_id}/membership` （[获取团队用户成员身份](/platform/v2/api-reference/teams/get-membership-by-team)） | 不适用 | 不适用 | 角色和权限通过工作区和项目权限进行处理。 | ### 3. 项目 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ---------- | ----------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **GET** | `/v2/teams/{team_id}/projects` （[按团队获取项目](/platform/v2/api-reference/projects/get-projects-by-team)） | **GET** | `/v4/accounts/{account_id}/workspaces/{workspace_id}/projects` （[列出项目](/platform/v4/api-reference/projects/index)） | 在 V4 中，必须同时提供 `account_id` 和 `workspace_id`。 | | **GET** | `/v2/projects/shared` | **GET** | `/v4/accounts/{account_id}/invited_projects` （[列出受邀项目](https://next.developer.frame.io/platform/api-reference/projects/invited-projects-index)） | 仅列出受邀项目 `/v4/accounts/{account_id}/projects` 列出所有项目，包括受邀项目 | | **POST** | `/v2/teams/{team_id}/projects` （[创建项目](/platform/v2/api-reference/projects/create-project)） | **POST** | `/v4/accounts/{account_id}/workspaces/{workspace_id}/projects` （[创建项目](/platform/v4/api-reference/projects/create)） | 请求体类似：`{ "name": "MyProject", ... }`。 | | **GET** | `/v2/projects/{project_id}` （[按 ID 获取项目](/platform/v2/api-reference/projects/get-project)） | **GET** | `/v4/accounts/{account_id}/projects/{project_id}` （[显示项目](/platform/v4/api-reference/projects/show)） | 需要 `account_id` 和 `project_id` | | **PUT** | `/v2/projects/{project_id}` （[更新项目](/platform/v2/api-reference/projects/update-project)） | **PATCH** | `/v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}` （[更新项目](/platform/v4/api-reference/projects/update)） | V4 使用 PATCH 进行部分更新。 | | **DELETE** | `/v2/projects/{project_id}` [（按 ID 删除项目）](/platform/v2/api-reference/projects/delete-project) | **DELETE** | `/v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id}` [（删除项目）](/platform/v4/api-reference/projects/delete) | 移除项目。 | | **GET** | `/v2/projects/{project_id}/collaborators` （[获取项目协作者](/platform/v2/api-reference/projects/get-project-collaborators)） | **GET** | `/v4/accounts/{account_id}/projects/{project_id}/users` （[列出项目用户角色](/platform/v4/api-reference/project-permissions/index)） | 返回项目中的所有用户（与旧版协作者端点最接近一致） | | **POST** | `/v2/projects/{project_id}/collaborators` （[向项目添加协作者](/platform/v2/api-reference/projects/add-collaborator-to-project)） | **PATCH** | `/v4/accounts/{account_id}/projects/{project_id}/users/{user_id}` （[更新给定项目的用户角色](/platform/v4/api-reference/project-permissions/project-user-roles-update)） | 允许在项目中添加或移除用户（与旧版协作者端点最接近一致） | ### 4. 文件夹 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ---------- | ------------------------------------------------------------------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **GET** | `/v2/assets/{asset_id}/children` （[获取次资产](/platform/v2/api-reference/assets/get-assets)） | **GET** | `/v4/accounts/{account_id}/folders/{folder_id}/children` （[列出文件夹次项](/platform/v4/api-reference/folders/index)） | 如果旧版 API 中的 `asset_id` 是文件夹，那么现在在 V4 中就是 `folder_id`。 | | **POST** | `/v2/assets/{parent_asset_id}/children` （[创建资产](/platform/v2/api-reference/assets/create-asset)） | **POST** | `/v4/accounts/{account_id}/folders/{folder_id}/folders` （[创建文件夹](/platform/v4/api-reference/folders/create)） | 在旧版 API 中您使用了 `"type": "folder"`，那么在 V4 中就使用 `{"data": {"name": "Folder name"}}`。 | | **GET** | `/v2/assets/{asset_id}` （[获取资产](/platform/v2/api-reference/assets/get-asset)） | **GET** | `/v4/accounts/{account_id}/folders/{folder_id}` （[显示文件夹](/platform/v4/api-reference/folders/show)） | 旧版 API 需要 "type": "folder" V4 API 需要路径参数中的 `folder_id` 和 `account_id` | | **PUT** | `/v2/assets/{asset_id}`（[更新资产](/platform/v2/api-reference/assets/update-asset)） | **PATCH** | `/v4/accounts/{account_id}/folders/{folder_id}` （[更新文件夹](/platform/v4/api-reference/folders/update)） | 旧版 API：`asset_id` 将是您的文件夹 ID V4 API：请求体：`{"data": {"name": "New Folder Name"}}`。 | | **DELETE** | `/v2/assets/{asset_id}` （[删除资产](/platform/v2/api-reference/assets/delete-asset)） | **DELETE** | `/v4/accounts/{account_id}/folders/{folder_id}` （[删除文件夹](/platform/v4/api-reference/folders/delete)） | 移除文件夹。 | | 不适用 | 不适用 | **GET** | `/v4/accounts/{account_id}/folders/{folder_id}/folders` （[列出文件夹](/platform/v4/api-reference/folders/list)） | 列出给定文件夹中的文件夹。 （从显示项目路由获取 root\_folder\_id，您可以使用此项来列出最高级别的所有文件夹。） | ### 5. 版本堆栈 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ---------- | ----------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | **POST** | `/v2/assets/{destination_folder}/copy` （[复制资产](/platform/v2/api-reference/assets/copy-asset)） | **POST** | `/v4/accounts/{account_id}/version_stacks/{version_stack_id}/copy` （[复制版本堆栈](/platform/api-reference/version-stacks/copy)） | 旧版：路径中的目标文件夹；在请求中与版本堆栈一起使用。 V4：复制版本堆栈。 | | **POST** | `/v2/assets/{asset_id}/version` （[对资产进行版本控制](/platform/v2/api-reference/assets/add-version-to-asset)） | **POST** | `/v4/accounts/{account_id}/folders/{folder_id}/version_stacks` （[创建版本堆栈](/platform/api-reference/version-stacks/create)） | 创建版本堆栈。 请求体中需要有 2–10 个文件 ID。 | | **POST** | `/v2/assets/{asset_id}/version` （[对资产进行版本控制](/platform/v2/api-reference/assets/add-version-to-asset)） | **PATCH** | `/v4/accounts/{account_id}/files/{file_id}/move` （[将文件移动到版本堆栈](/platform/api-reference/files/move)） | 将文件移动到现有版本堆栈。 使用 `version_stack_id` 作为请求体中的 `parent_id`。 | | **GET** | `/v2/assets/{asset_id}/children` （[获取次资产](/platform/v2/api-reference/assets/get-assets)） | **GET** | `/v4/accounts/{account_id}/version_stacks/{version_stack_id}/children` （[列出版本堆栈次项](/platform/api-reference/version-stacks/index)） | 旧版：与版本堆栈 asset\_id 一起使用。 V4：列出版本堆栈中的次项（文件/版本）。 | | 不适用 | 不适用 | **GET** | `/v4/accounts/{account_id}/folders/{folder_id}/version_stacks` （[列出版本堆栈](/platform/api-reference/version-stacks/list)） | 列出文件夹中的版本堆栈。 | | 不适用 | 不适用 | **PATCH** | `/v4/accounts/{account_id}/version_stacks/{version_stack_id}/move` （[移动版本堆栈](/platform/api-reference/version-stacks/move)） | 将版本堆栈移动到另一个文件夹。 | | **GET** | `/v2/assets/{asset_id}` （[获取资产](/platform/v2/api-reference/assets/get-asset)） | **GET** | `/v4/accounts/{account_id}/version_stacks/{version_stack_id}` （[显示版本堆栈](/platform/api-reference/version-stacks/show)） | 旧版：与版本堆栈 asset\_id 一起使用。 V4：显示版本堆栈详细信息。 | | **DELETE** | `/v2/assets/{asset_id}/unversion`（删除取消版本控制） | 不适用 | 不适用 | V4 目前不支持取消版本控制。 | ### 6. 文件 注意：现在 V4 中有两个端点用于创建文件（本地和通过 S3 上传）。 有关更多详细信息，请参阅[上传文件](/platform/v4/docs/guides/how-to-upload)。 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ---------- | ------------------------------------------------------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **POST** | `/v2/assets/{parent_asset_id}/children` （[创建资产](/platform/v2/api-reference/assets/create-asset)） | **POST** | `/v4/accounts/{account_id}/folders/{folder_id}/files/local_upload` （[创建文件（本地上传）](/platform/v4/api-reference/files/create_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` （[创建文件（远程上传）](/platform/v4/api-reference/files/create_remote_upload)） | 路径参数中需要 account\_id 和 folder\_id，负载上需要 source url 和 name | | **GET** | `/v2/assets/{asset_id}` （[获取资产](/platform/v2/api-reference/assets/get-asset)） | **GET** | `/v4/accounts/{account_id}/files/{file_id}` （[显示文件](/platform/v4/api-reference/files/show)） | 显示文件详细信息 - 许多包含项可用于在响应中返回其他文件详细信息。 | | 不适用 | 不适用 | **GET** | `/v4/accounts/{account_id}/files/{file_id}/status` （[获取文件元数据](/platform/api-reference/files/show-file-upload-status)） | 从创建文件远程上传端点获取远程上传的状态。 | | **PUT** | `/v2/assets/{asset_id}` （[更新资产](/platform/v2/api-reference/assets/update-asset)） | **PATCH** | `/v4/accounts/{account_id}/files/{file_id}` （[更新文件](/platform/v4/api-reference/files/update)） | 更新文件名称。 | | **DELETE** | `/v2/assets/{asset_id}` （[删除资产](/platform/v2/api-reference/assets/delete-asset)） | **DELETE** | `/v4/accounts/{account_id}/files/{file_id}` （[删除文件](/platform/v4/api-reference/files/delete)） | 成功时返回 204 No Content。 | ### 7. 评论 目前支持大多数 V4 API 评论功能。 > **Info** > > **即将发布的特性：** > > * 评论反应，例如表情符号 > * 查看或修改评论完成状态 > * 了解谁查看过评论（曝光量） > **Note** > > “timestamp”字段表示留下评论的帧戳（从 1 开始），而不是时间戳 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ---------- | -------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | **GET** | `/v2/assets/{asset_id}/comments` （[从评论线程获取所有评论和回复](/platform/v2/api-reference/comments/get-comments)） | **GET** | `/v4/accounts/{account_id}/files/{file_id}/comments` （[列出评论](/platform/api-reference/comments/index)） | 列出文件上的评论。 | | **POST** | `/v2/assets/{asset_id}/comments` （[创建评论](/platform/v2/api-reference/comments/create-comment)） | **POST** | `/v4/accounts/{account_id}/files/{asset_id}/comments` （[创建评论](/platform/api-reference/comments/create)） | 创建评论。 请求体类似：`{"text":"Nice","timestamp":12.3}`。 | | **GET** | `/v2/comments/{comment_id}` （[通过 ID 获取评论](/platform/v2/api-reference/comments/get-comment)） | **GET** | `/v4/accounts/{account_id}/comments/{comment_id}` （[显示评论](/platform/api-reference/comments/show)） | 通过 ID 获取单个评论。 | | **PUT** | `/v2/comments/{comment_id}` （[更新评论](/platform/v2/api-reference/comments/update-comment)） | **PATCH** | `/v4/accounts/{account_id}/comments/{comment_id}` （[更新评论）](/platform/api-reference/comments/update) | 更新文本、时间等。 | | **DELETE** | `/v2/comments/{comment_id}` （[删除评论](/platform/v2/api-reference/comments/delete-comment)） | **DELETE** | `/v4/accounts/{account_id}/comments/{comment_id}` （[删除评论](/platform/api-reference/comments/delete)） | 移除评论。 | | **GET** | `/v2/comments/{comment_id}/impressions` （[获取曝光量](/platform/v2/api-reference/comments/get-comment-impressions)） | 不适用 | 不适用 | V4 当前不支持曝光量。 | ### 8. 共享项（审阅链接/演示文稿） 在 Frame V4 中，共享链接不再分为审阅链接和演示文稿链接。 在 V4 中，现在可以配置不同的样式来设置分享链接，匹配审阅或演示文稿体验。 注意：不支持通过 V4 API 与旧版审阅链接和演示文稿进行交互。 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ---------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **GET** | `/v2/projects/{project_id}/review_links` （[列出项目中的审阅链接](/platform/v2/api-reference/review-links/list)） | **GET** | `/v4/accounts/{account_id}/projects/{project_id}/shares` （[列出共享项](https://developer.adobe.com/frameio/api/current/#tag/Shares/operation/shares.index)） | 列出项目中的共享项（注意，这不包括旧版审阅链接和演示文稿） | | **POST** | `/v2/projects/{project_id}/review_links` （[创建审阅链接](/platform/v2/api-reference/review-links/review-link-create)） | **POST** | `/v4/accounts/{account_id}/projects/{project_id}/shares` （[创建共享项](https://developer.adobe.com/frameio/api/current/#tag/Shares/operation/shares.create)） | 创建新的共享链接。 请求体可能是 `{"data":{"name":"Review Link","type":"review"}}`。 | | **POST** | `/v2/review_links/{link_id}/assets` （[将资产添加到审阅链接](/platform/v2/api-reference/review-links/review-link-item-create)） | **POST** | `/v4/accounts/{account_id}/shares/{share_id}/assets` （[将新资产添加到共享项](/platform/api-reference/shares/add-asset)） | 将资产添加到共享项。 支持文件、文件夹和版本堆栈。 | | 不适用 | 不存在 | **DELETE** | `/v4/accounts/{account_id}/shares/{share_id}/assets/{asset_id}` [（删除共享）](/platform/api-reference/shares/remove-asset) | 从共享中移除资产 | | **DELETE** | `/v2/review_links/{link_id}` （[删除审阅链接](/platform/v2/api-reference/review-links/review-link-delete)） | **DELETE** | `/v4/accounts/{account_id}/shares/{share_id}` [（删除共享项）](/platform/api-reference/shares/delete) | 删除共享链接。 | | **PUT** | `/v2/review_links/{review_link_id}` （[更新审阅链接](/platform/v2/api-reference/review-links/review-link-update)） | **PATCH** | `/v4/accounts/{account_id}/shares/{share_id}` [（更新共享项）](/platform/api-reference/shares/update) | 更新共享链接 | ### 9. Webhook 您在 V3 中使用的 Webhook 将被迁移，且在大部分情况下功能保持不变。 迁移时它们将被禁用，需要启用后才能正常使用。 资产事件需要进行一些更改，现在分为文件和文件夹。 需要注意一些新的 V4 特定事件：metadata.value.updated、收藏集相关事件和共享相关事件。 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ---------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **POST** | `/v2/teams/{team_id}/hooks` [（创建 Webhook）](/platform/v2/api-reference/webhooks/create-webhook-for-team) | **POST** | `/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks` [（创建 Webhook）](/platform/api-reference/webhooks/create) | 提供 `{"data":{"url":"...","events":["file.created",...]}}`。 | | **GET** | `/v2/accounts/{account_id}/webhooks` [（获取帐户的 Webhook）](/platform/v2/api-reference/webhooks/get-webhooks-by-account) | **GET** | `/v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks` [（列出 Webhook）](/platform/api-reference/webhooks/index) | 获取工作区的所有 Webhook。 注意：要获取帐户的所有 Webhook，您需要先获取该帐户的所有工作区，然后获取这些工作区的所有 Webhook。 | | **GET** | `/v2/hooks/{hook_id}` [（获取 Webhook）](/platform/v2/api-reference/webhooks/get-webhook) | **GET** | `/v4/accounts/{account_id}/webhooks/{webhook_id}` [（列出 Webhook）](/platform/api-reference/webhooks/index) | 获取 Webhook 信息 | | **PUT** | `/v2/hooks/{hook_id}` [（更新 Webhook）](/platform/v2/api-reference/webhooks/update-webhook) | **PATCH** | `/v4/accounts/{account_id}/webhooks/{webhook_id}` [（更新 Webhook）](https://developer.adobe.com/frameio/api/experimental/#tag/Webhooks/operation/webhooks.update) | 更新 Webhook 设置 | | **DELETE** | `/v2/hooks/{hook_id}` [（删除 Webhook）](/platform/v2/api-reference/webhooks/delete-webhook) | **DELETE** | `/v4/accounts/{account_id}/webhooks/{webhook_id}` [（删除 Webhook）](https://developer.adobe.com/frameio/api/experimental/#tag/Webhooks/operation/webhooks.delete) | 移除 Webhook。 | ### 10. 自定义操作 您在 V3 中使用的自定义操作将被迁移，但将需要对请求和响应处理进行一些修改。 迁移时它们将被禁用，需要启用后才能正常使用。 有关更多详细信息，请参阅此[（文档）](/platform/v4/docs/guides/custom-actions#migrated-actions) 注意：自定义操作端点目前处于实验性 API 中，需要标头："api-version: experimental"。 | 方法 | 旧版端点 | 方法 | V4 端点 | 注意 | | ---------- | ------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | **POST** | `/v2/teams/{team_id}/actions`（[创建自定义操作](/platform/v2/api-reference/custom-actions/create-action-for-team)） | **POST** | `/v4/accounts/{account_id}/workspaces/{workspace_id}/actions`（[创建自定义操作](/platform/v4-experimental/api-reference/custom-actions/actions-create)） | 在工作区中创建自定义操作。 | | **DELETE** | `/v2/actions/{action_id}`（[删除自定义操作](/platform/v2/api-reference/custom-actions/delete-action)） | **DELETE** | `/v4/accounts/{account_id}/actions/{action_id}`（[删除自定义操作](/platform/v4-experimental/api-reference/custom-actions/actions-delete)） | 删除自定义操作。 | | **PUT** | `/v2/actions/{action_id}`（[更新自定义操作](/platform/v2/api-reference/custom-actions/update-action)） | **PATCH** | `/v4/accounts/{account_id}/actions/{action_id}`（[更新自定义操作](/platform/v4-experimental/api-reference/custom-actions/actions-update)） | 更新自定义操作详细信息。 | | **GET** | `/v2/teams/{team_id}/actions`（[获取团队的自定义操作](/platform/v2/api-reference/custom-actions/get-actions-by-account)） | **GET** | `/v4/accounts/{account_id}/workspaces/{workspace_id}/actions`（[列出自定义操作](/platform/v4-experimental/api-reference/custom-actions/actions-index)） | 列出给定工作区中的自定义操作。 | | **GET** | `/v2/actions/{action_id}`（[通过 ID 获取自定义操作](/platform/v2/api-reference/custom-actions/get-action)） | **GET** | `/v4/accounts/{account_id}/actions/{action_id}`（[显示自定义操作详细信息](/platform/v4-experimental/api-reference/custom-actions/actions-show)） | 显示自定义操作详细信息。 | ## 迁移步骤 #### 调整不支持的 V2 端点 **调整**任何不支持的旧版 V2 端点。 #### 更新基础 URL **更新基础 URL**，从 `api.frame.io/v2/...` 改为 `api.frame.io/v4/...`。 #### 更新 API 请求 **更新代码中的 API 请求**，以引用新的端点架构。 #### 更新 JSON 负载 **更新请求/响应架构的 JSON 负载**，确保您生成和使用正确的字段。 #### 更新术语 更新术语：在您的代码和前端中，“团队” → “工作区”；“资产” → “文件/文件夹”；“审阅链接”或“演示文稿链接” → “共享项”。 #### 测试端点 **测试**所有新更新的端点。 如果遇到 403、404、422 错误，请确认端点、请求负载形式等。 #### 解析错误响应 **解析**新的详细错误响应，如果您的 API 调用失败，请在 `{"errors": [...]}` JSON 响应中查找问题。 #### 部署到生产环境 使用 V4 [Frame.io](http://frame.io/) 帐户验证后，即可**部署**到生产环境。 ## 错误处理和常见问题 > **Note** > > 某些路由会给出自定义错误描述，这些描述可能与以下示例略有不同。 #### 客户端错误 (4xx) * **400** 错误请求：检查负载准确性。 \* **401** 未授权：授权令牌无效或缺失。 \* **403** 禁止访问：缺少权限范围或用户没有访问权限。 \* **404** 未找到：确认端点、API 版本或 ID。 \* **422** 实体无法处理：验证请求数据 \* **429** 请求过多：实施有退避机制的重试。 #### 服务器错误 (5xx) * **500** 内部服务器错误：短暂延迟后重试。 ## SDK 支持 与旧版 SDK 类似，开发者可以使用 Python SDK，且首次提供了 Typescript SDK。 这些 SDK 的功能相似，但方法完全不同。如果您要从旧版 SDK 更新到 V4 SDK，请务必相应地更新您的代码。 您可以在以下链接中找到它们： [快速入门 SDK](/platform/docs/getting-started#sdks) [Python SDK](/platform/docs/sdk-reference/python-sdk-reference) [Typescript SDK](/platform/docs/sdk-reference/type-script-sdk-reference) ---