Rolet
`roles->list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` dhe `listPermissions`.
Çdo metodë
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'] mban gjashtë elemente, 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ë.
list kthen një OpenEmail\Result\Page, listAll i kthen të gjitha rolet në një array të vetëm, dhe iterate kthen një Generator që jep rolet një nga një. Një rol kthehet si array me çelësa në camelCase, ndaj $role['permissions'] lexon listën. create dhe update e marrin trupin si një array të vetëm me emrat e API-së, ndërsa delete merr reassignTo: si argument me emër.
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 $client->members: shihni members->grantAddress dhe members->revokeAddress te faqja e anëtarëve. “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. Një leje u përgjigjet të dyjave: një rol që mban addresses:all arrin çdo adresë, përfshirë ato që shtohen më vonë, pa asnjë dhënie të drejtash, dhe vetëm një person në aplikacion mund ta vërë atë në një rol.
Degëzoni sipas editable dhe deletable, jo sipas builtin ose emrit. 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 krijohet një hapësirë pune. Një rol që dikush e ka riemërtuar u përgjigjet ende saktë të dyjave, ndërsa 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 elementin që kishit parasysh dhe dërgojini të gjitha përsëri, siç bën më lart [...$support['permissions'], ApiScopes::TEMPLATES_READ]. 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. Klienti e dërgon si parametrin e query-t reassignTo, sepse një trup në DELETE hidhet tej nga disa runtime dhe nga një numër proxy-sh, dhe e lë parametrin jashtë kur nuk jepni asgjë. Rezultati raporton reassigned dhe keysReassigned veç e veç, që një skript të mund të regjistrojë çfarë bëri dhe jo çfarë kërkoi.
listPermissions është GET /roles/permissions, një shteg i fiksuar që ndodhet pikërisht aty ku do të shkonte një id roli. Klienti e thërret drejtpërdrejt atë shteg në vend që ta kalojë fjalën përmes get, dhe kthen një listë të thjeshtë, jo një OpenEmail\Result\Page: një array për çdo leje, me id, label, group dhe scope. scope false shënon elementet që asnjë çelës nuk mund t’i mbajë kurrë. Mos ia jepni vetë fjalën get. $client->roles->get('permissions') ndërton të njëjtin shteg, ndaj dërgon të njëjtën kërkesë dhe merr prapa fjalorin e lejeve në zarfin e tij të listës dhe jo një rol ose një 404.
Roli është tavani i një çelësi
Një çelës i lëshuar kundrejt një roli mund të bëjë fushat 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. Një çelës pa rol nuk ka fare tavan, gjë që e bën një roleId 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 pranë scopes efektive. Kështu merr përgjigje pyetja “çelësi im ka emails:send dhe po marr insufficient_scope”: çdo gjë që është te grantedScopes dhe mungon te scopes e ka marrë roli. $client->me->get() dhe $client->me->ping() i kthejnë të dyja në array-n e tyre, ndaj array_diff($key['grantedScopes'], $key['scopes']) liston çfarë mori roli. Vetë refuzimi është një PermissionException, isScopeMissing() i të cilit është true.
Parametrat
namestringe detyrueshme- Si e quan rolin hapësira e punës: 1 deri në 48 karaktere, i pastruar nga hapësirat anësore para se të ruhet. Emrat janë unikë për hapësirë pune pa dallim shkronjash të mëdha a të vogla, ndaj një “Support” i dytë refuzohet me `role_name_taken` (409), të hedhur si `ConflictException`, në vend që të krijohet pranë 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ë string që mbetet bosh pas pastrimit ruhet si null, ndaj një përshkrim prej hapësirash kthehet si null dhe jo si ajo që dërguat. Te `create`, lëreni çelësin jashtë në vend që të jepni null: klienti e dërgon null ashtu siç është, dhe `create` e refuzon me një 422. Te `update`, `'description' => null` e pastron.
permissionsarraye detyrueshme- Çfarë jep roli, e marrë nga fjalori që shërben `listPermissions`. Një string që nuk është në të jep një 422 te `permissions`, të hedhur si `ValidationException` me `param` të vendosur në `permissions`, në vend që të hidhet tej në heshtje, ndaj një gabim shtypi raportohet në vend që t’ju kushtojë një pasdite. Lista ZGJEROHET në hyrje (`templates:write` ruan `templates:read` pranë vetes), pastrohet nga dublikatat dhe vihet sërish në renditjen kanonike, ndaj lexojeni listën e ruajtur nga përgjigjja në vend që të supozoni se është ajo që dërguat.
Përgjigje
objectstring- Gjithmonë `role`. Shenja e fshirjes përgjigjet me të njëjtën vlerë, `id` e rolit, `deleted` të vendosur në true dhe dy numrat e ricaktimit, dhe asnjë nga fushat e tjera më poshtë.
idstring- Id-ja e rolit, e lexuar si `$role['id']`. Është ajo që emërton `roleId` i një anëtari, ajo te e cila tregon tavani i një çelësi API, dhe ajo që merr `reassignTo:` kur fshihet një rol tjetër dhe mbajtësit e tij kalojnë te ky.
namestring- Emri që i jep roli hapësira e punës, i pastruar nga hapësirat anësore dhe unik pa dallim shkronjash të mëdha a të vogla. Çdo rol përveç atij të pronarit mund të riemërtohet, përfshirë rolet fillestare (`builtin` thotë nga erdhi një rresht, jo si duhet të vazhdojë të quhet), ndaj një rol i quajtur “Admin” nuk thotë asgjë të sigurt për atë që mban. Një emër që e ka tashmë një rol tjetër jep `role_name_taken` (409, me `param` të vendosur në `name`). Riemërtimi i pronarit jep `role_immutable` (409), si çdo ndryshim tjetër i tij.
descriptionstring or 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.
permissionsarray- Gjithçka që jep roli, tashmë e zgjeruar dhe në renditje kanonike, jo në renditjen që shkroi dikush. Ajo renditje ka rëndësi thelbësore: dy role me të njëjtat leje mbajnë array-e të barabarta, gjë që i lejon një ekrani cilësimesh t’i krahasojë me `===` për të vendosur nëse butoni Ruaj është i aktivizuar.
builtinstring or null- Nga cili prej gjashtë roleve fillestare erdhi ky rresht, `owner`, `admin`, `member`, `viewer`, `developer` ose `billing`, ose null për një rol që e shkroi vetë hapësira e punës. Regjistron origjinën dhe jo një status: një rol fillestar riemërtohet, merr leje të tjera dhe fshihet si çdo tjetër. Degëzoni sipas `editable` dhe `deletable` dhe jo sipas kësaj. Një rol që dikush e quajti “Admin” nuk është domosdoshmërisht ai fillestari, dhe ai fillestari mund të mos quhet më kështu.
editablebool- Llogaritet si `builtin !== 'owner'`, ndaj është false vetëm për rolin e pronarit, dhe çdo `update` i atij roli refuzohet me `role_immutable` (409). Çdo rol tjetër është plotësisht i ndryshueshëm (emri, përshkrimi dhe lejet), përfshirë të pesë rolet me të cilat krijohet një hapësirë pune.
deletablebool- Llogaritet si `builtin !== 'owner'`: false vetëm për rolin e pronarit, i cili kthehet me `role_undeletable` (409), dhe true për çdo rol tjetër, përfshirë rolet fillestare. Kontrollojeni para se të ofroni butonin, jo pas refuzimit. Një rol që e mban ende dikush kërkon edhe `reassignTo:`, përndryshe fshirja jep `role_in_use` (409). Të dyja refuzimet hidhen si `ConflictException`, dhe `errorCode` i dallon.
membersint- Sa veta e mbajnë këtë rol, të 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ë.
apiKeysint- Sa çelësa API aktivë 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ë te roli, përfshirë edhe ata të revokuarit. Ky është grupi i dytë që duhet zhvendosur para se roli të mund të hiqet, dhe ai që nuk e vë re askush: çelësat janë programe, dhe një program nuk ankohet.
createdAtstring- Kur u shkrua rreshti i rolit, si string ISO 8601. Rreshtat e integruar krijohen me vonesë, herën e parë që diçka ka nevojë për ta, si një lexim i listës së roleve, krijimi i një roli ose ekrani i çelësave API, dhe jo në krijimin e hapësirës së punës. Kështu, 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, si string ISO 8601. Çdo `update` i pranuar e lëviz, përfshirë një që i vendos një fushe vlerën që kishte tashmë.