Funções
`roles.list`, `get`, `create`, `update`, `delete` e `listPermissions`.
Todos os métodos
const roles = await openemail.roles.list()const role = await openemail.roles.get('role_…') const support = await openemail.roles.create({ name: 'Support', description: 'Answers the shared inboxes and nothing else.', permissions: ['emails:send', 'threads:write', 'labels:write'],}) console.log(support.permissions) await openemail.roles.update(support.id, { permissions: [...support.permissions, 'templates:read'],}) await openemail.roles.delete(support.id, { reassignTo: 'role_…' }) const vocabulary = await openemail.roles.listPermissions()support.permissions contém seis entradas, não três: emails:send traz emails:read, threads:write traz threads:read e labels:write traz labels:read. Leia a lista de volta em vez de assumir.
Uma função diz o que alguém PODE FAZER. A que ENDEREÇOS o pode fazer é o outro eixo e vive em openemail.members. Veja lá grantAddress e revokeAddress. «Pode enviar correio» e «pode enviar como invoices@» são frases diferentes, e um workspace que contrata um segundo agente de apoio altera a segunda sem tocar na primeira.
Decida com base em editable e deletable, e não pelo nome de builtin. Ambos são false apenas para o proprietário, cuja lista é «todas as permissões, incluindo as que forem inventadas para o ano» e é calculada em vez de armazenada; todas as outras funções respondem true a ambos, incluindo as cinco com que um workspace é semeado. Uma função que alguém renomeou continua a responder corretamente a ambos, e o seu nome já não lhe diz nada.
update SUBSTITUI a lista de permissões. Não existe uma chamada para conceder uma só, por isso leia a função, altere a entrada que pretendia e devolva-as todas. Enviar uma permissão deixa a função a deter exatamente essa, mais o que ela implicar.
delete exige reassignTo assim que alguém detiver a função, e este viaja como parâmetro de query porque um corpo em DELETE é descartado por vários runtimes e por um bom número de proxies. O resultado indica reassigned e keysReassigned em separado, para que um script possa registar o que fez e não o que pediu.
listPermissions() é GET /roles/permissions, um caminho fixo que fica exatamente onde iria o id de uma função. O cliente codifica-o diretamente em vez de passar a string por get, por isso pedir uma função realmente chamada «permissions» pede uma função e recebe um 404, que é a resposta honesta ao que foi escrito. scope: false marca as entradas que chave nenhuma pode alguma vez deter.
Uma função é o teto de uma chave
Uma chave emitida contra uma função pode fazer a INTERSEÇÃO dos seus próprios scopes com as permissões dessa função, resolvida por pedido na fronteira. Restringir uma função revoga assim as suas chaves em direto, sem que nenhuma delas seja rodada, e uma chave sem função não tem teto nenhum, o que faz de uma função null o estado mais amplo em que uma chave pode estar, e não o mais restrito.
É também por isso que roles.delete insiste em ter para onde mover as chaves. Deixá-las órfãs eliminaria por completo o seu teto, promovendo em silêncio todas as credenciais que a função limitava.
GET /keys/self e GET /ping devolvem roleId e grantedScopes ao lado dos scopes efetivos, que é como se responde a «a minha chave tem emails:send e estou a receber insufficient_scope»: tudo o que esteja em grantedScopes e falte em scopes foi retirado pela função. openemail.me.get() e openemail.me.ping() devolvem ambos, com tipos.
Parâmetros
namestringobrigatório- O nome que o workspace dá à função: 1 a 48 caracteres, aparado antes de ser armazenado. Os nomes são únicos por workspace sem distinguir maiúsculas de minúsculas, pelo que um segundo "Support" é recusado com `role_name_taken` (409) em vez de criado ao lado do primeiro.
descriptionstring- Uma frase a dizer para que serve a função, aparada e com 240 caracteres no máximo. Uma string que fique vazia depois de aparada é armazenada como null, por isso uma descrição feita de espaços volta como null e não como aquilo que enviou.
permissionsPermission[]obrigatório- O que a função concede, retirado do vocabulário que `listPermissions()` serve; uma string que não conste dele é um 422 em `permissions` em vez de ser descartada em silêncio, por isso uma gralha é comunicada em vez de lhe custar uma tarde. A lista é EXPANDIDA à entrada (`templates:write` guarda `templates:read` ao seu lado), desduplicada e reposta por ordem canónica, por isso leia a lista armazenada a partir da resposta em vez de assumir que é a que enviou.
Resposta
object'role'- Sempre `role`. A lápide devolvida pelo delete responde com o mesmo valor, o `id` da função, `deleted: true` e as duas contagens de reatribuição, e com nenhum dos outros campos abaixo.
idstring- O id da função. É o que o `roleId` de um membro nomeia, aquilo para onde aponta o teto de uma chave de API, e o que `reassignTo` recebe quando esta função é eliminada.
namestring- O nome que o workspace dá à função, aparado e único sem distinguir maiúsculas de minúsculas. Todas as funções, menos a do proprietário, podem ser renomeadas, incluindo as semeadas (`builtin` diz de onde veio uma linha, não como ela tem de continuar a chamar-se), por isso não leia "Admin" como uma promessa sobre o que a função detém. Um nome a que outra função já responde dá `role_name_taken` (409, `param: "name"`); renomear o proprietário dá `role_immutable` (409), tal como qualquer outra edição dele.
descriptionstring | null- A frase que descreve a função, ou null quando não foi dada nenhuma. Entrada em branco é armazenada como null tanto no create como no update, por isso isto nunca é uma string vazia.
permissionsPermission[]- Tudo o que a função concede, já expandido e por ordem canónica, e não pela ordem em que alguém o escreveu. Essa ordenação é estrutural: duas funções que detenham as mesmas permissões comparam-se como iguais enquanto JSON, que é o que permite a um ecrã de definições compará-las para decidir se o Guardar fica ativo.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- De qual das seis funções semeadas veio esta linha, ou null para uma que o próprio workspace escreveu. Regista a origem e não um estado: uma função semeada é renomeada, repermissionada e eliminada como qualquer outra. Decida com base em `editable` e `deletable`, e não nisto. Uma função a que alguém chamou "Admin" não tem de ser a semeada, e a semeada pode já não se chamar assim.
editableboolean- Calculado como `builtin !== 'owner'`, pelo que é false apenas para a função de proprietário e todos os PATCH dessa função são recusados com `role_immutable` (409). Todas as outras funções são editáveis por completo (nome, descrição e permissões), incluindo as cinco com que um workspace é semeado.
deletableboolean- Calculado como `builtin !== 'owner'`: false apenas para a função de proprietário, que volta com `role_undeletable` (409), e true para todas as outras, incluindo as semeadas. Verifique-o antes de oferecer o botão e não depois da recusa, embora uma função que alguém ainda detenha precise também de `reassignTo`, ou o delete é `role_in_use` (409).
membersnumber- Quantas pessoas detêm esta função, contadas a partir das linhas de membro do workspace. O proprietário não está entre elas: não tem linha de membro e não lhe pode ser atribuída uma função, por isso a função Owner comunica zero detentores mesmo quando a lista de membros o mostra.
apiKeysnumber- Quantas chaves de API vivas estão limitadas por esta função; as chaves revogadas ficam de fora da contagem, embora um delete volte a apontar todas as linhas de chave que apontavam para a função, incluindo as revogadas. É a segunda população que tem de ser movida antes de a função poder desaparecer, e aquela de que ninguém dá conta: as chaves são programas, e um programa não se queixa.
createdAtstring- Quando a linha da função foi escrita, ISO-8601. As linhas integradas são semeadas de forma preguiçosa na primeira vez que algo precisa delas — uma leitura da lista de funções, a criação de uma função ou o ecrã das chaves de API — e não na criação do workspace, por isso o timestamp de uma função integrada é o momento em que esse primeiro pedido chegou e não aquele em que o workspace foi criado.
updatedAtstring- Quando a função mudou pela última vez, ISO-8601. Todos os PATCH aceites a movem, incluindo um que defina um campo com o valor que ele já tinha.