Roller
`roles.list`, `get`, `create`, `update`, `delete` ve `listPermissions`.
Her yöntem
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 üç değil altı girdi tutar: emails:send beraberinde emails:read'i, threads:write threads:read'i ve labels:write labels:read'i getirir. Listeyi varsaymak yerine geri okuyun.
Bir rol, birinin NE YAPABİLECEĞİNİ söyler. Bunu hangi ADRESLER üzerinde yapabileceği ise diğer eksendir ve openemail.members üzerinde yaşar. Oradaki grantAddress ve revokeAddress'e bakın. “Posta gönderebilir” ile “invoices@ adresinden gönderebilir” farklı cümlelerdir ve ikinci bir destek temsilcisi işe alan bir çalışma alanı, birincisine dokunmadan ikincisini değiştirir.
builtin adının değil, editable ve deletable alanlarının üzerinden dallanın. Her ikisi de yalnızca sahip rolü için false'tur; onun listesi “gelecek yıl icat edilecekler dahil her izin”dir ve saklanmak yerine hesaplanır. Diğer her rol ikisine de true yanıtı verir, bir çalışma alanının başlangıçta aldığı beş rol dahil. Birinin yeniden adlandırdığı bir rol de ikisini doğru yanıtlar, ama adı artık size hiçbir şey söylemez.
update, izin listesinin YERİNE GEÇER. Tek bir izin vermeye yarayan bir çağrı yoktur; bu yüzden rolü okuyun, değiştirmek istediğiniz girdiyi değiştirin ve tümünü geri gönderin. Tek bir izin göndermek, rolde yalnızca o izni ve onun ima ettiklerini bırakır.
Rolü tutan biri olduğu anda delete için reassignTo gerekir ve bu, sorgu parametresi olarak taşınır; çünkü DELETE üzerindeki bir gövde birçok çalışma zamanı ve bir dizi proxy tarafından düşürülür. Sonuç, reassigned ve keysReassigned değerlerini ayrı ayrı bildirir; böylece bir betik, istediğini değil yaptığını günlüğe yazabilir.
listPermissions(), tam olarak bir rol id'sinin geleceği yerde duran sabit bir yol olan GET /roles/permissions'tır. İstemci bu dizeyi get üzerinden geçirmek yerine sabit kodlar; bu yüzden gerçekten “permissions” adlı bir rolü istemek bir rol ister ve 404 alır ki bu, yazılana verilebilecek dürüst yanıttır. scope: false, hiçbir anahtarın asla tutamayacağı girdileri işaretler.
Rol, bir anahtarın tavanıdır
Bir role karşı düzenlenen anahtar, kendi kapsamlarının o rolün izinleriyle KESİŞİMİNİ yapabilir; bu, her istekte sınırda çözümlenir. Dolayısıyla bir rolü daraltmak, anahtarlarının hiçbiri döndürülmeden onları canlı olarak geri alır; rolü olmayan bir anahtarın ise hiçbir tavanı yoktur, bu da null bir rolü bir anahtarın bulunabileceği en dar değil en geniş durum yapar.
roles.delete'in anahtarları taşıyacak bir yer konusunda ısrar etmesinin nedeni de budur. Onları öksüz bırakmak tavanlarını tamamen kaldırır ve rolün sınırladığı her kimlik bilgisini sessizce terfi ettirir.
GET /keys/self ve GET /ping, etkin scopes değerinin yanında roleId ve grantedScopes bildirir; “anahtarımda emails:send var ama insufficient_scope alıyorum” sorusu böyle yanıtlanır: grantedScopes içinde olup scopes içinde olmayan her şeyi rol almıştır. openemail.me.get() ve openemail.me.ping() her ikisini de türlenmiş olarak döndürür.
Parametreler
namestringzorunlu- Çalışma alanının role verdiği ad: 1 ila 48 karakter, saklanmadan önce kırpılır. Adlar, büyük/küçük harf ayrımı gözetilmeksizin çalışma alanı başına benzersizdir; bu yüzden ikinci bir “Support”, ilkinin yanına oluşturulmak yerine `role_name_taken` (409) ile reddedilir.
descriptionstring- Rolün ne işe yaradığını söyleyen bir cümle; kırpılır ve en fazla 240 karakterdir. Kırpıldığında boş kalan bir string null olarak saklanır; bu yüzden boşluklardan oluşan bir açıklama, gönderdiğiniz hâliyle değil null olarak geri gelir.
permissionsPermission[]zorunlu- Rolün verdiği yetkiler; `listPermissions()`'ın sunduğu sözlükten alınır. Bu sözlükte olmayan bir string sessizce düşürülmez, `permissions` üzerinde 422 olur; böylece bir yazım hatası size bir öğleden sonraya mal olmak yerine bildirilir. Liste girişte GENİŞLETİLİR (`templates:write`, yanında `templates:read`'i de saklar), yinelenenlerden arındırılır ve kanonik sıraya konur; bu yüzden saklanan listenin gönderdiğiniz liste olduğunu varsaymak yerine onu yanıttan okuyun.
Yanıt
object'role'- Her zaman `role`. Silme mezar taşı aynı değerle birlikte rolün `id` değerini, `deleted: true` alanını ve iki yeniden atama sayısını yanıtlar; aşağıdaki diğer alanların hiçbirini değil.
idstring- Rolün id'si. Bir üyenin `roleId` alanının adlandırdığı, bir API anahtarının tavanının işaret ettiği ve bu rol silindiğinde `reassignTo`'nun aldığı değerdir.
namestring- Çalışma alanının role verdiği ad; kırpılmış ve büyük/küçük harf ayrımı gözetilmeksizin benzersiz. Sahip rolü dışındaki her rol yeniden adlandırılabilir, tohumlanmış olanlar dahil (`builtin`, bir satırın nereden geldiğini söyler, adının ne kalması gerektiğini değil); bu yüzden “Admin” adını, rolün neleri tuttuğuna dair bir söz olarak okumayın. Başka bir rolün hâlihazırda yanıt verdiği bir ad `role_name_taken`'dır (409, `param: "name"`); sahip rolünü yeniden adlandırmak ise, üzerindeki diğer her düzenleme gibi, `role_immutable`'dır (409).
descriptionstring | null- Rolü betimleyen cümle ya da hiçbiri verilmediğinde null. Boş girdi hem oluşturmada hem güncellemede null olarak saklanır; bu yüzden burası asla boş bir string olmaz.
permissionsPermission[]- Rolün verdiği her yetki; birinin yazdığı sırada değil, hâlihazırda genişletilmiş ve kanonik sırada. Bu sıralama taşıyıcıdır: aynı izinleri tutan iki rol JSON olarak eşit karşılaştırılır ve bir ayarlar ekranının, Kaydet düğmesinin etkin olup olmayacağına karar vermek için onları karşılaştırabilmesini sağlayan da budur.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- Bu satırın tohumlanmış altı rolden hangisinden geldiği ya da çalışma alanının kendi yazdığı bir rol için null. Bir durumu değil, tohumu kaydeder: tohumlanmış bir rol de diğerleri gibi yeniden adlandırılır, izinleri değiştirilir ve silinir. Buna göre değil, `editable` ve `deletable` üzerinden dallanın. Birinin “Admin” adını verdiği bir rolün tohumlanmış olan olması gerekmez ve tohumlanmış olanın adı artık bu olmayabilir.
editableboolean- `builtin !== 'owner'` olarak hesaplanır; bu yüzden yalnızca sahip rolü için false'tur ve o rolün her PATCH'i `role_immutable` (409) ile reddedilir. Diğer her rol tümüyle düzenlenebilir (ad, açıklama ve izinler), bir çalışma alanının başlangıçta aldığı beş rol dahil.
deletableboolean- `builtin !== 'owner'` olarak hesaplanır: yalnızca sahip rolü için false'tur ve o rol `role_undeletable` (409) ile geri döner; tohumlanmış olanlar dahil diğer her rol için true'dur. Düğmeyi sunmadan önce, ret yanıtından sonra değil, bunu denetleyin; yine de birinin hâlâ tuttuğu bir rol için `reassignTo` da gerekir, aksi hâlde silme `role_in_use` (409) olur.
membersnumber- Bu rolü kaç kişinin tuttuğu; çalışma alanının üye satırlarından sayılır. Sahip bunların arasında değildir: üye satırı yoktur ve kendisine rol verilemez, bu yüzden üye listesi onu gösteriyor olsa da Owner rolü sıfır kişi bildirir.
apiKeysnumber- Bu rolün tavanladığı canlı API anahtarı sayısı; iptal edilmiş anahtarlar sayıma katılmaz, ancak bir silme işlemi role işaret eden her anahtar satırını, iptal edilmiş olanlar dahil, yeniden yönlendirir. Rol gidebilmeden önce taşınması gereken ikinci nüfus budur ve kimsenin fark etmediği de budur: anahtarlar programdır ve bir program şikâyet etmez.
createdAtstring- Rol satırının yazıldığı an, ISO-8601. Yerleşik satırlar, çalışma alanı oluşturulurken değil, bir rol listesi okuması, bir rol oluşturma ya da API anahtarı ekranı gibi bir şey onlara ilk kez ihtiyaç duyduğunda tembel biçimde tohumlanır; bu yüzden bir yerleşik rolün zaman damgası, çalışma alanının oluşturulduğu an değil, o ilk isteğin geldiği andır.
updatedAtstring- Rolün en son değiştiği an, ISO-8601. Kabul edilen her PATCH bunu ilerletir; bir alanı zaten tuttuğu değere ayarlayan PATCH dahil.