用户管理

概述

本教程介绍如何通过 Frame.io API 对用户进行基础管理。它假定读者已通过 OAuth2.0 或使用开发者令牌设置了身份验证。

核心概念

暂且不谈不同团队成员角色和权限的具体细微差别，通过 Frame.io API 管理用户时，有两个重要的关键点需要理解：

1. 团队成员隶属于团队，并且可以访问这些团队中的所有非私有项目。团队经理和管理员都是团队成员角色的扩展。
2. 项目协作者隶属于单个项目。根据这些项目的配置方式，他们也许能够创建演示文稿、下载资产或邀请其他协作者，也许不能。

有关更多信息，请参阅我们的支持文档：团队成员与协作者和帐户管理角色。

用户如何加入帐户

一般情况下，新用户由现有用户邀请加入，可以是直接邀请，也可以通过唯一的项目加入 URL。团队成员还可以：

1. 将自己添加到其帐户中公共团队内的非私有项目
2. 将自己添加到其帐户中的公共团队
3. 请求加入其帐户中的私有团队

在所有情况下，加入活动都将经过一系列逻辑步骤，包括检查之前的租赁情况、创建“待处理”记录，以及在适当的情况下发送邀请或加入请求的电子邮件。

好消息是，所有这些逻辑都被 Frame.io API 抽象化了。如果您想将某人添加到项目中，请使用协作者相关路由；如果您想邀请某人加入团队，请使用团队成员相关路由。

必需的权限范围

管理团队成员

添加团队成员

要向团队添加新的团队成员，您需要：

1. 目标团队的 id
2. 目标用户的电子邮件地址。

然后，只需向 https://api.frame.io/v2/teams/:id/members 发起一个经过授权的 POST 请求，并在请求体负载中包含目标用户的电子邮件，如下所示：

1
{
2
    "email": "user@example.com"
3
}

如果您邀请的用户已经是您组织中的团队成员，API 响应会表明这一点：

1
{
2
    "_type": "team_member",
3
    "id": "<team-member-record-id>",
4
    "role": "member",
5
    "team_id": "<team-id>",
6
    "user_id": "<user-id>"
7
}

如果您邀请的用户尚未加入您的组织，您的请求将触发邀请流程，API 响应将如下所示：

1
{
2
    "_type": "pending_team_member",
3
    "email": "user@example.com",
4
    "id": "<oending-team-member-record-id>",
5
    "role": "member",
6
    "team_id": "<team-id>
7
}

注意：由于用户尚未被创建或识别，pending_team_member 响应中不会有可映射的 user_id。

移除团队成员

要从团队中移除团队成员，您需要：

1. 目标团队的 id
2. 目标用户的电子邮件地址。

接下来，您将对与添加团队成员相同的 URL 发起一个 DELETE 调用，并向其传递一个特殊的查询字符串：DELETE https://api.frame.io/v2/teams/:id/members/_?email=user@example.com

在成功调用时，API 将返回与添加团队成员类似的负载。如果团队成员是首次被删除，您将看到一个 updated_at 属性，其时间与您的调用时间一致。如果团队成员之前已被删除，则该时间戳将不会更新（即它将反映该团队成员最初被移除时的时间）。

1
{
2
    "_type": "team_member",
3
    "id": "<team-member-record-id>",
4
    "role": "member",
5
    "team_id": "<team-id>",
6
    "user_id": "<user-id>",
7
    "updated_at": "<timestamp>"
8
}

尝试移除不存在或从未与该团队关联过的团队成员将导致 404 错误。

管理项目协作者

添加项目协作者

协作者管理与团队成员管理极其相似。要向团队添加新的协作者，您需要：

1. 目标项目的 id
2. 目标用户的电子邮件地址。

然后，向 https://api.frame.io/v2/projects/:id/collaborators 发起一个经过授权的 POST 请求，并在请求体负载中包含目标用户的电子邮件：

1
{
2
    "email": "user@example.com"
3
}

如果您邀请的用户能够被识别，且协作者角色可以立即实例化，API 响应会表明这一点，并返回一个完整的用户对象：

1
{
2
    "_type": "collaborator",
3
    "creator_id": "<inviting-user-id>",
4
    "id": "<collaborator-record-id>",
5
    "project_id": "<project-id>",
6
    "user": {
7
        "_type": "user",
8
       <...>
9
    },
10
    "user_id": "<user-id>"
11
}

如果您邀请的用户是您组织中的新用户，您的请求将触发邀请流程，API 将以 pending_collaborator 记录作为响应，如下所示：

1
{
2
    "_type": "pending_collaborator",
3
    "email": "user@example.com",
4
    "id": "<pending-collaborator-record-id>",
5
    "project_id": "<project-id>"
6
}

移除项目协作者

**注意：**此过程与（上述）团队成员的处理方式基本相同。

要从项目中移除协作者，您需要：

1. 目标项目的 id。
2. 目标用户的电子邮件地址。

接下来，您将对与添加协作者相同的 URL 发起一个 DELETE 调用，并向其传递一个特殊的查询字符串。DELETE https://api.frame.io/v2/projects/:id/collaborators/_?email=user@example.com

在调用成功后，API 将返回与添加项目协作者类似的负载：

1
{
2
    "_type": "collaborator",
3
    "creator_id": "<inviting-user-id>",
4
    "id": "<collaborator-record-id>",
5
    "project_id": "<project-id>",
6
    "user": {
7
        "_type": "user",
8
       <...>
9
    },
10
    "user_id": "<user-id>"
11
}

尝试移除不存在或从未与该项目关联过的协作者将导致 404 错误。