> This page is for 平台, version 旧版. > 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 对用户进行基础管理。它假定读者已通过 OAuth2.0 或使用开发者令牌设置了[身份验证](/getting-started/authentication)。 ### 核心概念 暂且不谈不同团队成员角色和权限的具体细微差别，通过 Frame.io API 管理用户时，有两个重要的关键点需要理解： 1. **团队成员隶属于团队**，并且可以访问这些团队中的所有非私有项目。团队经理和管理员都是团队成员角色的扩展。 2. **项目协作者隶属于单个项目**。根据这些项目的配置方式，他们也许能够创建演示文稿、下载资产或邀请其他协作者，也许不能。 有关更多信息，请参阅我们的支持文档：[团队成员与协作者](https://support.frame.io/getting-started/sharing-with-your-team-or-clients/difference-between-team-members-vs-collaborators)和[帐户管理角色](https://support.frame.io/enterprise-accounts/enterprise-account-management-roles)。 ### 用户如何加入帐户 一般情况下，新用户由现有用户邀请加入，可以是直接邀请，也可以通过唯一的项目加入 URL。团队成员还可以： 1. 将自己添加到其帐户中公共团队内的非私有项目 2. 将自己添加到其帐户中的公共团队 3. 请求加入其帐户中的私有团队 在所有情况下，加入活动都将经过一系列逻辑步骤，包括检查之前的租赁情况、创建“待处理”记录，以及在适当的情况下发送邀请或加入请求的电子邮件。 好消息是，所有这些逻辑都被 Frame.io API 抽象化了。如果您想将某人添加到项目中，请使用协作者相关路由；如果您想邀请某人加入团队，请使用团队成员相关路由。 ### 必需的权限范围 | 权限范围 | 原因 | | ---------- | ---------- | | **团队：**更新 | 添加和移除团队成员。 | | **项目：**更新 | 添加和移除项目协作者。 | ## 管理团队成员 ### 添加团队成员 要向团队添加新的团队成员，您需要： 1. 目标团队的 `id` 2. 目标用户的电子邮件地址。 然后，只需向 `https://api.frame.io/v2/teams/:id/members` 发起一个经过授权的 `POST` 请求，并在请求体负载中包含目标用户的电子邮件，如下所示： ```json { "email": "user@example.com" } ``` **如果您邀请的用户已经是您组织中的团队成员**，API 响应会表明这一点： ```json { "_type": "team_member", "id": "", "role": "member", "team_id": "", "user_id": "" } ``` **如果您邀请的用户尚未加入您的组织**，您的请求将触发邀请流程，API 响应将如下所示： ```json { "_type": "pending_team_member", "email": "user@example.com", "id": "", "role": "member", "team_id": " } ``` **注意**：由于用户尚未被创建或识别，`pending_team_member` 响应中不会有可映射的 `user_id`。 ### 移除团队成员 要从团队中移除团队成员，您需要： 1. 目标团队的 `id` 2. 目标用户的电子邮件地址。 接下来，您将对与添加团队成员相同的 URL 发起一个 `DELETE` 调用，并向其传递一个特殊的查询字符串：`DELETE` [`https://api.frame.io/v2/teams/:id/members/_?email=user@example.com`](ref:post_teams-teamid-members) **请注意** `/_?email=` 这种结构——这是 Frame.io API 中一个名为“include”的特殊模式，让您能够在 API 请求中请求额外的数据（在本例中是用户的电子邮件地址）。 在成功调用时，API 将返回与添加团队成员类似的负载。如果团队成员是首次被删除，您将看到一个 `updated_at` 属性，其时间与您的调用时间一致。如果团队成员之前已被删除，则该时间戳将不会更新（即它将反映该团队成员最初被移除时的时间）。 ```json { "_type": "team_member", "id": "", "role": "member", "team_id": "", "user_id": "", "updated_at": "" } ``` 尝试移除不存在或从未与该团队关联过的团队成员将导致 404 错误。 ## 管理项目协作者 ### 添加项目协作者 协作者管理与团队成员管理极其相似。要向团队添加新的协作者，您需要： 1. 目标项目的 `id` 2. 目标用户的电子邮件地址。 然后，向 [ `https://api.frame.io/v2/projects/:id/collaborators`](ref:post_projects-projectid-collaborators) 发起一个经过授权的 `POST` 请求，并在请求体负载中包含目标用户的电子邮件： ```json { "email": "user@example.com" } ``` **如果您邀请的用户能够被识别**，且协作者角色可以立即实例化，API 响应会表明这一点，并返回一个完整的用户对象： ```json { "_type": "collaborator", "creator_id": "", "id": "", "project_id": "", "user": { "_type": "user", <...> }, "user_id": "" } ``` 如果用户已经是您组织中的团队成员，但不是目标项目的成员，您仍然可以使用协作者路径，API 将如上所述进行响应。在后台，该团队成员将被添加到您的目标项目中，并且他仍然是一名团队成员。换句话说，您无法通过这种方式意外“降级”团队成员。 **如果您邀请的用户是您组织中的新用户**，您的请求将触发邀请流程，API 将以 `pending_collaborator` 记录作为响应，如下所示： ```json { "_type": "pending_collaborator", "email": "user@example.com", "id": "", "project_id": "" } ``` ### 移除项目协作者 **注意：**此过程与（上述）团队成员的处理方式基本相同。 要从项目中移除协作者，您需要： 1. 目标项目的 `id`。 2. 目标用户的电子邮件地址。 接下来，您将对与添加协作者相同的 URL 发起一个 `DELETE` 调用，并向其传递一个特殊的查询字符串。`DELETE` [`https://api.frame.io/v2/projects/:id/collaborators/_?email=user@example.com`](ref:post_teams-teamid-members) 在调用成功后，API 将返回与添加项目协作者类似的负载： ```json { "_type": "collaborator", "creator_id": "", "id": "", "project_id": "", "user": { "_type": "user", <...> }, "user_id": "" } ``` 尝试移除不存在或从未与该项目关联过的协作者将导致 404 错误。 与移除团队成员不同，尝试移除已经被移除过的协作者将导致 404 错误