Rolet
`roles.list`, `get`, `create`, `update`, `delete` dhe `listPermissions`.
Çdo metodë
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 mban gjashtë zëra, jo tre: emails:send sjell emails:read, threads:write sjell threads:read dhe labels:write sjell labels:read. Lexojeni listën nga përgjigjja, në vend që ta merrni të mirëqenë.
Një rol thotë çfarë mund të BËJË dikush. Se në cilat ADRESA mund ta bëjë, është boshti tjetër dhe qëndron te openemail.members. Shihni grantAddress dhe revokeAddress atje. “Mund të dërgojë postë” dhe “mund të dërgojë si invoices@” janë fjali të ndryshme, dhe një hapësirë pune që punëson një agjent të dytë mbështetjeje ndryshon të dytën pa prekur të parën.
Degëzoni sipas editable dhe deletable, jo sipas emrit te builtin. Të dyja janë false vetëm për pronarin, lista e të cilit është “çdo leje, përfshirë ato që do të shpiken vitin tjetër” dhe llogaritet në vend që të ruhet; çdo rol tjetër u përgjigjet të dyjave me true, përfshirë të pesë rolet me të cilat mbillet një hapësirë pune. Një rol që dikush e ka riemërtuar u përgjigjet ende saktë të dyjave, kurse emri i tij nuk ju thotë më asgjë.
update E ZËVENDËSON listën e lejeve. Nuk ka thirrje për të dhënë një leje të vetme, ndaj lexoni rolin, ndryshoni zërin që kishit parasysh dhe dërgojini të gjitha përsëri. Dërgimi i një leje të vetme e lë rolin me pikërisht atë, plus çdo gjë që ajo nënkupton.
delete kërkon reassignTo sapo dikush e mban rolin, dhe ky udhëton si parametër query, sepse një trup në DELETE hidhet tej nga disa runtime dhe nga një numër proxy-sh. Rezultati raporton reassigned dhe keysReassigned veç e veç, që një skript të mund të regjistrojë çfarë bëri e jo çfarë kërkoi.
listPermissions() është GET /roles/permissions, një shteg fiks që ndodhet pikërisht aty ku do të vinte një id roli. Klienti e ka të koduar fiks, në vend që ta kalojë vargun përmes get, ndaj kërkimi i një roli që quhet vërtet “permissions” kërkon një rol dhe merr një 404, që është përgjigjja e ndershme për atë që u shkrua. scope: false shënon zërat që asnjë çelës nuk mund t'i mbajë kurrë.
Roli është tavani i një çelësi
Një çelës i lëshuar kundrejt një roli mund të bëjë scope-et e veta NË PRERJE me lejet e atij roli, të zgjidhura për çdo kërkesë në kufi. Kështu, ngushtimi i një roli ua heq të drejtat çelësave të tij në çast, pa u rrotulluar asnjëri prej tyre; kurse një çelës pa rol nuk ka fare tavan, gjë që e bën rolin null gjendjen më të gjerë në të cilën mund të jetë një çelës, jo më të ngushtën.
Kjo është edhe arsyeja pse roles.delete këmbëngul të ketë një vend ku t'i zhvendosë çelësat. Lënia e tyre jetimë do t'ua hiqte tavanin fare, duke ngritur në heshtje çdo kredencial që roli po e mbante të kufizuar.
GET /keys/self dhe GET /ping raportojnë roleId dhe grantedScopes përkrah scopes-it efektiv, dhe kështu merr përgjigje pyetja “çelësi im ka emails:send e prapë po marr insufficient_scope”: çdo gjë që ndodhet te grantedScopes dhe mungon te scopes është marrë nga roli. openemail.me.get() dhe openemail.me.ping() i kthejnë të dyja, me tipe.
Parametrat
namestringe detyrueshme- Si e quan rolin hapësira e punës: nga 1 deri në 48 karaktere, të pastruara nga hapësirat anësore para se të ruhen. Emrat janë unikë për çdo hapësirë pune pavarësisht shkronjave të mëdha a të vogla, ndaj një "Support" i dytë refuzohet me `role_name_taken` (409), në vend që të krijohet përkrah të parit.
descriptionstring- Një fjali që thotë për çfarë shërben roli, e pastruar nga hapësirat anësore dhe me më së shumti 240 karaktere. Një varg që mbetet bosh pas pastrimit ruhet si null, ndaj një përshkrim i bërë me hapësira kthehet si null e jo si ajo që dërguat.
permissionsPermission[]e detyrueshme- Çfarë jep roli, marrë nga fjalori që shërben `listPermissions()`; një varg që nuk gjendet aty është një 422 te `permissions`, në vend që të hidhet tej në heshtje, kështu që një gabim shtypi raportohet e nuk ju kushton një pasdite. Lista ZGJEROHET në hyrje (`templates:write` ruan `templates:read` përkrah tij), i hiqen dublikatat dhe rikthehet në renditjen kanonike, ndaj lexojeni listën e ruajtur nga përgjigjja e mos e merrni të mirëqenë se është ajo që dërguat.
Përgjigjja
object'role'- Gjithmonë `role`. Regjistrimi i fshirjes përgjigjet me të njëjtën vlerë, me `id`-në e rolit, me `deleted: true` dhe me dy numërimet e ricaktimit, dhe me asnjë nga fushat e tjera më poshtë.
idstring- Id-ja e rolit. Është ajo që emërton `roleId`-ja e një anëtari, ajo nga e cila tregon tavani i një çelësi API dhe ajo që merr `reassignTo` kur ky rol fshihet.
namestring- Emri që hapësira e punës i vë rolit, i pastruar nga hapësirat anësore dhe unik pavarësisht shkronjave të mëdha a të vogla. Çdo rol, përveç atij të pronarit, mund të riemërtohet, përfshirë edhe ata të mbjellët (`builtin` thotë nga erdhi një rresht, jo si duhet të vazhdojë të quhet), ndaj mos e lexoni "Admin" si premtim për atë që mban roli. Një emër të cilit i përgjigjet tashmë një rol tjetër është `role_name_taken` (409, `param: "name"`); riemërtimi i pronarit është `role_immutable` (409), si çdo redaktim tjetër i tij.
descriptionstring | null- Fjalia që përshkruan rolin, ose null kur nuk është dhënë asnjë. Hyrja bosh ruhet si null si te krijimi, ashtu edhe te përditësimi, ndaj kjo nuk është kurrë një varg bosh.
permissionsPermission[]- Gjithçka që jep roli, tashmë e zgjeruar dhe në renditje kanonike e jo në renditjen që shkroi dikush. Ajo renditje është mbajtëse: dy role me të njëjtat leje dalin të barabarta si JSON, gjë që i lejon një ekrani cilësimesh t'i krahasojë për të vendosur nëse butoni Ruaj është i aktivizuar.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- Nga cili prej gjashtë roleve të mbjellë vjen ky rresht, ose null për një rol që e shkroi vetë hapësira e punës. Ai regjistron mbjelljen dhe jo një status: një rol i mbjellë riemërtohet, i ndryshohen lejet dhe fshihet si çdo tjetër. Degëzoni sipas `editable` dhe `deletable`, jo sipas kësaj fushe. Një rol që dikush e quajti "Admin" nuk është domosdoshmërisht ai i mbjelluri, dhe ai i mbjelluri mund të mos quhet më ashtu.
editableboolean- Llogaritet si `builtin !== 'owner'`, ndaj është false vetëm për rolin e pronarit dhe çdo PATCH i atij roli refuzohet me `role_immutable` (409). Çdo rol tjetër është i redaktueshëm plotësisht (emri, përshkrimi dhe lejet), përfshirë të pesë rolet me të cilat mbillet një hapësirë pune.
deletableboolean- Llogaritet si `builtin !== 'owner'`: false vetëm për rolin e pronarit, i cili kthen `role_undeletable` (409), dhe true për çdo rol tjetër, përfshirë ata të mbjellët. Kontrollojeni para se të ofroni butonin e jo pas refuzimit, ndonëse një rol që dikush e mban ende kërkon gjithashtu `reassignTo`, përndryshe fshirja është `role_in_use` (409).
membersnumber- Sa veta e mbajnë këtë rol, numëruar nga rreshtat e anëtarëve të hapësirës së punës. Pronari nuk është mes tyre: ai nuk ka rresht anëtari dhe nuk mund t'i jepet një rol, ndaj roli Owner raporton zero mbajtës, edhe pse lista e anëtarëve e shfaq atë.
apiKeysnumber- Sa çelësa API të gjallë kufizohen nga ky rol; çelësat e revokuar lihen jashtë numërimit, ndonëse një fshirje i ridrejton të gjithë rreshtat e çelësave që tregojnë nga roli, përfshirë edhe ata të revokuarit. Ky është popullimi i dytë që duhet zhvendosur para se roli të mund të largohet, dhe ai që nuk e vë re askush: çelësat janë programe, dhe një program nuk ankohet.
createdAtstring- Kur u shkrua rreshti i rolit, ISO-8601. Rreshtat e integruar mbillen me përtaci herën e parë që diçka ka nevojë për ta — një lexim i listës së roleve, krijimi i një roli ose ekrani i çelësave API — e jo në krijimin e hapësirës së punës, ndaj vula kohore e një roli të integruar është çasti kur mbërriti ajo kërkesë e parë dhe jo kur u krijua hapësira e punës.
updatedAtstring- Kur ndryshoi roli për herë të fundit, ISO-8601. Çdo PATCH i pranuar e lëviz atë, përfshirë edhe një PATCH që i vendos një fushe vlerën që ajo kishte tashmë.