Gestione degli utenti

Panoramica

Questa esercitazione spiega la gestione di base degli utenti tramite l’API Frame.io. Si presuppone che il lettore abbia già configurato l’autenticazione tramite OAuth2.0 o con un token sviluppatore.

Concetti fondamentali

Tralasciando le sfumature specifiche dei diversi ruoli e delle diverse autorizzazioni dei membri del team, ci sono due aspetti importanti da comprendere quando si gestiscono gli utenti tramite l’API Frame.io:

1. I membri del team appartengono ai team e hanno accesso a tutti i progetti non privati all’interno di quei team. I team manager e gli amministratori del team sono estensioni della ruolo di membro del team.
2. I collaboratori del progetto appartengono a singoli progetti. A seconda della configurazione di questi progetti, possono creare o meno presentazioni, scaricare risorse o invitare altri collaboratori.

Per ulteriori informazioni, fai riferimento alla nostra documentazione di supporto a proposito di membri del team rispetto ai collaboratori e ai ruoli per la gestione degli account.

Modalità di partecipazione degli utenti agli account

In generale, i nuovi utenti vengono invitati dagli utenti attuali, direttamente o tramite URL univoco di partecipazione al progetto. I membri del team possono anche:

1. Aggiungersi a progetti non privati all’interno di team pubblici nel loro account
2. Aggiungersi a team pubblici all’interno del loro account
3. Richiedere di unirsi a team privati all’interno del loro account

In tutti i casi, le attività di partecipazione seguiranno una serie di passaggi logici che includono il controllo dell’appartenenza precedente, la creazione di record “in sospeso” e l’invio di e-mail di invito o di richiesta di partecipazione, se appropriato.

La buona notizia è che tutta questa logica è astratta dall’API Frame.io. Se vuoi aggiungere qualcuno a un progetto, usa gli instradamenti dei collaboratori; se vuoi invitare qualcuno a un team, usa gli instradamenti dei membri del team.

Ambiti richiesti

Gestione dei membri del team

Aggiunta di membri del team

Per aggiungere un nuovo membro a un team, ti serve:

1. L’id del team di destinazione.
2. L’indirizzo e-mail dell’utente di destinazione.

Poi basta eseguire una richiesta POST autorizzata a https://api.frame.io/v2/teams/:id/members con l’e-mail dell’utente di destinazione nel payload del corpo, come segue:

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

Se l’utente che hai invitato è già un membro del team nella tua organizzazione, la risposta API lo indicherà:

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
}

Se l’utente che hai invitato non fa ancora parte della tua organizzazione, la richiesta attiverà un flusso di invito e la risposta API avrà un aspetto simile al seguente:

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: poiché l’utente non è ancora stato creato o riconosciuto, non ci sarà uno user_id mappabile nella risposta pending_team_member.

Rimozione di membri del team

Per rimuovere un membro da un team, ti serve:

1. L’id del team di destinazione.
2. L’indirizzo e-mail dell’utente di destinazione.

Devi quindi effettuare una chiamata DELETE allo stesso URL che useresti per aggiungere un membro del team, passando una stringa di richiesta speciale: DELETE https://api.frame.io/v2/teams/:id/members/_?email=user@example.com

Se la chiamata riesce, l’API restituirà un payload simile all’aggiunta di membri del team. Se il membro del team viene eliminato per la prima volta, vedrai un attributo updated_at corrispondente all’ora della chiamata. Se il membro del team è stato eliminato in precedenza, la marca temporale non si aggiornerà, ovvero rifletterà l’ora in cui il membro del team è stato rimosso inizialmente.

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
}

I tentativi di rimuovere membri del team che non esistono o non sono mai stati associati al team causeranno degli errori 404.

Gestione dei collaboratori del progetto

Aggiunta di collaboratori del progetto

La gestione dei collaboratori è molto simile alla gestione dei membri del team. Per aggiungere un nuovo collaboratore a un team, ti serve:

1. L’id del progetto di destinazione.
2. L’indirizzo e-mail dell’utente di destinazione.

Devi quindi eseguire un richiesta POST autorizzata a https://api.frame.io/v2/projects/:id/collaborators, con l’e-mail dell’utente di destinazione nel payload del corpo:

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

Se l’utente che hai invitato viene riconosciuto e il ruolo di collaboratore può essere creato immediatamente, la risposta API lo indicherà e invierà un oggetto utente 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
}

Se l’utente che hai invitato è nuovo nella tua organizzazione, la tua richiesta attiverà un flusso di invito e l’API risponderà con un record pending_collaborator, come segue:

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

Rimozione dei collaboratori del progetto

Nota: questo processo è praticamente identico a come vengono gestiti i membri del team (descritto in alto).

Per rimuovere un collaboratore da un progetto, ti serve:

1. L’id del progetto di destinazione.
2. L’indirizzo e-mail dell’utente di destinazione.

Devi quindi effettuare una chiamata DELETE allo stesso URL che useresti per aggiungere un collaboratore, passando una stringa di richiesta speciale. DELETE https://api.frame.io/v2/projects/:id/collaborators/_?email=user@example.com

Su la chiamata riesce, l’API restituirà un payload simile all’aggiunta di un collaboratore del progetto:

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
}

I tentativi di rimuovere collaboratori che non esistono o non sono mai stati associati al progetto causeranno degli errori 404.