Funções
`roles.list`, `list_all`, `iterate`, `get`, `create`, `update`, `delete` e `list_permissions`.
Todos os métodos
from openemail import openemail roles = openemail.roles.list()role = openemail.roles.get('role_…') support = openemail.roles.create({ 'name': 'Support', 'description': 'Answers the shared inboxes and nothing else.', 'permissions': ['emails:send', 'threads:write', 'labels:write'],}) print(support['permissions']) openemail.roles.update(support['id'], { 'permissions': [*support['permissions'], 'templates:read'],}) openemail.roles.delete(support['id'], reassign_to='role_…') vocabulary = openemail.roles.list_permissions()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á grant_address e revoke_address. «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. Uma permissão responde às duas: uma função com addresses:all alcança todos os endereços, incluindo os que forem adicionados depois, sem concessão, e só uma pessoa na aplicação a pode pôr numa função.
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 reassign_to 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.
list_permissions() é GET /roles/permissions, um caminho fixo que fica exatamente onde iria o id de uma função, por isso get('permissions') chega ao mesmo endpoint e responde com a lista de permissões em vez de uma função. '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
namestrobrigató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.
descriptionstr- 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.
permissionslist[Permission]obrigatório- O que a função concede, retirado do vocabulário que `list_permissions()` 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
objectLiteral['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.
idstr- 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 `reassign_to` recebe quando esta função é eliminada.
namestr- 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.
descriptionstr | None- 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.
permissionslist[Permission]- 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.
builtinLiteral['owner', 'admin', 'member', 'viewer', 'developer', 'billing'] | None- 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.
editablebool- 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.
deletablebool- 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 `reassign_to`, ou o delete é `role_in_use` (409).
membersint- 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.
apiKeysint- 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.
createdAtstr- 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.
updatedAtstr- 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.
Códigos de verificação
update e delete pedem um código de verificação a um token de acesso OAuth antes de alterarem o que quer que seja, e create não. A chamada lança um OpenEmailApiError cujo is_step_up_required é True: peça um código com security.begin_step_up(), verifique o que a pessoa lhe der com security.verify_step_up({'code': ...}) e depois faça a chamada de novo. Uma verificação é válida durante 60 minutos, e a uma chave de API nunca é pedido.