Membres
`members->list`, `listAll`, `iterate`, `get`, `add`, `update`, `remove`, `grantAddress`, `revokeAddress`, `grantDomain`, `revokeDomain`, ainsi que les méthodes d'invitation à côté.
Toutes les méthodes
$supportRoleId = 'role_8b1f4c2e9a7d3b60e5f1a2c4';$viewerRoleId = 'role_2c7e9a1f4b8d3e60c5a7f1b9'; $invitation = $client->members->add([ 'email' => '[email protected]', 'roleId' => $supportRoleId, 'addressIds' => ['2b81de07-9c3f-4a61-b8e2-5d07f4c19a36'], 'access' => 'member',]);echo $invitation['id'], ' ', $invitation['expiresAt'], PHP_EOL; foreach ($client->members->listAll() as $person) { echo $person['email'], ' ', $person['userId'], PHP_EOL;} $samId = 'q7Vd3kX9mT2pLw8RzN4bYc6HfJ1sGa5E';$member = $client->members->get($samId);echo $member['role']['name'], $member['implied'] ? ' (implied)' : '', PHP_EOL; $client->members->update($samId, ['roleId' => $viewerRoleId]); $addressId = 'c40a95f2-1e7b-4d38-a6c9-82f05b3d7e14';$client->members->grantAddress($samId, ['addressId' => $addressId, 'access' => 'viewer']);$client->members->revokeAddress($samId, $addressId); $removed = $client->members->remove($samId);echo $removed['addressesRevoked'], PHP_EOL;Deux attributions par personne, et elles ne doivent pas être confondues. role est ce qu'elle a le droit de faire. addresses et domains sont ce sur quoi elle a le droit de le faire. Les deux doivent concorder : un rôle qui détient emails:send avec access à viewer sur invoices@ désigne quelqu'un qui peut envoyer du courrier mais pas depuis cette adresse. L'exception est un rôle qui détient addresses:all, qui atteint toutes les adresses quoi que liste addresses, car ce tableau ne contient que les attributions directes. Vérifiez donc permissions avant de lire addresses comme la totalité de ce que quelqu'un peut atteindre.
Chaque appel qui concerne une personne prend son userId comme premier argument, et non son e-mail : lisez-le donc dans list ou listAll, comme le fait l'exemple. add est la seule exception, car il invite une adresse : la personne n'a de userId qu'une fois l'invitation acceptée, et listInvitations suit l'invitation jusque-là. Le corps d'add, update, grantAddress et grantDomain est un seul tableau aux noms en camelCase de l'API (roleId, addressIds, addressId).
list renvoie une OpenEmail\Result\Page, listAll renvoie tous les membres dans un seul tableau, et iterate renvoie un Generator qui fournit les membres un par un. Un membre revient sous forme de tableau à clés en camelCase, et role est un tableau à l'intérieur : $member['role']['name'] lit donc le nom du rôle.
implied à true signifie que personne n'a choisi le rôle. La personne détient des adresses ou des domaines et aucune ligne de rôle : il a donc été déduit de l'attribution la plus large qu'elle possède. Traitez-le comme « pas encore décidé ». C'est update qui transforme la déduction en décision. D'ici là, élargir son accès aux adresses élargit silencieusement ce qu'elle a le droit de faire.
Le propriétaire de l'espace de travail est la première ligne, avec isOwner à true, tandis qu'add, update et remove le refusent toujours avec member_is_owner, un 422 levé sous la forme d'une ValidationException. Un espace de travail non partagé indique un membre et non zéro. Excluez donc isOwner quand vous comptez les sièges : count(array_filter($client->members->listAll(), fn(array $member): bool => !$member['isOwner'])).
remove agit sur les deux axes, le rôle ET chaque attribution d'adresse et de domaine de cet espace de travail, et indique dans addressesRevoked combien d'attributions il a retirées, domaines compris. revokeAddress est l'appel ciblé, pour quelqu'un qui a changé d'équipe plutôt que pour quelqu'un qui est parti, et revokeDomain fait de même pour un domaine entier.
add, update, remove et les quatre appels d'attribution et de retrait demandent un code de vérification à un jeton d'accès OAuth, et jamais à une clé API. Tant que le jeton n'en a pas, ils lèvent une PermissionException dont isStepUpRequired() vaut true. add et grantDomain exigent aussi une offre qui inclut l'accès d'équipe, et sur une offre qui ne l'inclut pas, ils lèvent une PermissionException avec errorCode à plan_required.
Paramètres
emailstringobligatoire- Qui inviter, nettoyé des espaces et mis en minuscules. La personne n'a pas encore besoin d'un compte : tout le monde est invité, et le rôle et les attributions se posent à l'acceptation. Quelqu'un qui est déjà dans l'espace de travail donne `member_is_owner` (422). Une adresse qui se connecte avec son propre mot de passe ne peut pas être invitée et revient en `mailbox_login` (403) : invitez plutôt l'adresse e-mail personnelle de la personne.
roleIdstringobligatoire- Le rôle que la personne détiendra, de 1 à 128 caractères, et ce doit être un rôle de cet espace de travail : un id inconnu donne `role_not_found` (404), levé sous la forme d'une `NotFoundException`. Le rôle propriétaire ne peut pas être attribué et revient en `role_immutable` (409), car faire de quelqu'un un propriétaire est un transfert d'espace de travail, et aucun appel ici ne le permet.
addressIdsarray- Les adresses que porte l'invitation, au maximum 64 ids de 1 à 128 caractères chacun, attribuées lorsqu'elle est acceptée. Chaque id est vérifié avant toute écriture : un id qui n'est pas une adresse de ce workspace fait donc refuser l'appel entier avec 422 `member_not_found`, et rien n'est envoyé. Inviter de nouveau la même adresse dans les dix minutes donne 409 `invitation_too_soon`.
domainIdsarray- Les domaines entiers que porte l'invitation, au maximum 64 ids, attribués lorsqu'elle est acceptée. Une attribution de domaine atteint chaque adresse de ce domaine, y compris celles créées plus tard. Un id qui n'est pas un domaine de cet espace de travail donne 422 `member_not_found`, comme pour une adresse.
accessstring- Ce que la personne peut faire avec chaque id de `addressIds` et `domainIds` : `member` lit l'adresse et envoie en son nom, `viewer` se contente de la lire. Vaut `member` par défaut, le niveau qu'ont toujours utilisé la console et l'ancien chemin de partage, pour que le même appel signifie la même chose depuis un script et depuis un écran. Pour panacher, appelez ensuite `grantAddress` sur les adresses qui diffèrent.
Réponse
objectstring- Toujours `member`. Une suppression répond avec la même valeur, le `userId` de la personne, `deleted` à true et `addressesRevoked`, et aucun des autres champs ci-dessous.
userIdstring- L'id de son compte, que tout autre appel sur les membres prend comme premier argument : `get`, `update`, `remove` et les quatre appels d'attribution et de retrait. Ajouter quelqu'un est le seul appel qui part plutôt d'un e-mail, car celui qui ajoute un collègue connaît son adresse et non son id.
emailstring- L'e-mail de son compte, renvoyé tel que cette ligne le stocke. Cette ressource ne l'écrit jamais, et la mise en minuscules d'`add` s'applique à l'adresse que vous envoyez pour la recherche, pas à ce qui revient. Après le propriétaire, la liste des membres est triée dessus plutôt que sur la date d'arrivée des personnes, car on lit cette liste pour trouver quelqu'un, pas pour voir ce qui a changé.
namestring or null- Son nom affiché, repris de son compte, où la colonne a toujours une valeur. Le null du type est une précaution plutôt qu'un état que cette API ait déjà produit. Ce nom appartient à la personne et non à l'espace de travail : rien sur cette ressource ne peut donc le définir.
imagestring or null- Son avatar, repris de son compte, et null quand elle n'en a pas défini.
role.idstring or null- L'id du rôle que la personne détient, lu avec `$member['role']['id']`, ou null quand personne ne l'a choisi. Voir `implied`. Un null ici est le seul cas où `role` indique une déduction plutôt qu'une décision prise par quelqu'un.
role.namestring- Le nom du rôle. Pour un membre implicite, c'est le nom du modèle intégré auquel correspond son accès, et non une ligne de cet espace de travail.
role.builtinstring or null- De quel rôle intégré il s'agit, `owner`, `admin`, `member`, `viewer`, `developer` ou `billing`, ou null pour un rôle personnalisé. `owner` n'apparaît que sur la ligne du propriétaire lui-même, aux côtés d'`isOwner` à true. Attribuer ce rôle à quiconque est refusé avec `role_immutable` (409).
isOwnerbool- Vrai sur exactement une ligne, le compte sur lequel le workspace est indexé. Cette personne détient toutes les permissions quoi que dise sa ligne de rôle, elle est triée en premier, et `add`, `update` et `remove` la refusent tous avec `member_is_owner`. Excluez-la quand vous comptez des sièges.
impliedbool- True quand cette personne a des attributions d'adresses ou de domaines et aucune ligne de membre : son rôle a donc été déduit plutôt que choisi. Toute attribution `member` en fait le rôle intégré Member, sinon Viewer. Jamais true pour le propriétaire. Affichez-le comme « déduit de l'accès ». Tant qu'un `update` n'a pas transformé la déduction en décision, élargir son accès aux adresses élargit en silence ce qu'elle peut faire.
permissionsarray- Les permissions du rôle reportées sur le membre, pour qu'une seule lecture réponde à « a-t-elle le droit ? » sans aller chercher le rôle. Pour un membre implicite, elles viennent du MODÈLE intégré plutôt que de la ligne de rôle de cet espace de travail : modifier le rôle Member intégré ne change donc pas ce que détient un membre implicite.
addressesarray- Les adresses qui lui ont été accordées, triées par adresse, un tableau par adresse avec son propre niveau d'accès. Vide pour quelqu'un qui détient un rôle et aucune attribution, ce à quoi ressemble un nouveau membre tant qu'aucune adresse ne lui est accordée, et c'est le bon échec à avoir pendant que vous décidez encore de ce qu'elle doit voir.
addresses[].addressIdstring- L'id de l'adresse, et ce que prennent `grantAddress` et `revokeAddress`. Un id qui n'est pas une adresse de ce workspace est refusé sur les deux, plutôt que de rapporter une révocation qui n'a jamais eu lieu.
addresses[].addressstring- L'adresse complète, en minuscules, reconstruite à partir de sa partie locale et de son domaine.
addresses[].accessstring- Ce que la personne peut faire avec cette adresse précise : `member` la lit et envoie en son nom, `viewer` se contente de la lire. Ce champ et le rôle doivent tous deux autoriser un envoi pour qu'il ait lieu : un rôle qui détient `emails:send` avec une attribution `viewer` n'envoie depuis aucune adresse. La colonne stockée s'appelle `role`, et elle est renommée ici pour qu'un même tableau ne porte pas deux clés `role` issues de deux vocabulaires.
domainsarray- Les domaines entiers qui lui ont été accordés, chacun avec `domainId`, `domain` et `access`. Une attribution de domaine atteint chaque adresse de ce domaine, y compris celles créées plus tard : lisez-la donc à côté d'`addresses` avant de décider que quelqu'un ne peut pas atteindre une adresse. `grantDomain` et `revokeDomain` prennent le `domainId`.
createdAtstring or null- Quand sa ligne de membre a été écrite, sous forme de chaîne ISO 8601, et null quand il n'existe aucune ligne de membre. Ce null décrit la même population qu'`implied` à true : les personnes qui détiennent des attributions datant d'avant l'existence des rôles et à qui personne n'a depuis attribué de rôle.
Invitations
$waiting = $client->members->listAllInvitations(); foreach ($waiting as $invitation) { if ($invitation['expired']) { $client->members->resendInvitation($invitation['id']); }} $client->members->revokeInvitation('winv_6bb640f5b99e47deb758f1f5');add répond par une invitation, et voici les appels qui en assurent le suivi. listInvitations renvoie une OpenEmail\Result\Page de celles que personne n'a encore acceptées, listAllInvitations les renvoie toutes dans un seul tableau, et iterateInvitations renvoie un Generator qui les fournit une par une. resendInvitation en renvoie une avec un nouveau lien et quatorze jours de plus, et revokeInvitation la retire. Une invitation en attente n'accorde rien tant qu'elle n'est pas acceptée.
Une invitation est un tableau avec id, email, role, addresses, domains, expiresAt, expired, lastSentAt et createdAt. delivered et deliveryError indiquent ce qu'il est advenu du dernier e-mail d'invitation : un script peut ainsi distinguer une invitation simplement écrite d'une invitation qui a atteint quelqu'un.
resendInvitation refuse la même adresse deux fois en dix minutes avec 409 invitation_too_soon, et revokeInvitation refuse une invitation acceptée entre-temps avec 409 invitation_accepted. Les deux sont levés sous la forme d'une ConflictException : isConflict() vaut donc true et errorCode les distingue.