भूमिकाएँ
`roles.list`, `list_all`, `iterate`, `get`, `create`, `update`, `delete` और `list_permissions`।
हर मेथड
from openemail import openemail roles = openemail.roles.list()role = openemail.roles.get('role_…') support = openemail.roles.create({ 'name': 'Support', 'description': 'Answers the shared inboxes and nothing else.', 'permissions': ['emails:send', 'threads:write', 'labels:write'],}) print(support['permissions']) openemail.roles.update(support['id'], { 'permissions': [*support['permissions'], 'templates:read'],}) openemail.roles.delete(support['id'], reassign_to='role_…') vocabulary = openemail.roles.list_permissions()support['permissions'] में तीन नहीं, छह प्रविष्टियाँ होती हैं: emails:send अपने साथ emails:read लाता है, threads:write अपने साथ threads:read और labels:write अपने साथ labels:read। मान लेने के बजाय सूची वापस पढ़ें।
role बताती है कि कोई क्या कर सकता है। किन पतों पर कर सकता है, यह दूसरा अक्ष है और वह openemail.members पर रहता है। वहाँ grant_address और revoke_address देखें। “मेल भेज सकता है” और “invoices@ से भेज सकता है” अलग वाक्य हैं, और जो वर्कस्पेस दूसरा support एजेंट रखता है वह पहले को छुए बिना दूसरा बदलता है। एक अनुमति दोनों का जवाब देती है: addresses:all रखने वाली role बिना grant के हर पते तक पहुँचती है, बाद में जोड़े गए पतों समेत, और इसे किसी role पर सिर्फ़ ऐप में कोई व्यक्ति ही रख सकता है।
builtin के नाम पर नहीं, editable और deletable पर शाखा बनाएँ। ये दोनों केवल मालिक के लिए false हैं, जिसकी सूची “हर अनुमति, उन सहित जो अगले साल गढ़ी जाएँगी” है और जो संग्रहीत नहीं बल्कि गणना की जाती है; बाकी हर role दोनों पर true कहती है, उन पाँच सहित जिनसे वर्कस्पेस बीजित होता है। जिस role का नाम किसी ने बदल दिया वह भी दोनों सही बताती है, और उसका नाम अब आपको कुछ नहीं बताता।
update अनुमति सूची को पूरी तरह बदल देता है। एक-एक अनुमति देने वाला कोई कॉल नहीं है, इसलिए role पढ़ें, जो प्रविष्टि बदलनी थी उसे बदलें और सभी वापस भेजें। एक ही अनुमति भेजने पर role के पास ठीक वही एक रह जाती है, साथ में वह जो उससे निहित होती है।
जैसे ही कोई role धारण करता है, delete को reassign_to चाहिए, और वह query parameter के रूप में जाता है क्योंकि DELETE पर body कई रनटाइम और कई proxy गिरा देते हैं। परिणाम reassigned और keysReassigned अलग-अलग बताता है, ताकि स्क्रिप्ट यह लॉग कर सके कि उसने क्या किया, न कि उसने क्या माँगा था।
list_permissions() GET /roles/permissions है, एक निश्चित path जो ठीक वहाँ बैठा है जहाँ role id आती, इसलिए get('permissions') उसी endpoint तक पहुँचता है और किसी role के बजाय permissions की सूची के साथ जवाब देता है। 'scope': False उन प्रविष्टियों को चिह्नित करता है जो कोई कुंजी कभी धारण नहीं कर सकती।
role किसी key की छत है
किसी role के विरुद्ध जारी की गई key अपने scope को उस role की अनुमतियों से INTERSECT करके ही कुछ कर सकती है, जो हर request पर सीमा पर हल होता है। इसलिए role को संकरा करना उसकी keys को तुरंत निरस्त कर देता है, बिना किसी को rotate किए, और जिस key के पास कोई role नहीं उस पर कोई छत ही नहीं, यानी null role किसी key की सबसे चौड़ी स्थिति है, सबसे संकरी नहीं।
यही वजह है कि roles.delete इस बात पर अड़ता है कि keys को कहीं और ले जाया जाए। उन्हें अनाथ छोड़ना उनकी छत पूरी तरह हटा देता, और role जिन क्रेडेंशियल को सीमित कर रही थी उन सबको चुपचाप पदोन्नत कर देता।
GET /keys/self और GET /ping प्रभावी scopes के साथ-साथ roleId और grantedScopes भी बताते हैं, और इसी से “मेरी key के पास emails:send है और मुझे insufficient_scope मिल रहा है” का उत्तर मिलता है: जो कुछ grantedScopes में है और scopes में नहीं, वह role ने ले लिया। openemail.me.get() और openemail.me.ping() दोनों लौटाते हैं, typed।
पैरामीटर
namestrआवश्यक- वर्कस्पेस इस role को क्या कहता है: 1 से 48 वर्ण, संग्रहीत होने से पहले trim। नाम प्रति वर्कस्पेस case-insensitive रूप से अद्वितीय होते हैं, इसलिए दूसरा "Support" पहले के साथ बनने के बजाय `role_name_taken` (409) के साथ अस्वीकार होता है।
descriptionstr- एक वाक्य जो बताता है कि role किसलिए है, trim किया हुआ और अधिकतम 240 वर्ण। trim के बाद खाली बची string null के रूप में संग्रहीत होती है, इसलिए केवल spaces वाला विवरण वापस null आता है, वह नहीं जो आपने भेजा था।
permissionslist[Permission]आवश्यक- role क्या देती है, उस शब्दावली से जिसे `list_permissions()` परोसता है; उसमें न होने वाली string चुपचाप गिराई नहीं जाती बल्कि `permissions` पर 422 बनती है, इसलिए टाइपो एक दोपहर खर्च कराने के बजाय बता दिया जाता है। सूची अंदर आते समय EXPAND की जाती है (`templates:write` अपने साथ `templates:read` संग्रहीत करता है), दोहराव हटाया जाता है और उसे विहित क्रम में रखा जाता है, इसलिए यह मान लेने के बजाय कि जो आपने भेजा वही है, संग्रहीत सूची रिस्पॉन्स से पढ़ें।
प्रतिक्रिया
objectLiteral['role']- हमेशा `role`। delete का tombstone वही मान, role की `id`, `'deleted': True` और दोनों पुनर्नियतन गिनतियाँ लौटाता है, और नीचे के बाकी फ़ील्ड कोई नहीं।
idstr- role की id। यही वह है जिसका नाम किसी सदस्य का `roleId` लेता है, जिसकी ओर किसी API key की छत इशारा करती है, और जिसे यह role हटाते समय `reassign_to` लेता है।
namestr- role के लिए वर्कस्पेस का नाम, trim किया हुआ और case-insensitive रूप से अद्वितीय। मालिक की role को छोड़कर हर role का नाम बदला जा सकता है, बीजित वाली भी (`builtin` बताता है कि पंक्ति कहाँ से आई, यह नहीं कि उसका नाम क्या रहना चाहिए), इसलिए "Admin" को इस वादे की तरह न पढ़ें कि role के पास क्या है। जिस नाम से कोई दूसरी role पहले से जानी जाती है वह `role_name_taken` (409, `param: "name"`) है; मालिक का नाम बदलना `role_immutable` (409) है, उसके हर दूसरे संपादन की तरह।
descriptionstr | None- role का वर्णन करने वाला वाक्य, या null जब कोई नहीं दिया गया। खाली इनपुट create और update दोनों पर null के रूप में संग्रहीत होता है, इसलिए यह कभी खाली string नहीं होता।
permissionslist[Permission]- role जो कुछ देती है, पहले ही expand किया हुआ और विहित क्रम में, न कि उस क्रम में जिसमें किसी ने टाइप किया। वह क्रम अहम है: समान अनुमतियों वाली दो role JSON के रूप में बराबर तुलना होती हैं, और इसी से सेटिंग्स स्क्रीन उनका अंतर निकालकर तय कर पाती है कि Save सक्षम हो या नहीं।
builtinLiteral['owner', 'admin', 'member', 'viewer', 'developer', 'billing'] | None- यह पंक्ति छह बीजित roles में से किससे आई, या null उसके लिए जिसे वर्कस्पेस ने खुद लिखा। यह बीज दर्ज करता है, कोई स्थिति नहीं: बीजित role का नाम बदला जाता है, अनुमतियाँ बदली जाती हैं और वह किसी और की तरह हटाई भी जाती है। इस पर नहीं, `editable` और `deletable` पर शाखा बनाएँ। जिस role को किसी ने "Admin" कहा वह ज़रूरी नहीं कि बीजित वाली हो, और बीजित वाली शायद अब उस नाम से न बुलाई जाती हो।
editablebool- `builtin != 'owner'` के रूप में गणना की जाती है, इसलिए यह केवल owner role के लिए false है और उस role का हर PATCH `role_immutable` (409) के साथ अस्वीकार होता है। बाकी हर role पूरी तरह संपादनीय है (नाम, विवरण और अनुमतियाँ), उन पाँच सहित जिनसे वर्कस्पेस बीजित होता है।
deletablebool- `builtin != 'owner'` के रूप में गणना की जाती है: केवल owner role के लिए false, जो `role_undeletable` (409) लौटाती है, और बीजित वाली सहित बाकी हर role के लिए true। बटन दिखाने से पहले इसे जाँचें, इनकार के बाद नहीं, हालाँकि जिस role को कोई अब भी धारण करता है उसके लिए `reassign_to` भी चाहिए, वरना delete `role_in_use` (409) है।
membersint- कितने लोग यह role धारण करते हैं, वर्कस्पेस की member पंक्तियों से गिना गया। मालिक इनमें नहीं है: उसकी कोई member पंक्ति नहीं होती और उसे role दी नहीं जा सकती, इसलिए Owner role शून्य धारक बताती है, भले ही सदस्यों की सूची उसे दिखाती हो।
apiKeysint- कितनी जीवित API keys इस role से सीमित हैं; निरस्त keys गिनती से बाहर हैं, हालाँकि delete role की ओर इशारा करती हर key पंक्ति को फिर से जोड़ देता है, निरस्त वाली भी। यही वह दूसरा समूह है जिसे role के जाने से पहले हटाना होता है, और वही जिस पर किसी का ध्यान नहीं जाता: keys प्रोग्राम हैं, और प्रोग्राम शिकायत नहीं करता।
createdAtstr- role की पंक्ति कब लिखी गई, ISO-8601। अंतर्निहित पंक्तियाँ वर्कस्पेस बनते समय नहीं, बल्कि आलस से तब बीजित होती हैं जब पहली बार किसी को उनकी ज़रूरत पड़ती है (जैसे roles की सूची पढ़ना, role बनाना या API-key स्क्रीन), इसलिए किसी अंतर्निहित role का timestamp वह है जब वह पहला request आया, न कि जब वर्कस्पेस बना।
updatedAtstr- role आखिरी बार कब बदली, ISO-8601। हर स्वीकृत PATCH इसे आगे बढ़ाता है, वह भी जो किसी फ़ील्ड को उसी मान पर सेट करता है जो उसमें पहले से था।
सत्यापन कोड
update और delete कुछ भी बदलने से पहले OAuth एक्सेस टोकन से सत्यापन कोड माँगते हैं, और create नहीं माँगता। कॉल एक OpenEmailApiError raise करती है जिसका is_step_up_required True होता है: security.begin_step_up() से कोड माँगें, व्यक्ति से मिला कोड security.verify_step_up({'code': ...}) से जाँचें, फिर कॉल दोबारा करें। एक सत्यापन 60 मिनट तक मान्य रहता है, और API कुंजी से कभी नहीं पूछा जाता।