사용자 관리

개요

이 튜토리얼은 Frame.io API를 통한 기본적인 사용자 관리 방법을 다룹니다. 이 가이드는 독자가 이미 OAuth 2.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 호출을 수행하되, 다음과 같이 특수한 쿼리 문자열을 추가하여 전달하게 됩니다. DELETEhttps://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 응답도 이를 반영하며, 전체 User 오브젝트를 반환하게 됩니다.

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 호출을 수행하게 됩니다. DELETEhttps://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 오류가 발생합니다.