역할
`roles->list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete`, `listPermissions`.
모든 메서드
use OpenEmail\Constants\ApiScopes; $page = $client->roles->list();echo count($page), PHP_EOL; $role = $client->roles->get('role_8b1f4c2e9a7d3b60e5f1a2c4');echo $role['name'], PHP_EOL; $support = $client->roles->create([ 'name' => 'Support', 'description' => 'Answers the shared inboxes and nothing else.', 'permissions' => [ApiScopes::EMAILS_SEND, ApiScopes::THREADS_WRITE, ApiScopes::LABELS_WRITE],]); echo implode(', ', $support['permissions']), PHP_EOL; $client->roles->update($support['id'], ['permissions' => [...$support['permissions'], ApiScopes::TEMPLATES_READ]]); $client->roles->delete($support['id'], reassignTo: $role['id']); $vocabulary = $client->roles->listPermissions();echo implode(', ', array_column($vocabulary, 'id')), PHP_EOL;$support['permissions']에는 세 개가 아니라 여섯 개가 들어 있습니다: emails:send는 emails:read를, threads:write는 threads:read를, labels:write는 labels:read를 함께 가져옵니다. 짐작하지 말고 목록을 다시 읽으세요.
list는 OpenEmail\Result\Page 하나를 반환하고, listAll은 모든 역할을 하나의 배열로 반환하며, iterate는 역할을 하나씩 yield하는 Generator를 반환합니다. 역할은 camelCase 키를 가진 배열로 돌아오므로 $role['permissions']로 목록을 읽습니다. create와 update는 본문을 API의 이름을 쓰는 배열 하나로 받고, delete는 reassignTo:를 명명된 인자로 받습니다.
역할은 그 사람이 무엇을 해도 되는지를 말합니다. 어떤 주소에 대해 할 수 있는지는 다른 축이며 $client->members에 있습니다: 멤버 페이지의 members->grantAddress와 members->revokeAddress를 참고하세요. “메일을 보낼 수 있다”와 “invoices@로 보낼 수 있다”는 서로 다른 문장이며, 지원 담당을 한 명 더 채용한 워크스페이스는 앞의 것은 건드리지 않고 뒤의 것만 바꿉니다. 두 문장 모두에 답하는 권한이 하나 있습니다: addresses:all을 가진 역할은 부여 없이도 나중에 추가되는 주소까지 모든 주소에 닿으며, 이를 역할에 넣을 수 있는 것은 앱에 있는 사람뿐입니다.
builtin이나 이름이 아니라 editable과 deletable로 분기하세요. 둘 다 false인 것은 소유자 역할뿐이며, 그 권한 목록은 “내년에 새로 생길 것까지 포함한 모든 권한”으로 저장되는 대신 계산됩니다. 워크스페이스에 기본 제공되는 다섯 개를 포함해 나머지 역할은 모두 두 값이 true입니다. 누군가 이름을 바꾼 역할도 두 값은 정확히 답하지만, 그 이름은 더 이상 아무것도 알려 주지 않습니다.
update는 권한 목록을 통째로 교체합니다. 권한 하나만 부여하는 호출은 없으므로, 위의 [...$support['permissions'], ApiScopes::TEMPLATES_READ]처럼 역할을 읽어서 의도한 항목만 바꾼 뒤 전체를 다시 보내세요. 권한 하나만 보내면 그 역할에는 그 하나와 그것이 함축하는 권한만 남습니다.
누군가 그 역할을 갖고 있는 순간부터 delete에는 reassignTo:가 필요합니다. 클라이언트는 이를 reassignTo 쿼리 파라미터로 보내는데, DELETE의 본문은 여러 런타임과 적지 않은 프록시가 버리기 때문이며, 아무것도 전달하지 않으면 파라미터를 생략합니다. 결과는 reassigned와 keysReassigned를 따로 보고하므로, 스크립트가 요청한 내용이 아니라 실제로 수행한 내용을 기록할 수 있습니다.
listPermissions는 GET /roles/permissions로, 정확히 역할 id가 들어갈 자리에 놓인 고정 경로입니다. 클라이언트는 그 단어를 get에 넘기는 대신 그 경로를 직접 호출하며, OpenEmail\Result\Page가 아니라 일반 리스트를 반환합니다: 권한마다 하나의 배열로, id, label, group, scope를 가집니다. scope가 false인 항목은 어떤 키도 가질 수 없는 항목입니다. 그 단어를 직접 get에 넘기지 마세요. $client->roles->get('permissions')는 같은 경로를 만들기 때문에 같은 요청을 보내고, 역할이나 404가 아니라 목록 봉투에 담긴 어휘를 돌려받습니다.
역할은 키의 상한이다
역할에 묶여 발급된 키는 자신의 스코프와 그 역할의 권한을 교집합한 만큼만 할 수 있으며, 이는 요청마다 경계에서 계산됩니다. 따라서 역할을 좁히면 키를 하나도 회전하지 않고도 그 키들의 권한이 즉시 회수됩니다. 역할이 없는 키에는 상한이 전혀 없으므로, null인 roleId는 키가 가질 수 있는 가장 좁은 상태가 아니라 가장 넓은 상태입니다.
roles->delete가 키를 옮길 곳을 반드시 요구하는 이유도 같습니다. 키를 고아로 남기면 상한이 통째로 사라져, 그 역할이 제한하고 있던 모든 자격 증명이 조용히 승격됩니다.
GET /keys/self와 GET /ping은 실제 적용되는 scopes 옆에 roleId와 grantedScopes를 함께 보고합니다. “내 키에는 emails:send가 있는데 insufficient_scope가 납니다”라는 질문은 이렇게 답합니다: grantedScopes에는 있는데 scopes에는 없는 것은 역할이 걷어낸 것입니다. $client->me->get()과 $client->me->ping()은 둘 다 배열로 반환하므로, array_diff($key['grantedScopes'], $key['scopes'])로 역할이 걷어낸 것을 나열할 수 있습니다. 거부 자체는 isScopeMissing()이 true인 PermissionException입니다.
매개변수
namestring필수- 워크스페이스가 이 역할을 부르는 이름입니다: 1자에서 48자이고 저장 전에 앞뒤 공백을 제거합니다. 이름은 워크스페이스 안에서 대소문자를 구분하지 않고 고유해야 하므로, 두 번째 “Support”는 첫 번째 옆에 새로 만들어지지 않고 `role_name_taken`(409)으로 거부되며, 이는 `ConflictException`으로 던져집니다.
descriptionstring- 역할의 용도를 설명하는 한 문장이며, 앞뒤 공백을 제거하고 최대 240자입니다. 공백을 제거했을 때 비어 있는 문자열은 null로 저장되므로, 공백으로만 된 설명은 보낸 그대로가 아니라 null로 돌아옵니다. `create`에서는 null을 전달하지 말고 키를 생략하세요: 클라이언트는 null을 그대로 보내고, `create`는 이를 422로 거부합니다. `update`에서는 `'description' => null`로 지웁니다.
permissionsarray필수- 역할이 부여하는 권한이며, `listPermissions`가 제공하는 어휘에서 가져옵니다. 거기에 없는 문자열은 조용히 버려지지 않고 `permissions`에 대한 422가 되며, `param`이 `permissions`인 `ValidationException`으로 던져지므로, 오타 하나로 오후를 통째로 날리는 대신 바로 보고받습니다. 목록은 들어올 때 확장되고(`templates:write`는 `templates:read`도 함께 저장합니다), 중복이 제거되며, 정해진 순서로 재배열됩니다. 따라서 보낸 목록이 그대로라고 가정하지 말고 응답에서 저장된 목록을 읽으세요.
응답
objectstring- 항상 `role`입니다. 삭제 시의 묘비 응답도 같은 값과 함께 역할의 `id`, true인 `deleted`, 두 가지 재할당 개수만 돌려주고, 아래의 다른 필드는 돌려주지 않습니다.
idstring- 역할의 id로, `$role['id']`로 읽습니다. 멤버의 `roleId`가 가리키는 값이자, API 키의 상한이 가리키는 값이며, 다른 역할이 삭제되어 그 보유자가 이 역할로 옮겨 올 때 `reassignTo:`가 받는 값입니다.
namestring- 워크스페이스가 이 역할에 붙인 이름이며, 앞뒤 공백을 제거하고 대소문자를 구분하지 않고 고유합니다. 소유자 역할을 제외한 모든 역할은 기본 제공된 것을 포함해 이름을 바꿀 수 있으므로(`builtin`은 그 행이 어디서 왔는지를 말할 뿐, 계속 그 이름이어야 한다는 뜻이 아닙니다), “Admin”이라는 역할이라고 해서 그 역할이 무엇을 가졌는지 확실히 알 수는 없습니다. 다른 역할이 이미 쓰고 있는 이름은 `role_name_taken`(409, `param`은 `name`)이고, 소유자 역할의 이름을 바꾸는 것은 그 역할의 다른 모든 수정과 마찬가지로 `role_immutable`(409)입니다.
descriptionstring or null- 역할을 설명하는 문장이며, 주어지지 않았으면 null입니다. 생성과 수정 모두에서 빈 입력은 null로 저장되므로, 이 값이 빈 문자열이 되는 일은 없습니다.
permissionsarray- 역할이 부여하는 모든 권한이며, 누가 입력한 순서가 아니라 이미 확장되어 정해진 순서로 정렬된 상태입니다. 이 정렬은 중요한 역할을 합니다: 같은 권한을 가진 두 역할은 같은 배열을 가지며, 덕분에 설정 화면이 `===`로 둘을 비교해 저장 버튼을 켤지 말지 결정할 수 있습니다.
builtinstring or null- 이 행이 기본 제공되는 여섯 역할(`owner`, `admin`, `member`, `viewer`, `developer`, `billing`) 중 어디에서 왔는지이며, 워크스페이스가 직접 만든 역할이면 null입니다. 상태가 아니라 출처를 기록할 뿐입니다: 기본 제공 역할도 다른 역할과 똑같이 이름을 바꾸고 권한을 바꾸고 삭제할 수 있습니다. 이 값이 아니라 `editable`과 `deletable`로 분기하세요. 누군가 “Admin”이라고 부르는 역할이 기본 제공 역할이 아닐 수 있고, 기본 제공 역할이 더 이상 그 이름이 아닐 수도 있습니다.
editablebool- `builtin !== 'owner'`로 계산되므로 소유자 역할에서만 false이며, 그 역할에 대한 `update`는 모두 `role_immutable`(409)로 거부됩니다. 워크스페이스에 기본 제공되는 다섯 개를 포함한 나머지 역할은 이름, 설명, 권한까지 전부 수정할 수 있습니다.
deletablebool- `builtin !== 'owner'`로 계산됩니다: 소유자 역할에서만 false이며 그 경우 `role_undeletable`(409)로 돌아오고, 기본 제공 역할을 포함한 나머지 역할에서는 true입니다. 거부당한 뒤가 아니라 버튼을 보여 주기 전에 확인하세요. 아직 누군가 갖고 있는 역할에는 `reassignTo:`도 필요하며, 없으면 삭제는 `role_in_use`(409)입니다. 두 거부 모두 `ConflictException`으로 던져지며, `errorCode`로 구분할 수 있습니다.
membersint- 이 역할을 가진 사람 수이며, 워크스페이스의 멤버 행에서 셉니다. 소유자는 여기에 포함되지 않습니다: 소유자는 멤버 행이 없고 역할을 부여받을 수도 없으므로, 멤버 목록에는 소유자가 보이더라도 Owner 역할의 보유자 수는 0으로 보고됩니다.
apiKeysint- 이 역할이 상한을 두고 있는 유효한 API 키 수입니다. 폐기된 키는 이 수에서 제외되지만, 삭제 시에는 폐기된 키를 포함해 이 역할을 가리키는 모든 키 행이 다시 연결됩니다. 역할을 없애기 전에 옮겨야 하는 두 번째 집단이자 아무도 알아채지 못하는 집단입니다: 키는 프로그램이고, 프로그램은 불평하지 않으니까요.
createdAtstring- 역할 행이 기록된 시각이며 ISO 8601 문자열입니다. 내장 역할 행은 워크스페이스를 만들 때가 아니라, 역할 목록 조회나 역할 생성, API 키 화면처럼 무언가 필요로 하는 순간 처음으로 지연 생성됩니다. 그래서 내장 역할의 타임스탬프는 워크스페이스가 만들어진 때가 아니라 그 첫 요청이 들어온 때입니다.
updatedAtstring- 역할이 마지막으로 변경된 시각이며 ISO 8601 문자열입니다. 이미 갖고 있던 값을 그대로 설정하는 것을 포함해, 수락된 모든 `update`가 이 값을 갱신합니다.