Управление пользователями

Обзор

В этом руководстве рассказывается о базовом управлении пользователями через API-интерфейс Frame.io. Предполагается, что читающий пользователь уже настроил аутентификацию через OAuth2.0 или с помощью токена разработчика.

Основные концепции

Помимо специфических нюансов различных ролей и разрешений участников группы есть два важных ключевых аспекта для понимания при управлении пользователями через API-интерфейс Frame.io:

1. Участники команды принадлежат командам и имеют доступ ко всем не частным проектам в этих командах. Менеджеры и администраторы команд являются расширениями роли участника команды.
2. Соавтор проекта принадлежит одному проекту. В зависимости от того, как настроен проект, он может или не может создавать презентации, загружать ресурсы или приглашать других соавторов.

Для получения дополнительной информации обратитесь к справочной документации по сравнению участников команды и соавторов и по ролям управления учетными записями.

Как пользователи присоединяются к учетным записям

В общем, новые пользователи приглашаются текущими пользователями либо напрямую, либо через уникальный URL-адрес для присоединения к проекту. Участники команды также могут:

1. Добавлять себя к не частным проектам в общедоступных командах своей учетной записи.
2. Добавлять себя к общедоступным командам в их учетной записи.
3. Запрашивать присоединение к частным командам в своей учетной записи.

Во всех случаях действия по присоединению проходят через серию логических шагов, включающих проверку предыдущего участия, создание записей «в ожидании» и отправку приглашений или электронных писем с запросами на присоединение при необходимости.

Хорошо, что вся эта логика абстрагирована API-интерфейсом Frame.io. Чтобы добавить кого-то в проект, используйте маршруты соавтора. Чтобы пригласить кого-то в команду, используйте маршруты участника команды.

Необходимые области доступа

Управление участниками команды

Добавление участников команды

Для добавления нового участника в команду требуется:

1. ИД целевой команды.
2. Адрес электронной почты целевого пользователя.

Затем просто выполните авторизованный запрос POST к https://api.frame.io/v2/teams/:id/members с адресом электронной почты целевого пользователя в теле полезной нагрузки следующим образом:

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. ИД целевой команды.
2. Адрес электронной почты целевого пользователя.

Здесь вы будете выполнять вызов DELETE к тому же URL-адресу, который используется для добавления участника команды, и передавать специальную строку запроса: 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. ИД целевого проекта.
2. Адрес электронной почты целевого пользователя.

Затем выполните авторизованный запрос POST к https://api.frame.io/v2/projects/:id/collaborators с адресом электронной почты целевого пользователя в теле полезной нагрузки:

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. ИД целевого проекта.
2. Адрес электронной почты целевого пользователя.

Здесь вы будете выполнять вызов DELETE к тому же URL-адресу, который используется для добавления соавтора, и передавать специальную строку запроса. 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.