Funções
`roles.list`, `list_all`, `iterate`, `get`, `create`, `update`, `delete` e `list_permissions`.
Todos os métodos
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] 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 devolvida em vez de a dar por adquirida.
list devolve uma OpenEmail::Page, list_all devolve todas as funções num único Array, e iterate passa cada função a um bloco ou devolve um Enumerator quando não há bloco. Uma função volta como um Hash com chaves Symbol, por isso role[:permissions] lê a lista. create e update aceitam os campos do corpo como argumentos nomeados ou como um único Hash, enquanto delete aceita reassign_to:, um argumento nomeado em snake_case que a gem renomeia para a API.
Uma função diz o que alguém PODE FAZER. A que ENDEREÇOS o pode fazer é o outro eixo e fica em client.members: veja grant_address e revoke_address na página Membros. «Pode enviar correio» e «pode enviar como invoices@» são frases diferentes, e um espaço de trabalho 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 atribuir a uma função.
Baseie a lógica em editable e deletable, e não em builtin nem no nome. 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 guardada. Todas as outras funções respondem true a ambos, incluindo as cinco com que um espaço de trabalho é 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, como faz [*support[:permissions], "templates:read"] acima. Enviar uma permissão deixa a função com exatamente essa, mais o que ela implicar.
delete exige reassign_to: assim que alguém detiver a função. A gem envia-o como o parâmetro de consulta reassignTo, porque um corpo em DELETE é descartado por vários runtimes e por um bom número de proxies, e omite o parâmetro quando não passa nada. 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. A gem chama esse caminho diretamente em vez de passar a palavra por get, e devolve um Array simples, não uma OpenEmail::Page: um Hash por permissão, com id, label, group e scope. scope: false marca as entradas que nenhuma chave pode alguma vez ter. Não passe a palavra a get você mesmo. client.roles.get("permissions") constrói o mesmo caminho, por isso envia o mesmo pedido e recebe o vocabulário em vez de uma função ou de um 404.
Uma função é o teto de uma chave
Uma chave emitida sob uma função só pode fazer a INTERSEÇÃO dos seus próprios âmbitos com as permissões dessa função, resolvida por pedido na fronteira. Assim, restringir uma função revoga as suas chaves em direto, sem que nenhuma delas seja rodada. Uma chave sem função não tem teto nenhum, o que faz de um roleId nil 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. É assim que 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. client.me.get e client.me.ping devolvem ambos no seu Hash, por isso key[:grantedScopes] - key[:scopes] lista o que a função retirou. A recusa em si é um OpenEmail::PermissionError cujo scope_missing? é true.
Parâmetros
nameStringobrigatório- O nome que o espaço de trabalho dá à função: 1 a 48 caracteres, aparado antes de ser guardado. Os nomes são únicos por espaço de trabalho sem distinguir maiúsculas de minúsculas, pelo que um segundo «Support» é recusado com `role_name_taken` (409), lançado como `OpenEmail::ConflictError`, em vez de ser 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 é guardada como nil, por isso uma descrição feita de espaços volta como nil e não como aquilo que enviou. Em `create`, omita-a em vez de passar nil: a gem envia um nil tal como está, e `create` recusa-o com um 422. Em `update`, `description: nil` apaga-a.
permissionsArray<String>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`, lançado como `OpenEmail::ValidationError` com `param` definido como `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 guardada a partir da resposta em vez de assumir que é a que enviou.
Resposta
objectString- Sempre `role`. A lápide devolvida pela eliminação 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, lido como `role[:id]`. É 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 outra função é eliminada e os seus titulares passam para esta.
nameString- O nome que o espaço de trabalho 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 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, com `param` definido como `name`). Renomear o proprietário dá `role_immutable` (409), tal como qualquer outra edição dele.
descriptionString or nil- A frase que descreve a função, ou nil quando não foi dada nenhuma. Uma entrada em branco é guardada como nil tanto na criação como na atualização, por isso isto nunca é uma string vazia.
permissionsArray<String>- 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 com as mesmas permissões têm Arrays iguais, que é o que permite a um ecrã de definições compará-las com `==` para decidir se o botão Guardar fica ativo.
builtinString or nil- De qual das seis funções semeadas veio esta linha, `owner`, `admin`, `member`, `viewer`, `developer` ou `billing`, ou nil para uma que o próprio espaço de trabalho escreveu. Regista a origem e não um estado: uma função semeada é renomeada, recebe outras permissões e é eliminada como qualquer outra. Baseie a lógica em `editable` e `deletable`, e não neste campo. 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 `update` 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 espaço de trabalho é 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 funções, incluindo as semeadas. Verifique-o antes de oferecer o botão e não depois da recusa. Uma função que alguém ainda detenha também precisa de `reassign_to:`, caso contrário a eliminação dá `role_in_use` (409). Ambas as recusas são lançadas como `OpenEmail::ConflictError`, e `code` distingue-as.
membersInteger- Quantas pessoas detêm esta função, contadas a partir das linhas de membro do espaço de trabalho. 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 indica zero titulares mesmo quando a lista de membros o mostra.
apiKeysInteger- Quantas chaves de API ativas estão limitadas por esta função. As chaves revogadas ficam de fora da contagem, embora uma eliminação 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, como String ISO 8601. As linhas integradas são semeadas de forma preguiçosa na primeira vez que algo precisa delas, como 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 espaço de trabalho. Por isso, o carimbo temporal de uma função integrada é o momento em que esse primeiro pedido chegou e não aquele em que o espaço de trabalho foi criado.
updatedAtString- Quando a função mudou pela última vez, como String ISO 8601. Todos os `update` aceites o fazem avançar, incluindo um que defina um campo com o valor que já tinha.