Administración de usuarios

Información general

En este tutorial se explica la administración básica de usuarios a través de la API de Frame.io. Se asume que el lector ya ha configurado la autenticación mediante OAuth 2.0 o con un token de desarrollador.

Conceptos fundamentales

Dejando de lado los matices específicos de las diferentes funciones y permisos de los integrantes del equipo, hay dos claves importantes que se deben entender al administrar usuarios a través de la API de Frame.io:

1. Los integrantes del equipo pertenecen a equipos y tienen acceso a todos los proyectos no privados dentro de esos equipos. Los responsables de equipos y los administradores son extensiones de la función de integrante del equipo.
2. Los colaboradores del proyecto pertenecen a proyectos individuales. Según cómo estén configurados esos proyectos, podrán o no podrán crear presentaciones, descargar activos o invitar a otros colaboradores.

Para obtener más información, consulte nuestra documentación de asistencia para integrantes del equipo frente a colaboradores y las funciones de administración de cuentas.

Cómo se unen los usuarios a las cuentas

En general, los usuarios nuevos se unen mediante una invitación por parte de usuarios actuales, ya sea directamente o a través de una URL única de unión al proyecto. Los integrantes del equipo también pueden:

1. Añadirse a sí mismos a proyectos no privados dentro de equipos públicos en su cuenta
2. Añadirse a sí mismos a equipos públicos dentro de su cuenta
3. Solicitar unirse a equipos privados dentro de su cuenta

En todos los casos, las actividades de unión pasarán por una serie de pasos lógicos, entre los que se incluyen comprobar el arrendamiento previo, crear registros “pendientes” y enviar correos electrónicos de invitación o de solicitud de unión cuando corresponda.

La buena noticia es que toda esa lógica está abstraída por la API de Frame.io. Si desea añadir a alguien a un proyecto, use las rutas de colaborador; si desea invitar a alguien a un equipo, use las rutas de integrante del equipo.

Ámbitos necesarios

Administrar integrantes del equipo

Añadir integrantes al equipo

Para añadir un integrante del equipo nuevo a un equipo, necesitará:

1. El id del equipo de destino
2. El correo electrónico del usuario de destino.

A partir de ahí, simplemente realice una solicitud POST autorizada a https://api.frame.io/v2/teams/:id/members con el correo electrónico del usuario de destino en la carga útil del cuerpo de la siguiente manera:

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

Si el usuario al que ha invitado ya es un integrante del equipo en su organización, la respuesta de la API lo indicará:

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
}

Si el usuario al que ha invitado aún no está en su organización, su solicitud activará un flujo de invitación, y la respuesta de la API tendrá un aspecto similar al siguiente:

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
}

Nota: Dado que el usuario aún no se ha creado o reconocido, no habrá un user_id asignable en la respuesta pending_team_member.

Quitar a integrantes del equipo

Para quitar un integrante de un equipo, necesitará:

1. El id del equipo de destino
2. El correo electrónico del usuario de destino.

A partir de ahí, realizará una llamada DELETE a la misma URL que usaría para añadir un integrante del equipo, y le pasará una cadena de consulta especial: DELETE https://api.frame.io/v2/teams/:id/members/_?email=user@example.com

En una llamada correcta, la API devolverá una carga útil similar a la adición de integrantes del equipo. Si el integrante del equipo se va a eliminar por primera vez, verá un atributo updated_at que coincide con la hora de su llamada. Si el integrante del equipo ya se ha eliminado anteriormente, esa marca de tiempo no se actualizará (es decir, reflejará la hora en que se quitó inicialmente el integrante del equipo).

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
}

Los intentos de quitar integrantes del equipo que no existen o que nunca estuvieron asociados con el equipo devolverán errores 404.

Administrar colaboradores del proyecto

Añadir colaboradores del proyecto

La administración de colaboradores es muy similar a la administración de integrantes del equipo. Para añadir un colaborador nuevo a un equipo, necesitará:

1. El id del proyecto de destino
2. El correo electrónico del usuario de destino.

A partir de ahí, realice una solicitud POST autorizada a https://api.frame.io/v2/projects/:id/collaborators, con el correo electrónico del usuario de destino en la carga útil del cuerpo:

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

Si el usuario al que ha invitado se reconoce y la función de colaborador se puede instanciar inmediatamente, la respuesta de la API lo indicará y enviará de vuelta un objeto de usuario completo:

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
}

Si el usuario al que ha invitado es nuevo en su organización, su solicitud activará un flujo de invitación, y la API responderá con un registro pending_collaborator, de la siguiente manera:

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

Quitar colaboradores del proyecto

Nota: Este proceso es fundamentalmente idéntico a cómo se gestionan los integrantes del equipo (que se ha descrito anteriormente).

Para quitar un colaborador de un proyecto, necesitará:

1. El id del proyecto de destino.
2. El correo electrónico del usuario de destino.

A partir de ahí, realizará una llamada DELETE a la misma URL que utilizaría para añadir un colaborador, y le pasará una cadena de consulte especial. DELETE https://api.frame.io/v2/projects/:id/collaborators/_?email=user@example.com

En una llamada correcta, la API devolverá una carga útil similar a la adición de colaborador de proyecto:

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
}

Los intentos de quitar colaboradores que no existen o que nunca estuvieron asociados con el proyecto devolverán errores 404.