Membros
`members->list`, `listAll`, `iterate`, `get`, `add`, `update`, `remove`, `grantAddress`, `revokeAddress`, `grantDomain`, `revokeDomain` e os métodos de convites ao lado.
Todos os métodos
$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;Duas concessões por pessoa, que não podem ser fundidas numa só. role é o que a pessoa pode fazer. addresses e domains são aquilo a que o pode fazer. Ambas têm de concordar: uma função com emails:send e com access definido como viewer em invoices@ é alguém que pode enviar correio mas não o pode enviar a partir desse endereço. A exceção é uma função com addresses:all, que alcança todos os endereços, seja o que for que addresses liste, porque esse array só contém concessões diretas. Por isso, verifique permissions antes de ler addresses como todo o alcance de alguém.
Todas as chamadas sobre uma pessoa recebem o seu userId como primeiro argumento, e não o seu email, por isso obtenha-o de list ou listAll, como faz o exemplo. add é a única exceção, porque convida um endereço: a pessoa só tem um userId depois de aceitar, e listInvitations acompanha o convite até lá. O corpo de add, update, grantAddress e grantDomain é um único array com as chaves dos nomes em camelCase da API (roleId, addressIds, addressId).
list devolve uma OpenEmail\Result\Page, listAll devolve todos os membros num único array, e iterate devolve um Generator que entrega um membro de cada vez. Um membro volta como um array com chaves em camelCase, e role é um array dentro dele, por isso $member['role']['name'] lê o nome da função.
Quando implied é true, ninguém escolheu a função. A pessoa tem endereços ou domínios e nenhuma linha de função, por isso esta foi inferida a partir da concessão mais ampla que possui. Trate-o como «ainda não decidido»: é update que transforma a inferência numa decisão. Até lá, alargar o seu acesso a endereços alarga silenciosamente o que pode fazer.
O proprietário do espaço de trabalho é a primeira linha, com isOwner igual a true, enquanto add, update e remove continuam a recusá-lo com member_is_owner, um 422 lançado como ValidationException. Um espaço de trabalho não partilhado indica um membro em vez de nenhum, por isso exclua isOwner quando estiver a contar lugares: count(array_filter($client->members->listAll(), fn(array $member): bool => !$member['isOwner'])).
remove retira ambos os eixos, a função E todas as concessões de endereço e de domínio neste espaço de trabalho, e indica em addressesRevoked quantas concessões retirou, incluindo as de domínio. revokeAddress é o mais restrito, para alguém que mudou de equipa e não para alguém que saiu, e revokeDomain faz o mesmo para um domínio inteiro.
add, update, remove e as quatro chamadas de concessão e revogação pedem um código de verificação a um token de acesso OAuth, e a uma chave de API nunca. Enquanto o token não tiver um, lançam um PermissionException cujo isStepUpRequired() é true. add e grantDomain precisam também de um plano que inclua uma equipa, e num plano que não a inclua lançam um PermissionException com errorCode definido como plan_required.
Parâmetros
emailstringobrigatório- Quem convidar, aparado e passado a minúsculas. Ainda não precisa de conta: toda a gente é convidada, e a função e as concessões chegam quando aceitam. Alguém que já esteja no espaço de trabalho é `member_is_owner` (422). Um endereço que inicia sessão com uma palavra-passe própria não pode ser convidado e volta com `mailbox_login` (403), por isso convide antes o email da própria pessoa.
roleIdstringobrigatório- A função que a pessoa vai ter, de 1 a 128 caracteres, e tem de ser uma função deste espaço de trabalho: um id desconhecido dá `role_not_found` (404), lançado como `NotFoundException`. A função de proprietário não pode ser atribuída e volta como `role_immutable` (409), porque tornar alguém proprietário é uma transferência do espaço de trabalho e não há aqui nenhuma chamada para isso.
addressIdsarray- Endereços que o convite transporta, no máximo 64 ids de 1 a 128 caracteres cada, concedidos quando é aceite. Cada id é verificado antes de qualquer escrita, por isso um que não seja um endereço desta workspace faz recusar a chamada inteira com 422 `member_not_found` e nada é enviado. Convidar o mesmo endereço outra vez dentro de dez minutos é 409 `invitation_too_soon`.
domainIdsarray- Domínios inteiros que o convite inclui, no máximo 64 ids, concedidos quando é aceite. Uma concessão de domínio alcança todos os endereços desse domínio, incluindo os criados depois. Um id que não seja um domínio deste espaço de trabalho dá 422 `member_not_found`, tal como um endereço.
accessstring- O que a pessoa pode fazer com cada id em `addressIds` e `domainIds`: `member` lê o endereço e envia como ele, `viewer` apenas o lê. Por omissão é `member`, o nível que a consola e o antigo percurso de partilha sempre usaram, para que a mesma chamada signifique o mesmo a partir de um script e de um ecrã. Para conceder níveis diferentes, chame depois `grantAddress` para os endereços que diferem.
Resposta
objectstring- Sempre `member`. Uma remoção responde com o mesmo valor, o seu `userId`, `deleted` definido como true e `addressesRevoked`, e nenhum dos outros campos abaixo.
userIdstring- O id da conta da pessoa, e o identificador que todas as outras chamadas de membros recebem como primeiro argumento: `get`, `update`, `remove` e as quatro chamadas de concessão e revogação. Adicionar alguém é a única chamada que funciona a partir de um email, porque quem adiciona um colega sabe o endereço dele e não o id.
emailstring- O email na conta deles, ecoado tal como essa linha o guarda. Este recurso nunca o escreve, e a passagem a minúsculas em `add` aplica-se ao endereço que envia para a procura e não ao que volta. Depois do dono, a lista de membros é ordenada por ele e não por quando as pessoas entraram, porque a lista é lida para encontrar uma pessoa e não para ver o que mudou.
namestring or null- O nome visível da pessoa, retirado da sua conta, onde a coluna tem sempre um valor. O null no tipo é defensivo e não um estado que se tenha visto esta API produzir. Pertence à pessoa e não ao espaço de trabalho, por isso nada neste recurso o pode definir.
imagestring or null- O avatar deles, tirado da conta, e null quando não definiram nenhum.
role.idstring or null- O id da função que a pessoa tem, lido como `$member['role']['id']`, ou null quando ninguém a escolheu. Veja `implied`. Um null aqui é o único caso em que `role` indica uma inferência em vez de uma decisão que alguém tomou.
role.namestring- O nome da função. Para um membro implícito, é o nome do modelo integrado a que o seu acesso corresponde, não uma linha deste espaço de trabalho.
role.builtinstring or null- Que função integrada é, `owner`, `admin`, `member`, `viewer`, `developer` ou `billing`, ou null para uma personalizada. `owner` aparece apenas na linha do próprio proprietário, ao lado de `isOwner` igual a true. Atribuir essa função a alguém é recusado com `role_immutable` (409).
isOwnerbool- True em exatamente uma linha, a conta a que a workspace está associada. Têm todas as permissões independentemente do que diga a sua linha de papel, ordenam-se em primeiro lugar, e `add`, `update` e `remove` recusam-nos todos com `member_is_owner`. Exclua-os quando estiver a contar lugares.
impliedbool- True quando esta pessoa tem concessões de endereço ou de domínio e nenhuma linha de membro, por isso a sua função foi inferida em vez de escolhida: qualquer concessão `member` torna-a a função integrada Member, caso contrário Viewer. Nunca é true para o proprietário. Mostre-o como «implícita pelo acesso». Até um `update` transformar a inferência numa decisão, alargar o seu acesso a endereços alarga silenciosamente o que pode fazer.
permissionsarray- As permissões da função copiadas para o membro, para que uma única leitura responda a «pode?» sem ir buscar a função. Para um membro implícito, vêm do MODELO integrado e não da linha de função deste espaço de trabalho, por isso editar a função integrada Member não muda o que um membro implícito tem.
addressesarray- Os endereços que lhes foram dados, ordenados por endereço, cada um num array com o seu próprio nível de acesso. Vazio para alguém com uma função e nenhuma concessão, que é o aspeto de um novo membro até lhe ser concedido um endereço, e é a falha certa a ter enquanto ainda está a decidir o que devem ver.
addresses[].addressIdstring- O id do endereço, e o que `grantAddress` e `revokeAddress` recebem. Um id que não seja um endereço desta workspace é recusado em ambos, em vez de reportar uma revogação que nunca aconteceu.
addresses[].addressstring- O endereço completo, em minúsculas, reconstruído a partir da sua parte local e do seu domínio.
addresses[].accessstring- O que a pessoa pode fazer com este endereço em concreto: `member` lê-o e envia como ele, `viewer` apenas o lê. Tanto isto como a função têm de permitir um envio para que ele aconteça, por isso uma função com `emails:send` sobre uma concessão `viewer` não envia a partir de nada. A coluna guardada chama-se `role`, e é renomeada aqui para que um array não tenha duas chaves `role` tiradas de dois vocabulários.
domainsarray- Os domínios inteiros que foram dados à pessoa, cada um com `domainId`, `domain` e `access`. Uma concessão de domínio alcança todos os endereços desse domínio, incluindo os criados depois, por isso leia-a ao lado de `addresses` antes de concluir que alguém não alcança um endereço. `grantDomain` e `revokeDomain` recebem o `domainId`.
createdAtstring or null- Quando a linha de membro da pessoa foi escrita, como string ISO 8601, e null quando não existe linha de membro nenhuma. Esse null descreve a mesma população que `implied` igual a true: pessoas que têm concessões de antes de as funções existirem e a quem ninguém deu uma função desde então.
Convites
$waiting = $client->members->listAllInvitations(); foreach ($waiting as $invitation) { if ($invitation['expired']) { $client->members->resendInvitation($invitation['id']); }} $client->members->revokeInvitation('winv_6bb640f5b99e47deb758f1f5');add responde com um convite, e estas são as chamadas que lhe dão seguimento. listInvitations devolve uma OpenEmail\Result\Page dos convites que ninguém aceitou ainda, listAllInvitations devolve-os todos num único array, e iterateInvitations devolve um Generator que entrega um de cada vez. resendInvitation volta a enviar um com uma nova ligação e mais catorze dias, e revokeInvitation retira-o. Um convite pendente não concede nada até ser aceite.
Um convite é um array com id, email, role, addresses, domains, expiresAt, expired, lastSentAt e createdAt. delivered e deliveryError indicam o que aconteceu ao último email de convite, para que um script consiga distinguir um convite que foi escrito de um que chegou a alguém.
resendInvitation recusa o mesmo endereço duas vezes em dez minutos com 409 invitation_too_soon, e revokeInvitation recusa um convite que já tenha sido aceite com 409 invitation_accepted. Ambos são lançados como ConflictException, por isso isConflict() é true e errorCode distingue-os.