Rôles
`roles.list`, `list_all`, `iterate`, `get`, `create`, `update`, `delete` et `list_permissions`.
Toutes les méthodes
page = client.roles.listputs page.items.size role = client.roles.get("role_8b1f4c2e9a7d3b60e5f1a2c4")puts role[:name] support = client.roles.create( name: "Support", description: "Answers the shared inboxes and nothing else.", permissions: ["emails:send", "threads:write", "labels:write"]) p support[:permissions] client.roles.update(support[:id], permissions: [*support[:permissions], "templates:read"]) client.roles.delete(support[:id], reassign_to: role[:id]) vocabulary = client.roles.list_permissionsp vocabulary.map { |permission| permission[:id] }support[:permissions] contient six entrées, pas trois : emails:send apporte emails:read, threads:write apporte threads:read et labels:write apporte labels:read. Relisez la liste plutôt que de la supposer.
list renvoie une OpenEmail::Page, list_all renvoie tous les rôles dans un seul Array, et iterate passe chaque rôle à un bloc ou renvoie un Enumerator sans bloc. Un rôle revient sous forme de Hash à clés Symbol : role[:permissions] lit donc la liste. create et update prennent les champs du corps en mots-clés ou en un seul Hash, alors que delete prend reassign_to:, un mot-clé en snake_case que la gem renomme pour l'API.
Un rôle dit ce que quelqu'un peut FAIRE. Les ADRESSES sur lesquelles il peut le faire forment l'autre axe, qui vit sur client.members : voir grant_address et revoke_address sur la page Membres. « Peut envoyer du courrier » et « peut envoyer en tant que invoices@ » sont deux phrases différentes, et un espace de travail qui recrute un deuxième agent de support change la seconde sans toucher à la première. Une permission répond aux deux : un rôle qui détient addresses:all atteint toutes les adresses, y compris celles ajoutées plus tard, sans octroi, et seule une personne dans l'application peut l'attribuer à un rôle.
Branchez-vous sur editable et deletable plutôt que sur builtin ou sur le nom. Les deux valent false pour le seul rôle propriétaire, dont la liste est « toutes les permissions, y compris celles inventées l'an prochain » et se calcule plutôt qu'elle ne se stocke. Tous les autres rôles répondent true aux deux, y compris les cinq créés à l'initialisation d'un espace de travail. Un rôle que quelqu'un a renommé répond toujours correctement aux deux, et son nom ne vous apprend plus rien.
update REMPLACE la liste des permissions. Il n'existe pas d'appel qui octroie une seule permission : lisez donc le rôle, changez l'entrée voulue et renvoyez-les toutes, comme le fait [*support[:permissions], "templates:read"] ci-dessus. Envoyer une seule permission laisse au rôle exactement celle-ci, plus ce qu'elle implique.
delete a besoin de reassign_to: dès que quelqu'un détient le rôle. La gem l'envoie comme paramètre de requête reassignTo, car un corps sur un DELETE est abandonné par plusieurs runtimes et un certain nombre de proxys, et omet le paramètre quand vous ne passez rien. Le résultat indique reassigned et keysReassigned séparément, pour qu'un script puisse journaliser ce qu'il a fait plutôt que ce qu'il a demandé.
list_permissions correspond à GET /roles/permissions, un chemin fixe situé exactement là où irait un id de rôle. La gem appelle directement ce chemin au lieu de faire passer le mot par get, et renvoie un simple Array, pas une OpenEmail::Page : un Hash par permission, avec id, label, group et scope. scope: false marque les entrées qu'aucune clé ne peut jamais détenir. Ne passez pas le mot à get vous-même. client.roles.get("permissions") construit le même chemin : il envoie donc la même requête et récupère le vocabulaire plutôt qu'un rôle ou un 404.
Un rôle est le plafond d'une clé
Une clé émise pour un rôle peut faire ce que permettent ses propres portées INTERSECTÉES avec les permissions de ce rôle, résolues à chaque requête à la frontière. Restreindre un rôle révoque donc les droits de ses clés en direct, sans qu'aucune d'elles ne soit renouvelée. Une clé sans rôle n'a aucun plafond, ce qui fait d'un roleId nil l'état le plus large dans lequel une clé puisse être, et non le plus étroit.
C'est aussi pourquoi roles.delete exige un endroit où déplacer les clés. Les laisser orphelines supprimerait entièrement leur plafond, promouvant en silence chaque identifiant que le rôle limitait.
GET /keys/self et GET /ping indiquent roleId et grantedScopes à côté des scopes effectives. C'est ainsi qu'on répond à « ma clé a emails:send et je reçois insufficient_scope » : tout ce qui figure dans grantedScopes et manque dans scopes a été retiré par le rôle. client.me.get et client.me.ping renvoient les deux dans leur Hash : key[:grantedScopes] - key[:scopes] liste donc ce que le rôle a retiré. Le refus lui-même est une OpenEmail::PermissionError dont scope_missing? vaut true.
Paramètres
nameStringobligatoire- Le nom que l'espace de travail donne au rôle : de 1 à 48 caractères, rogné avant d'être stocké. Les noms sont uniques par espace de travail sans distinction de casse : un deuxième « Support » est donc refusé avec `role_name_taken` (409), levé sous forme d'`OpenEmail::ConflictError`, au lieu d'être créé à côté du premier.
descriptionString- Une phrase qui dit à quoi sert le rôle, rognée et de 240 caractères au maximum. Une chaîne vide une fois rognée est stockée comme nil : une description faite d'espaces revient donc à nil plutôt que telle que vous l'avez envoyée. Sur `create`, omettez-la plutôt que de passer nil : la gem envoie nil tel quel, et `create` le refuse avec un 422. Sur `update`, `description: nil` l'efface.
permissionsArray<String>obligatoire- Ce que le rôle accorde, pris dans le vocabulaire que sert `list_permissions`. Une chaîne qui n'y figure pas donne un 422 sur `permissions`, levé sous forme d'`OpenEmail::ValidationError` avec `param` à `permissions`, au lieu d'être ignorée en silence : une faute de frappe est ainsi signalée au lieu de vous coûter un après-midi. La liste est DÉVELOPPÉE à l'entrée (`templates:write` stocke `templates:read` à côté), dédoublonnée et remise dans l'ordre canonique : lisez donc la liste stockée dans la réponse plutôt que de supposer que c'est celle que vous avez envoyée.
Réponse
objectString- Toujours `role`. La pierre tombale de suppression répond avec la même valeur, l'`id` du rôle, `deleted: true` et les deux compteurs de réaffectation, et aucun des autres champs ci-dessous.
idString- L'id du rôle, lu avec `role[:id]`. C'est ce que désigne le `roleId` d'un membre, ce vers quoi pointe le plafond d'une clé API, et ce que prend `reassign_to:` quand un autre rôle est supprimé et que ses détenteurs passent à celui-ci.
nameString- Le nom que l'espace de travail donne au rôle, rogné et unique sans distinction de casse. Tous les rôles sauf celui du propriétaire peuvent être renommés, y compris les rôles initiaux (`builtin` dit d'où vient une ligne, pas comment elle doit continuer à s'appeler) : ne lisez donc pas « Admin » comme une promesse sur ce que détient le rôle. Un nom auquel répond déjà un autre rôle donne `role_name_taken` (409, avec `param` à `name`). Renommer le propriétaire donne `role_immutable` (409), comme toute autre modification de ce rôle.
descriptionString or nil- La phrase qui décrit le rôle, ou nil quand aucune n'a été donnée. Une saisie vide est stockée comme nil à la création comme à la mise à jour : ce champ n'est donc jamais une chaîne vide.
permissionsArray<String>- Tout ce que le rôle accorde, déjà développé et dans l'ordre canonique plutôt que dans l'ordre où quelqu'un l'a saisi. Cet ordre est structurant : deux rôles qui détiennent les mêmes permissions détiennent des Arrays égaux, et c'est ce qui permet à un écran de paramètres de les comparer avec `==` pour décider si Enregistrer est actif.
builtinString or nil- Duquel des six rôles initiaux provient cette ligne, `owner`, `admin`, `member`, `viewer`, `developer` ou `billing`, ou nil pour un rôle que l'espace de travail a écrit lui-même. Le champ enregistre l'origine et non un statut : un rôle initial se renomme, se repermissionne et se supprime comme n'importe quel autre. Branchez-vous sur `editable` et `deletable` plutôt que sur ce champ. Un rôle que quelqu'un a appelé « Admin » n'est pas forcément le rôle initial, et le rôle initial ne s'appelle peut-être plus ainsi.
editableBoolean- Calculé comme `builtin != "owner"` : il vaut donc false pour le seul rôle propriétaire, et tout `update` de ce rôle est refusé avec `role_immutable` (409). Tous les autres rôles sont entièrement modifiables (nom, description et permissions), y compris les cinq créés à l'initialisation d'un espace de travail.
deletableBoolean- Calculé comme `builtin != "owner"` : false pour le seul rôle propriétaire, qui répond `role_undeletable` (409), et true pour tous les autres, y compris les rôles initiaux. Vérifiez-le avant de proposer le bouton plutôt qu'après le refus. Un rôle que quelqu'un détient encore a aussi besoin de `reassign_to:`, sinon la suppression donne `role_in_use` (409). Les deux refus sont levés sous forme d'`OpenEmail::ConflictError`, et `code` les distingue.
membersInteger- Combien de personnes détiennent ce rôle, compté à partir des lignes de membres de l'espace de travail. Le propriétaire n'en fait pas partie : il n'a pas de ligne de membre et ne peut pas recevoir de rôle, si bien que le rôle Owner affiche zéro détenteur alors même que la liste des membres le montre.
apiKeysInteger- Combien de clés API actives sont plafonnées par ce rôle. Les clés révoquées ne sont pas comptées, même si une suppression réaffecte chaque ligne de clé qui pointe vers le rôle, révoquées comprises. C'est la deuxième population à déplacer avant que le rôle puisse disparaître, et celle que personne ne remarque : les clés sont des programmes, et un programme ne se plaint pas.
createdAtString- Quand la ligne du rôle a été écrite, sous forme de String ISO 8601. Les lignes intégrées sont créées à la demande, la première fois que quelque chose en a besoin, comme la lecture d'une liste de rôles, la création d'un rôle ou l'écran des clés API, plutôt qu'à la création de l'espace de travail. L'horodatage d'un rôle intégré correspond donc au moment où cette première requête est arrivée, et non à celui où l'espace de travail a été créé.
updatedAtString- Quand le rôle a changé pour la dernière fois, sous forme de String ISO 8601. Chaque `update` accepté le fait avancer, y compris celui qui donne à un champ la valeur qu'il avait déjà.