Szerepkörök
`roles.list`, `get`, `create`, `update`, `delete` és `listPermissions`.
Minden metódus
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()A support.permissions hat bejegyzést tartalmaz, nem hármat: az emails:send magával hozza az emails:read-et, a threads:write a threads:read-et, a labels:write pedig a labels:read-et. Olvasd vissza a listát, ne feltételezd.
A szerepkör azt mondja meg, mit TEHET valaki. Hogy mely CÍMEKKEL teheti, az a másik tengely, és az openemail.members alatt él. Ott lásd a grantAddress és a revokeAddress hívást. A „küldhet levelet” és a „küldhet az invoices@ címről” két különböző mondat, és az a munkaterület, amely felvesz egy második ügyfélszolgálatost, a másodikat változtatja meg anélkül, hogy az elsőhöz hozzányúlna.
Az editable és a deletable mezőre ágazz el, ne a builtin nevére. Mindkettő kizárólag a tulajdonosnál hamis, akinek a listája „minden jogosultság, beleértve a jövőre kitalálandókat is”, és számított, nem tárolt; minden más szerepkör mindkettőre igazzal felel, beleértve azt az ötöt is, amelyet a munkaterület alapból megkap. Az átnevezett szerepkör is helyesen felel mindkettőre, a neve viszont már semmit nem árul el.
Az update LECSERÉLI a jogosultságlistát. Egyesével adó hívás nincs, ezért olvasd be a szerepkört, módosítsd azt a bejegyzést, amelyet akartál, és küldd vissza az összeset. Ha egyetlen jogosultságot küldesz, a szerepkör pontosan azt az egyet fogja birtokolni, plusz amit az maga után von.
A delete abban a pillanatban igényli a reassignTo paramétert, amint bárki birtokolja a szerepkört, és ez query paraméterként utazik, mert a DELETE törzsét több futtatókörnyezet és számos proxy eldobja. Az eredmény külön jelenti a reassigned és a keysReassigned értéket, így egy szkript azt naplózhatja, amit tett, nem azt, amit kért.
A listPermissions() a GET /roles/permissions, egy fix útvonal pontosan ott, ahol a szerepkör-azonosító állna. A kliens ezt bedrótozza, nem a get-en keresztül adja át a stringet, így egy valóban „permissions” nevű szerepkör lekérése szerepkört kér, és 404-et kap, ami a beírtakra adott őszinte válasz. A scope: false azokat a bejegyzéseket jelöli, amelyeket kulcs soha nem birtokolhat.
A szerepkör a kulcs felső korlátja
A szerepkörhöz kiadott kulcs a saját hatóköreinek és az adott szerepkör jogosultságainak METSZETÉT teheti meg, kérésenként, a határon feloldva. Egy szerepkör szűkítése tehát élőben vonja vissza a kulcsait, anélkül hogy bármelyiket rotálni kellene, a szerepkör nélküli kulcsnak pedig egyáltalán nincs felső korlátja – így a null szerepkör a legtágabb állapot, amelyben egy kulcs lehet, nem a legszűkebb.
Ezért is ragaszkodik a roles.delete ahhoz, hogy legyen hová átvinni a kulcsokat. Árvává tételük teljesen megszüntetné a felső korlátjukat, és csendben előléptetne minden hitelesítő adatot, amelyet a szerepkör korlátozott.
A GET /keys/self és a GET /ping a tényleges scopes mellett jelenti a roleId és a grantedScopes értéket, és így válaszolható meg az, hogy „a kulcsomon rajta van az emails:send, mégis insufficient_scope hibát kapok”: amit a grantedScopes tartalmaz, de a scopes nem, azt a szerepkör vette el. Az openemail.me.get() és az openemail.me.ping() mindkettőt visszaadja, típusosan.
Paraméterek
namestringkötelező- Ahogy a munkaterület nevezi a szerepkört: 1–48 karakter, tárolás előtt levágva. A nevek munkaterületenként, kis- és nagybetűtől függetlenül egyediek, így egy második „Support” `role_name_taken` (409) hibát kap, nem pedig az első mellé jön létre.
descriptionstring- Egy mondat arról, mire való a szerepkör; levágva, legfeljebb 240 karakter. A levágás után üres string nullként tárolódik, így a csupa szóközből álló leírás nullként jön vissza, nem pedig úgy, ahogy elküldted.
permissionsPermission[]kötelező- Amit a szerepkör megad, abból a szótárból véve, amelyet a `listPermissions()` szolgáltat; az abban nem szereplő string 422-t kap a `permissions` mezőn, nem pedig csendben eldobásra kerül, így egy elgépelés jelentést kap, nem pedig egy délutánodba kerül. A lista befelé menet KIBŐVÜL (a `templates:write` mellé bekerül a `templates:read`), deduplikálódik és kanonikus sorrendbe kerül vissza, ezért a tárolt listát a válaszból olvasd ki, ne feltételezd, hogy az, amit küldtél.
Válasz
object'role'- Mindig `role`. A törlési sírkő ugyanezzel az értékkel válaszol, mellette a szerepkör `id` mezője, a `deleted: true` és a két újrakiosztási darabszám, az alábbi többi mező nélkül.
idstring- A szerepkör azonosítója. Ezt nevezi meg egy tag `roleId` mezője, erre mutat egy API-kulcs felső korlátja, és ezt várja a `reassignTo`, amikor ezt a szerepkört törlik.
namestring- A munkaterület neve a szerepkörre, levágva, kis- és nagybetűtől függetlenül egyedi. A tulajdonosén kívül minden szerepkör átnevezhető, az alapból létrehozottak is (a `builtin` azt mondja meg, honnan jött a sor, nem azt, minek kell maradnia), tehát az „Admin” nevet ne olvasd ígéretként arra, mit tartalmaz a szerepkör. Olyan név, amelyre már egy másik szerepkör hallgat, `role_name_taken` (409, `param: "name"`); a tulajdonos átnevezése `role_immutable` (409), mint minden más szerkesztése.
descriptionstring | null- A szerepkört leíró mondat, vagy null, ha nem adtak meg ilyet. Az üres bemenet mind létrehozáskor, mind frissítéskor nullként tárolódik, így ez soha nem üres string.
permissionsPermission[]- Minden, amit a szerepkör megad, már kibővítve és kanonikus sorrendben, nem abban, ahogy bárki beírta. Ez a sorrend teherhordó: két azonos jogosultságú szerepkör JSON-ként egyenlőnek bizonyul, és ez az, ami lehetővé teszi, hogy egy beállítási képernyő összehasonlítsa őket annak eldöntéséhez, aktív-e a Mentés.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- A hat alapszerepkör közül melyikből származik ez a sor, vagy null, ha a munkaterület maga írta. Az eredetet rögzíti, nem állapotot: az alapból létrehozott szerepkör ugyanúgy átnevezhető, újrajogosítható és törölhető, mint bármelyik másik. Az `editable` és a `deletable` mezőre ágazz el, ne erre. Az „Admin” névre hallgató szerepkör nem feltétlenül az alapból létrehozott, az alapból létrehozottat pedig lehet, hogy már nem így hívják.
editableboolean- A `builtin !== 'owner'` kifejezésből számítva, tehát kizárólag a tulajdonosi szerepkörnél hamis, és annak minden PATCH hívása `role_immutable` (409) hibával elutasításra kerül. Minden más szerepkör teljes egészében szerkeszthető (név, leírás és jogosultságok), beleértve azt az ötöt is, amelyet a munkaterület alapból megkap.
deletableboolean- A `builtin !== 'owner'` kifejezésből számítva: kizárólag a tulajdonosi szerepkörnél hamis, amely `role_undeletable` (409) hibával tér vissza, és minden más szerepkörnél igaz, az alapból létrehozottakat is beleértve. A gomb felkínálása előtt ellenőrizd, ne az elutasítás után, ugyanakkor egy még birtokolt szerepkörhöz `reassignTo` is kell, különben a törlés `role_in_use` (409).
membersnumber- Hányan birtokolják ezt a szerepkört, a munkaterület tagsorai alapján számolva. A tulajdonos nincs közöttük: nincs tagsora, és nem is kaphat szerepkört, így az Owner szerepkör nulla birtokost jelent, noha a taglista mutatja őt.
apiKeysnumber- Hány élő API-kulcsot korlátoz ez a szerepkör; a visszavont kulcsok kimaradnak a számból, noha a törlés minden, a szerepkörre mutató kulcssort átirányít, a visszavontakat is beleértve. Ez a második populáció, amelyet át kell mozgatni, mielőtt a szerepkör mehetne, és az, amelyet senki nem vesz észre: a kulcsok programok, a program pedig nem panaszkodik.
createdAtstring- Mikor íródott a szerepkörsor, ISO-8601. A beépített sorok lustán jönnek létre, amikor először szükség van rájuk – például szerepkörlista-olvasáskor, szerepkör létrehozásakor vagy az API-kulcs képernyőn –, nem a munkaterület létrehozásakor, így egy beépített szerepkör időbélyege azt jelöli, mikor érkezett az az első kérés, nem azt, mikor készült a munkaterület.
updatedAtstring- Mikor változott utoljára a szerepkör, ISO-8601. Minden elfogadott PATCH elmozdítja, az is, amely egy mezőt a már meglévő értékére állít.