Gestion des utilisateurs

Aperçu

Ce tutoriel couvre la gestion de base des utilisateurs via l’API Frame.io. Il suppose que le lecteur a déjà configuré l’authentification via OAuth2.0 ou avec un jeton développeur.

Concepts de base

En laissant de côté les nuances spécifiques des différents rôles et autorisations des membres de l’équipe, il y a deux clés importantes à comprendre lors de la gestion des utilisateurs via l’API Frame.io :

1. Les membres de l’équipe appartiennent aux équipes, et ont accès à tous les projets non privés au sein de ces équipes. Les gestionnaires d’équipe et les administrateurs sont tous deux des extensions du rôle de membre de l’équipe.
2. Les utilisateurs collaborateur de projet appartiennent à des projets individuels. Selon la façon dont ces projets sont configurés, ils peuvent ou ne peuvent pas créer des présentations, télécharger des ressources, ou inviter d’autres utilisateurs collaborateur.

Pour plus d’informations, veuillez vous référer à notre documentation d’assistance pour Membres de l’équipe vs Utilisateurs collaborateur, et Rôles de gestion de compte.

Comment les utilisateurs rejoignent les comptes

En général, les nouveaux utilisateurs sont invités par les utilisateurs actuels, soit directement, soit via une URL de participation de projet unique. Les membres de l’équipe peuvent aussi :

1. S’ajouter à des projets non privés au sein d’équipes publiques dans leur compte
2. S’ajouter à des équipes publiques au sein de leur compte
3. Demander à rejoindre des équipes privées au sein de leur compte

Dans tous les cas, les activités de participation passeront par une série d’étapes logiques qui inclut la vérification de la location préalable, la création d’enregistrements « en attente », et l’envoi d’e-mails d’invitation ou de demande de participation quand approprié.

La bonne nouvelle est que toute cette logique est abstraite par l’API Frame.io. Si vous voulez ajouter quelqu’un à un projet, utilisez les routes d’utilisateur collaborateur ; si vous voulez inviter quelqu’un à une équipe, utilisez les routes de membre de l’équipe.

Portées requises

Gérer les membres de l’équipe

Ajouter des membres de l’équipe

Pour ajouter un nouveau membre de l’équipe à une équipe, vous avez besoin de :

1. L’id de l’équipe cible
2. L’adresse e-mail de l’Utilisateur cible.

À partir de là, effectuez simplement un POST autorisé vers https://api.frame.io/v2/teams/:id/members avec l’e-mail de l’Utilisateur cible dans le corps de la charge utile comme suit :

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

Si l’Utilisateur que vous avez invité est déjà un membre de l’équipe dans votre organisation, la réponse de l’API l’indiquera :

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 l’Utilisateur que vous avez invité ne fait pas encore partie de votre organisation, votre requête déclenchera un flux d’invitation, et la réponse de l’API ressemblera plutôt à ceci :

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
}

Remarque : étant donné que l’Utilisateur n’est pas encore créé ou reconnu, il n’y aura pas de user_id mappable dans la réponse pending_team_member.

Supprimer des membres de l’équipe

Pour supprimer un membre de l’équipe d’une équipe, vous avez besoin de :

1. L’id de l’équipe cible
2. L’adresse e-mail de l’Utilisateur cible.

À partir d’ici, vous effectuerez un appel DELETE vers la même URL que pour ajouter un membre de l’équipe, en lui transmettant une chaîne de requête spéciale : DELETE https://api.frame.io/v2/teams/:id/members/_?email=user@example.com

Lors d’un appel réussi, l’API renvoie une charge utile similaire à l’ajout de membre de l’équipe. Si le membre de l’équipe est supprimé pour la première fois, vous verrez un attribut updated_at correspondant à l’heure de votre appel. Si le membre de l’équipe a été supprimé précédemment, cette date et heure ne se met pas à jour (c’est-à-dire qu’elle reflète l’heure à laquelle le membre de l’équipe a été initialement supprimé).

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
}

Les tentatives de suppression de membres de l’équipe qui n’existent pas ou qui n’ont jamais été associés à l’équipe entraînent des erreurs 404.

Gérer les utilisateurs collaborateurs de Projet

Ajouter des utilisateurs collaborateurs de Projet

1
1. De l'`id` du Projet cible
2
2. De l'adresse e-mail de l'Utilisateur cible.
3
4
À partir de là, effectuez un `POST` autorisé vers [ `https://api.frame.io/v2/projects/:id/collaborators`](ref:post_projects-projectid-collaborators), avec l'e-mail de l'Utilisateur cible dans le corps de la charge utile :
5
6
```json
7
{
8
    "email": "user@example.com"
9
}

Si l’Utilisateur que vous avez invité est reconnu et que le rôle collaborateur utilisateur peut être instancié instantanément, la réponse de l’API l’indiquera et renverra un objet Utilisateur complet :

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 l’Utilisateur que vous avez invité est nouveau dans votre organisation, votre demande déclenchera un flux d’invitation, et l’API répondra avec un enregistrement pending_collaborator, comme ceci :

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

Suppression des collaborateurs de Projet

Remarque : ce processus est fondamentalement identique à la façon dont les membres de l’équipe sont traités (ci-dessus).

Pour supprimer un collaborateur utilisateur d’un Projet, vous aurez besoin :

1. De l’id du Projet cible.
2. De l’adresse e-mail de l’Utilisateur cible.

À partir d’ici, vous effectuerez un appel DELETE vers la même URL que vous utiliseriez pour ajouter un collaborateur utilisateur, en lui passant une chaîne de requête spéciale.DELETE https://api.frame.io/v2/projects/:id/collaborators/_?email=user@example.com

En cas d’appel réussi, l’API renverra une charge utile similaire à l’ajout de collaborateur de Projet. :

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
}

Les tentatives de suppression de collaborateurs qui n’existent pas ou qui n’ont jamais été associés au Projet entraîneront des erreurs 404.