Rollen
`roles->list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` und `listPermissions`.
Jede Methode
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'] enthält sechs Einträge, nicht drei: emails:send bringt emails:read mit, threads:write bringt threads:read mit und labels:write bringt labels:read mit. Lesen Sie die Liste zurück, statt sie anzunehmen.
list gibt eine OpenEmail\Result\Page zurück, listAll gibt alle Rollen in einem einzigen Array zurück, und iterate gibt einen Generator zurück, der eine Rolle nach der anderen liefert. Eine Rolle kommt als Array mit camelCase-Schlüsseln zurück, $role['permissions'] liest also die Liste. create und update nehmen den Body als ein einzelnes Array unter den Namen der API, während delete reassignTo: als benanntes Argument nimmt.
Eine Rolle sagt, was jemand TUN darf. Auf welche ADRESSEN sich das bezieht, ist die andere Achse und liegt auf $client->members: Siehe members->grantAddress und members->revokeAddress auf der Seite Mitglieder. „Darf Mail senden“ und „darf als invoices@ senden“ sind zwei verschiedene Sätze, und ein Workspace, der eine zweite Support-Kraft einstellt, ändert den zweiten, ohne den ersten anzurühren. Eine Berechtigung beantwortet beides: Eine Rolle mit addresses:all erreicht jede Adresse, auch später hinzugefügte, ohne Freigabe, und nur eine Person in der App kann sie einer Rolle geben.
Verzweigen Sie über editable und deletable und nicht über builtin oder den Namen. Beide sind allein für die Owner-Rolle false, deren Liste „jede Berechtigung, einschließlich der erst nächstes Jahr erfundenen“ lautet und die berechnet statt gespeichert wird. Jede andere Rolle antwortet auf beide mit true, einschließlich der fünf, mit denen ein Workspace initial bestückt wird. Eine von jemandem umbenannte Rolle antwortet auf beide weiterhin korrekt, und ihr Name sagt Ihnen nichts mehr.
update ERSETZT die Berechtigungsliste. Es gibt keinen Aufruf, der eine einzelne Berechtigung vergibt. Lesen Sie daher die Rolle, ändern Sie den gemeinten Eintrag und senden Sie alle zurück, wie es [...$support['permissions'], ApiScopes::TEMPLATES_READ] oben tut. Wird eine einzige Berechtigung gesendet, hält die Rolle danach genau diese eine, zuzüglich dessen, was sie impliziert.
delete benötigt reassignTo:, sobald irgendjemand die Rolle innehat. Der Client sendet es als Query-Parameter reassignTo, weil ein Body bei DELETE von mehreren Runtimes und etlichen Proxys verworfen wird, und lässt den Parameter weg, wenn Sie nichts übergeben. Das Ergebnis meldet reassigned und keysReassigned getrennt, sodass ein Skript protokollieren kann, was es getan hat, und nicht, was es angefordert hat.
listPermissions ist GET /roles/permissions, ein fester Pfad genau an der Stelle, an der eine Rollen-id stünde. Der Client ruft diesen Pfad direkt auf, statt das Wort durch get zu reichen, und gibt eine einfache Liste zurück, keine OpenEmail\Result\Page: ein Array pro Berechtigung, mit id, label, group und scope. Ist scope false, markiert das die Einträge, die kein Schlüssel je halten kann. Übergeben Sie das Wort nicht selbst an get. $client->roles->get('permissions') baut denselben Pfad, sendet also dieselbe Anfrage und bekommt das Vokabular in seiner Listenhülle zurück statt einer Rolle oder eines 404.
Eine Rolle ist die Obergrenze für einen Key
Ein gegen eine Rolle ausgestellter Schlüssel darf das, was der SCHNITT aus seinen eigenen Scopes und den Berechtigungen dieser Rolle ergibt, aufgelöst pro Anfrage an der Grenze. Eine Rolle einzuschränken entzieht ihren Schlüsseln also live Rechte, ohne dass einer von ihnen rotiert wird. Ein Schlüssel ohne Rolle hat überhaupt keine Obergrenze, womit eine roleId von null der weiteste Zustand ist, in dem ein Schlüssel sein kann, und nicht der engste.
Das ist auch der Grund, warum roles->delete darauf besteht, dass es ein Ziel gibt, an das die Keys verschoben werden. Sie verwaist zurückzulassen würde ihre Obergrenze vollständig entfernen und damit stillschweigend jedes Credential heraufstufen, das die Rolle gedeckelt hat.
GET /keys/self und GET /ping melden roleId und grantedScopes neben den effektiven scopes. So wird „mein Schlüssel hat emails:send und ich bekomme insufficient_scope“ beantwortet: Alles, was in grantedScopes steht und in scopes fehlt, hat die Rolle genommen. $client->me->get() und $client->me->ping() geben beides in ihrem Array zurück, array_diff($key['grantedScopes'], $key['scopes']) listet also, was die Rolle genommen hat. Die Ablehnung selbst ist eine PermissionException, deren isScopeMissing() true ist.
Parameter
namestringerforderlich- Wie der Workspace die Rolle nennt: 1 bis 48 Zeichen, vor dem Speichern getrimmt. Namen sind pro Workspace ohne Beachtung der Groß- und Kleinschreibung eindeutig, ein zweites „Support“ wird daher mit `role_name_taken` (409) abgelehnt, geworfen als `ConflictException`, statt neben dem ersten angelegt zu werden.
descriptionstring- Ein Satz, der beschreibt, wozu die Rolle da ist, getrimmt und höchstens 240 Zeichen. Ein String, der nach dem Trimmen leer ist, wird als null gespeichert, eine Beschreibung aus Leerzeichen kommt also als null zurück und nicht als das Gesendete. Lassen Sie bei `create` den Schlüssel weg, statt null zu übergeben: Der Client sendet ein null unverändert, und `create` lehnt es mit einem 422 ab. Bei `update` löscht `'description' => null` die Beschreibung.
permissionsarrayerforderlich- Was die Rolle gewährt, entnommen dem Vokabular, das `listPermissions` ausliefert. Ein String, der nicht darin enthalten ist, ergibt einen 422 auf `permissions`, geworfen als `ValidationException` mit `param` gleich `permissions`, und wird nicht stillschweigend verworfen, sodass ein Tippfehler gemeldet wird, statt Sie einen Nachmittag zu kosten. Die Liste wird beim Eingang AUFGEWEITET (`templates:write` speichert `templates:read` daneben), dedupliziert und wieder in die kanonische Reihenfolge gebracht. Lesen Sie die gespeicherte Liste daher aus der Antwort, statt anzunehmen, dass es die gesendete ist.
Antwort
objectstring- Immer `role`. Der Tombstone beim Löschen antwortet mit demselben Wert, der `id` der Rolle, `deleted` gleich true und den beiden Umhängungszählern, und mit keinem der übrigen Felder unten.
idstring- Die id der Rolle, gelesen als `$role['id']`. Sie ist das, was die `roleId` eines Mitglieds benennt, worauf die Obergrenze eines API-Schlüssels zeigt und was `reassignTo:` entgegennimmt, wenn eine andere Rolle gelöscht wird und ihre Inhaber zu dieser wechseln.
namestring- Der Name, den der Workspace der Rolle gibt, getrimmt und ohne Beachtung der Groß- und Kleinschreibung eindeutig. Jede Rolle außer der des Owners kann umbenannt werden, die initial angelegten eingeschlossen (`builtin` sagt, woher eine Zeile stammt, nicht, wie sie heißen muss). Eine Rolle namens „Admin“ sagt daher nichts Sicheres darüber, was sie hält. Ein Name, auf den bereits eine andere Rolle hört, ergibt `role_name_taken` (409, mit `param` gleich `name`). Den Owner umzubenennen ergibt `role_immutable` (409), wie jede andere Bearbeitung dieser Rolle.
descriptionstring or null- Der Satz, der die Rolle beschreibt, oder null, wenn keiner angegeben wurde. Leere Eingaben werden sowohl bei create als auch bei update als null gespeichert; dieses Feld ist daher nie ein leerer String.
permissionsarray- Alles, was die Rolle gewährt, bereits aufgeweitet und in kanonischer Reihenfolge statt in der Reihenfolge, in der es jemand getippt hat. Diese Ordnung ist tragend: Zwei Rollen mit denselben Berechtigungen halten gleiche Arrays, und genau das erlaubt es einem Einstellungsbildschirm, sie mit `===` zu vergleichen und so zu entscheiden, ob „Speichern“ aktiv ist.
builtinstring or null- Aus welcher der sechs initial angelegten Rollen diese Zeile stammt, `owner`, `admin`, `member`, `viewer`, `developer` oder `billing`, oder null bei einer, die der Workspace selbst geschrieben hat. Festgehalten wird die Herkunft, kein Status: Eine initial angelegte Rolle wird wie jede andere umbenannt, neu berechtigt und gelöscht. Verzweigen Sie über `editable` und `deletable` und nicht hierüber. Eine Rolle, die jemand „Admin“ genannt hat, muss nicht die initial angelegte sein, und die initial angelegte heißt vielleicht nicht mehr so.
editablebool- Berechnet als `builtin !== 'owner'`, also allein für die Owner-Rolle false, und jedes `update` dieser Rolle wird mit `role_immutable` (409) abgelehnt. Jede andere Rolle ist vollständig bearbeitbar (Name, Beschreibung und Berechtigungen), einschließlich der fünf, mit denen ein Workspace initial bestückt wird.
deletablebool- Berechnet als `builtin !== 'owner'`: false allein für die Owner-Rolle, die mit `role_undeletable` (409) zurückkommt, und true für jede andere Rolle, die initial angelegten eingeschlossen. Prüfen Sie es, bevor Sie den Button anbieten, und nicht erst nach der Ablehnung. Eine Rolle, die jemand noch innehat, braucht zusätzlich `reassignTo:`, sonst ergibt das Löschen `role_in_use` (409). Beide Ablehnungen werden als `ConflictException` geworfen, und `errorCode` unterscheidet sie.
membersint- Wie viele Personen diese Rolle innehaben, gezählt aus den Mitgliederzeilen des Workspace. Der Owner zählt nicht dazu: Er hat keine Mitgliederzeile und kann keine Rolle erhalten, daher meldet die Owner-Rolle null Inhaber, obwohl die Mitgliederliste ihn anzeigt.
apiKeysint- Wie viele aktive API-Schlüssel durch diese Rolle gedeckelt sind. Widerrufene Schlüssel bleiben in der Zählung unberücksichtigt, obwohl ein Löschen jede Schlüsselzeile umhängt, die auf die Rolle zeigt, die widerrufenen eingeschlossen. Das ist die zweite Population, die verschoben werden muss, bevor die Rolle gehen kann, und die, die niemand bemerkt: Schlüssel sind Programme, und ein Programm beschwert sich nicht.
createdAtstring- Wann die Zeile der Rolle geschrieben wurde, als String nach ISO 8601. Eingebaute Zeilen werden verzögert angelegt, sobald etwas sie erstmals benötigt, etwa das Lesen einer Rollenliste, das Anlegen einer Rolle oder der Bildschirm für API-Schlüssel, und nicht bei der Erstellung des Workspace. Der Zeitstempel einer eingebauten Rolle ist also der Zeitpunkt, an dem diese erste Anfrage eintraf, und nicht der, an dem der Workspace angelegt wurde.
updatedAtstring- Wann sich die Rolle zuletzt geändert hat, als String nach ISO 8601. Jedes akzeptierte `update` bewegt den Wert, auch eines, das ein Feld auf den bereits gehaltenen Wert setzt.