Roller
`roles->list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` ve `listPermissions`.
Her yöntem
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'] üç değil, altı kayıt tutar: emails:send beraberinde emails:read, threads:write beraberinde threads:read, labels:write ise beraberinde labels:read getirir. Listeyi varsaymak yerine geri okuyun.
list bir OpenEmail\Result\Page döndürür, listAll tüm rolleri tek bir dizi içinde döndürür, iterate ise rolleri birer birer veren bir Generator döndürür. Bir rol camelCase anahtarlı bir dizi olarak döner; bu yüzden $role['permissions'] listeyi okur. create ve update gövdeyi API'deki adlarıyla tek bir dizi olarak alır; delete ise reassignTo: değerini adlandırılmış bir argüman olarak alır.
Bir rol, birinin ne YAPABİLECEĞİNİ söyler. Bunu hangi ADRESLER üzerinde yapabileceği diğer eksendir ve $client->members üzerindedir: Üyeler sayfasındaki members->grantAddress ve members->revokeAddress metotlarına bakın. “Posta gönderebilir” ile “invoices@ adresiyle gönderebilir” farklı cümlelerdir ve ikinci bir destek temsilcisi işe alan bir çalışma alanı birinciye dokunmadan ikinciyi değiştirir. Tek bir izin ikisini birden yanıtlar: addresses:all iznine sahip bir rol, sonradan eklenenler dahil her adrese ayrıca yetki verilmeden ulaşır ve bu izni bir role yalnızca uygulamadaki bir kişi ekleyebilir.
Dallanmayı builtin ya da ada göre değil, editable ve deletable değerlerine göre yapın. İkisi de yalnızca sahip rolünde false'tur; onun listesi “gelecek yıl icat edilecekler dahil her izin” anlamına gelir ve saklanmaz, hesaplanır. Bir çalışma alanının başlangıçta aldığı beş rol dahil diğer her rol ikisine de true yanıtı verir. Birinin yeniden adlandırdığı bir rol ikisine de hâlâ doğru yanıt verir, adı ise artık size hiçbir şey söylemez.
update izin listesinin YERİNİ ALIR. Tek bir izin veren bir çağrı yoktur; bu yüzden rolü okuyun, kastettiğiniz kaydı değiştirin ve yukarıdaki [...$support['permissions'], ApiScopes::TEMPLATES_READ] gibi hepsini geri gönderin. Tek bir izin göndermek, rolü tam olarak o izinle ve onun gerektirdikleriyle bırakır.
Rolü biri üstlendiği anda delete için reassignTo: gerekir. İstemci bunu reassignTo sorgu parametresi olarak gönderir, çünkü DELETE isteğindeki bir gövde birçok çalışma ortamı ve bir dizi proxy tarafından atılır; hiçbir şey geçirmediğinizde parametreyi göndermez. Sonuç reassigned ve keysReassigned değerlerini ayrı ayrı bildirir; böylece bir betik istediğini değil, yaptığını günlüğe kaydedebilir.
listPermissions, tam olarak bir rol kimliğinin geleceği yerde duran sabit bir yol olan GET /roles/permissions çağrısıdır. İstemci bu sözcüğü get üzerinden geçirmek yerine o yolu doğrudan çağırır ve bir OpenEmail\Result\Page değil, düz bir liste döndürür: her izin için id, label, group ve scope içeren bir dizi. scope değeri false olan kayıtlar, hiçbir anahtarın asla sahip olamayacağı kayıtlardır. Bu sözcüğü get metoduna kendiniz geçirmeyin. $client->roles->get('permissions') aynı yolu oluşturur; bu yüzden aynı isteği gönderir ve bir rol ya da 404 yerine izin sözlüğünü liste zarfı içinde geri alır.
Rol, bir anahtarın tavanıdır
Bir role karşı verilmiş bir anahtar, kendi kapsamlarının o rolün izinleriyle KESİŞİMİNİ yapabilir ve bu, sınırda her istek için hesaplanır. Bu yüzden bir rolü daraltmak, anahtarlarının hiçbiri döndürülmeden onların yetkilerini anında geri alır. Rolü olmayan bir anahtarın hiçbir tavanı yoktur; bu da null bir roleId değerini 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, geçerli scopes değerinin yanında roleId ve grantedScopes değerlerini 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. $client->me->get() ve $client->me->ping() ikisini de dizilerinde döndürür; bu yüzden array_diff($key['grantedScopes'], $key['scopes']) rolün aldıklarını listeler. Reddin kendisi, isScopeMissing() değeri true olan bir PermissionException'dır.
Parametreler
namestringzorunlu- Çalışma alanının role verdiği ad: 1 ile 48 karakter arası, saklanmadan önce boşlukları kırpılır. Adlar her çalışma alanında büyük/küçük harf gözetmeksizin benzersizdir; bu yüzden ikinci bir “Support” ilkinin yanında oluşturulmaz, `ConflictException` olarak fırlatılan `role_name_taken` (409) ile reddedilir.
descriptionstring- Rolün ne için olduğunu söyleyen bir cümle; boşlukları kırpılır ve en fazla 240 karakterdir. Kırpıldıktan sonra boş kalan bir dize 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. `create` üzerinde null geçirmek yerine anahtarı belirtmeyin: istemci null'u olduğu gibi gönderir ve `create` onu 422 ile reddeder. `update` üzerinde `'description' => null` açıklamayı temizler.
permissionsarrayzorunlu- Rolün verdiği izinler; `listPermissions` çağrısının sunduğu sözlükten alınır. Sözlükte olmayan bir dize sessizce atılmaz; `param` değeri `permissions` olan bir `ValidationException` olarak fırlatılan, `permissions` üzerinde bir 422 verir. 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` saklar), tekrarlardan arındırılır ve standart sıraya konur; bu yüzden saklanan listeyi, gönderdiğinizle aynı olduğunu varsaymak yerine yanıttan okuyun.
Yanıt
objectstring- Her zaman `role`. Silme kaydı da aynı değerle, rolün `id` değeri, true değerindeki `deleted` ve iki yeniden atama sayısıyla yanıt verir; aşağıdaki diğer alanların hiçbirini içermez.
idstring- Rolün kimliği, `$role['id']` olarak okunur. Bir üyenin `roleId` değerinin belirttiği, bir API anahtarının tavanının işaret ettiği ve başka bir rol silinip sahipleri bu role taşındığında `reassignTo:` değerinin aldığı kimlik budur.
namestring- Çalışma alanının role verdiği ad; boşlukları kırpılmış ve büyük/küçük harf gözetmeksizin benzersiz. Başlangıçta gelenler dahil, sahip rolü dışındaki her rol yeniden adlandırılabilir (`builtin` bir satırın nereden geldiğini söyler, nasıl adlandırılmak zorunda olduğunu değil); bu yüzden “Admin” adlı bir rol, neye sahip olduğu hakkında kesin hiçbir şey söylemez. Başka bir rolün zaten kullandığı bir ad `role_name_taken` (409, `param` değeri `name`) verir. Sahibi yeniden adlandırmak, onun diğer her düzenlemesi gibi `role_immutable` (409) verir.
descriptionstring or 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.
permissionsarray- Rolün verdiği her şey; zaten genişletilmiş ve birinin yazdığı sırada değil, standart sırada. Bu sıralama önemlidir: aynı izinlere sahip iki rol eşit diziler tutar ve bir ayarlar ekranının Kaydet düğmesinin etkin olup olmayacağına karar vermek için onları `===` ile karşılaştırabilmesini sağlayan budur.
builtinstring or null- Bu satırın başlangıçta gelen altı rolden hangisinden geldiği: `owner`, `admin`, `member`, `viewer`, `developer` ya da `billing`; çalışma alanının kendisinin yazdığı bir rol için null. Bir durumu değil, kökeni kaydeder: başlangıçta gelen bir rol de diğerleri gibi yeniden adlandırılır, izinleri değiştirilir ve silinir. Dallanmayı buna göre değil, `editable` ve `deletable` değerlerine göre yapın. Birinin “Admin” adını verdiği bir rolün başlangıçta gelen rol olması gerekmez; başlangıçta gelen rol de artık öyle adlandırılmıyor olabilir.
editablebool- `builtin !== 'owner'` olarak hesaplanır; bu yüzden yalnızca sahip rolünde false'tur ve o rolün her `update` çağrısı `role_immutable` (409) ile reddedilir. Bir çalışma alanının başlangıçta aldığı beş rol dahil diğer her rol tamamen (ad, açıklama ve izinler) düzenlenebilir.
deletablebool- `builtin !== 'owner'` olarak hesaplanır: yalnızca `role_undeletable` (409) ile dönen sahip rolünde false, başlangıçta gelenler dahil diğer her rolde true'dur. Bunu retten sonra değil, düğmeyi sunmadan önce denetleyin. Hâlâ birinin üstlendiği bir rol için ayrıca `reassignTo:` gerekir; aksi hâlde silme `role_in_use` (409) verir. İki ret de `ConflictException` olarak fırlatılır ve onları `errorCode` ayırt eder.
membersint- Bu rolü kaç kişinin üstlendiği; çalışma alanının üye satırlarından sayılır. Sahip bunların arasında değildir: üye satırı yoktur ve ona rol verilemez; bu yüzden üye listesi onu gösterse de Sahip rolü sıfır kişi bildirir.
apiKeysint- Bu rolün sınırladığı etkin API anahtarlarının sayısı. İptal edilmiş anahtarlar sayıma dahil edilmez, ancak bir silme işlemi role işaret eden her anahtar satırını, iptal edilmişler dahil, yeniden yönlendirir. Rol kaldırılmadan önce taşınması gereken ikinci gruptur ve kimsenin fark etmediği gruptur: anahtarlar programdır ve bir program şikâyet etmez.
createdAtstring- Rol satırının yazıldığı an, bir ISO 8601 dizesi olarak. Yerleşik satırlar çalışma alanı oluşturulurken değil, bir şey onlara ilk kez ihtiyaç duyduğunda (örneğin bir rol listesi okuması, bir rol oluşturma ya da API anahtarı ekranı) tembel olarak oluşturulur. Bu yüzden yerleşik bir rolün zaman damgası çalışma alanının oluşturulduğu anı değil, o ilk isteğin geldiği anı gösterir.
updatedAtstring- Rolün en son değiştiği an, bir ISO 8601 dizesi olarak. Bir alanı zaten sahip olduğu değere ayarlayan dahil, kabul edilen her `update` onu ilerletir.