Mitglieder
`members->list`, `listAll`, `iterate`, `get`, `add`, `update`, `remove`, `grantAddress`, `revokeAddress`, `grantDomain`, `revokeDomain` und die Einladungsmethoden daneben.
Jede Methode
$supportRoleId = 'role_8b1f4c2e9a7d3b60e5f1a2c4';$viewerRoleId = 'role_2c7e9a1f4b8d3e60c5a7f1b9'; $invitation = $client->members->add([ 'email' => '[email protected]', 'roleId' => $supportRoleId, 'addressIds' => ['2b81de07-9c3f-4a61-b8e2-5d07f4c19a36'], 'access' => 'member',]);echo $invitation['id'], ' ', $invitation['expiresAt'], PHP_EOL; foreach ($client->members->listAll() as $person) { echo $person['email'], ' ', $person['userId'], PHP_EOL;} $samId = 'q7Vd3kX9mT2pLw8RzN4bYc6HfJ1sGa5E';$member = $client->members->get($samId);echo $member['role']['name'], $member['implied'] ? ' (implied)' : '', PHP_EOL; $client->members->update($samId, ['roleId' => $viewerRoleId]); $addressId = 'c40a95f2-1e7b-4d38-a6c9-82f05b3d7e14';$client->members->grantAddress($samId, ['addressId' => $addressId, 'access' => 'viewer']);$client->members->revokeAddress($samId, $addressId); $removed = $client->members->remove($samId);echo $removed['addressesRevoked'], PHP_EOL;Zwei Berechtigungen pro Person, und sie dürfen nicht zusammengeworfen werden. role ist, was jemand tun darf. addresses und domains sind, woran er es tun darf. Beide müssen übereinstimmen: Eine Rolle mit emails:send und access gleich viewer auf invoices@ beschreibt jemanden, der Mail senden darf und sie nicht von dieser Adresse senden darf. Die Ausnahme ist eine Rolle mit addresses:all, die jede Adresse erreicht, egal was addresses auflistet, denn dieses Array enthält nur direkte Freigaben. Prüfen Sie daher permissions, bevor Sie addresses als die gesamte Reichweite einer Person lesen.
Jeder Aufruf zu einer Person nimmt deren userId als erstes Argument, nicht ihre E-Mail. Lesen Sie sie daher aus list oder listAll ab, wie es das Beispiel tut. add ist die einzige Ausnahme, weil es eine Adresse einlädt: Die Person hat erst eine userId, wenn sie annimmt, und listInvitations verfolgt die Einladung bis dahin. Der Body von add, update, grantAddress und grantDomain ist ein einzelnes Array unter den camelCase-Namen der API (roleId, addressIds, addressId).
list gibt eine OpenEmail\Result\Page zurück, listAll gibt alle Mitglieder in einem einzigen Array zurück, und iterate gibt einen Generator zurück, der ein Mitglied nach dem anderen liefert. Ein Mitglied kommt als Array mit camelCase-Schlüsseln zurück, und role ist ein Array darin, $member['role']['name'] liest also den Namen der Rolle.
implied gleich true bedeutet, dass niemand die Rolle gewählt hat. Die Person hat Adressen oder Domains und keine Rollenzeile, die Rolle wurde also aus ihrer weitesten Berechtigung abgeleitet. Behandeln Sie das als „noch nicht entschieden“. Erst update macht aus der Ableitung eine Entscheidung. Bis dahin erweitert jede Ausweitung ihres Adresszugriffs stillschweigend auch das, was sie tun darf.
Der Workspace-Eigentümer ist die erste Zeile, mit isOwner gleich true, während add, update und remove ihn weiterhin mit member_is_owner ablehnen, einem 422, geworfen als ValidationException. Ein nicht geteilter Workspace meldet ein Mitglied statt keines. Schließen Sie isOwner daher aus, wenn Sie Plätze zählen: count(array_filter($client->members->listAll(), fn(array $member): bool => !$member['isOwner'])).
remove nimmt beide Achsen, die Rolle UND jede Adress- und Domainfreigabe in diesem Workspace, und meldet in addressesRevoked, wie viele Freigaben es entzogen hat, Domains eingeschlossen. revokeAddress ist die enge Variante, für jemanden, der das Team gewechselt hat, statt für jemanden, der gegangen ist, und revokeDomain tut dasselbe für eine ganze Domain.
add, update, remove und die vier Aufrufe zum Vergeben und Entziehen verlangen von einem OAuth-Zugriffstoken einen Bestätigungscode, von einem API-Schlüssel nie. Solange das Token keinen hat, werfen sie eine PermissionException, deren isStepUpRequired() true ist. add und grantDomain brauchen außerdem einen Tarif mit Teamzugang, und bei einem Tarif ohne Teamzugang werfen sie eine PermissionException mit errorCode gleich plan_required.
Parameter
emailstringerforderlich- Wen Sie einladen, getrimmt und in Kleinbuchstaben. Ein Konto muss noch nicht bestehen: Eingeladen wird jeder, und Rolle wie Berechtigungen greifen, sobald die Einladung angenommen wird. Jemand, der bereits im Workspace ist, ergibt `member_is_owner` (422). Eine Adresse, die sich mit einem eigenen Passwort anmeldet, kann nicht eingeladen werden und kommt als `mailbox_login` (403) zurück. Laden Sie stattdessen die eigene E-Mail-Adresse der Person ein.
roleIdstringerforderlich- Die Rolle, die die Person erhält, 1 bis 128 Zeichen, und sie muss eine Rolle dieses Workspace sein: Eine unbekannte id ergibt `role_not_found` (404), geworfen als `NotFoundException`. Die Eigentümerrolle lässt sich nicht vergeben und kommt als `role_immutable` (409) zurück, denn jemanden zum Eigentümer zu machen ist eine Workspace-Übertragung, und dafür gibt es hier keinen Aufruf.
addressIdsarray- Adressen, die die Einladung mitführt, höchstens 64 IDs mit je 1 bis 128 Zeichen, vergeben, wenn sie angenommen wird. Jede ID wird geprüft, bevor irgendetwas geschrieben wird, eine ID, die keine Adresse dieses Workspace ist, führt also dazu, dass der ganze Aufruf mit 422 `member_not_found` abgelehnt wird, und nichts wird gesendet. Dieselbe Adresse innerhalb von zehn Minuten erneut einzuladen ergibt 409 `invitation_too_soon`.
domainIdsarray- Ganze Domains, die die Einladung mitführt, höchstens 64 IDs, vergeben, wenn sie angenommen wird. Eine Domain-Freigabe erreicht jede Adresse auf dieser Domain, auch später angelegte. Eine ID, die keine Domain dieses Workspace ist, ergibt 422 `member_not_found`, wie bei einer Adresse.
accessstring- Was die Person mit jeder id in `addressIds` und `domainIds` tun darf: `member` liest die Adresse und sendet als sie, `viewer` liest sie nur. Standard ist `member`, die Stufe, die die Konsole und der ältere Freigabepfad seit jeher verwenden, sodass derselbe Aufruf aus einem Skript dasselbe bedeutet wie von einem Bildschirm. Eine gemischte Vergabe erreichen Sie, indem Sie anschließend `grantAddress` für die abweichenden Adressen aufrufen.
Antwort
objectstring- Immer `member`. Eine Entfernung antwortet mit demselben Wert, der `userId` der Person, `deleted` gleich true und `addressesRevoked`, und mit keinem der übrigen Felder weiter unten.
userIdstring- Die Konto-id der Person und der Bezeichner, den jeder andere Mitglieder-Aufruf als erstes Argument nimmt: `get`, `update`, `remove` und die vier Aufrufe zum Vergeben und Entziehen. Jemanden hinzuzufügen ist der einzige Aufruf, der stattdessen mit einer E-Mail-Adresse arbeitet, denn wer eine Kollegin oder einen Kollegen hinzufügt, kennt deren Adresse und nicht deren id.
emailstring- Die E-Mail-Adresse des Kontos, so zurückgegeben, wie diese Zeile sie speichert. Diese Ressource schreibt sie nie, und die Umwandlung in Kleinbuchstaben bei `add` betrifft die Adresse, die Sie zur Suche senden, nicht das, was zurückkommt. Nach dem Eigentümer ist die Mitgliederliste danach sortiert und nicht nach dem Beitrittszeitpunkt, denn die Liste wird gelesen, um eine bestimmte Person zu finden, nicht um zu sehen, was sich geändert hat.
namestring or null- Der Anzeigename der Person, aus ihrem Konto übernommen, wo die Spalte immer einen Wert enthält. Das null im Typ ist defensiv und kein Zustand, den diese API nachweislich erzeugt. Der Name gehört der Person und nicht dem Workspace, nichts an dieser Ressource kann ihn also setzen.
imagestring or null- Der Avatar der Person, aus ihrem Konto übernommen, und null, wenn sie keinen gesetzt hat.
role.idstring or null- Die id der Rolle, die die Person hat, gelesen als `$member['role']['id']`, oder null, wenn sie niemand gewählt hat. Siehe `implied`. Ein null an dieser Stelle ist der eine Fall, in dem `role` eine Ableitung meldet und nicht eine Entscheidung, die jemand getroffen hat.
role.namestring- Der Name der Rolle. Bei einem abgeleiteten Mitglied ist es der Name der eingebauten Vorlage, der sein Zugriff entspricht, und keine Zeile in diesem Workspace.
role.builtinstring or null- Welche eingebaute Rolle es ist, `owner`, `admin`, `member`, `viewer`, `developer` oder `billing`, oder null bei einer eigenen Rolle. `owner` erscheint nur in der Zeile des Eigentümers selbst, zusammen mit `isOwner` gleich true. Diese Rolle jemandem zuzuweisen wird mit `role_immutable` (409) abgelehnt.
isOwnerbool- true in genau einer Zeile, dem Konto, auf das der Workspace geschlüsselt ist. Dieses Konto hat jede Berechtigung, ganz gleich was seine Rollenzeile sagt, es wird zuerst einsortiert, und `add`, `update` und `remove` lehnen es alle mit `member_is_owner` ab. Schließen Sie es aus, wenn Sie Plätze zählen.
impliedbool- True, wenn diese Person Adress- oder Domain-Freigaben und keine Mitgliedszeile hat, ihre Rolle also abgeleitet und nicht gewählt wurde: Jede Freigabe mit `member` macht daraus die eingebaute Rolle Member, sonst Viewer. Beim Eigentümer nie true. Zeigen Sie es als „durch Zugriff abgeleitet“ an. Bis ein `update` aus der Ableitung eine Entscheidung macht, erweitert jede Ausweitung ihres Adresszugriffs stillschweigend auch das, was sie tun darf.
permissionsarray- Die Berechtigungen der Rolle, flach auf das Mitglied gelegt, sodass ein einziger Lesevorgang die Frage „darf die Person das?“ beantwortet, ohne die Rolle zu laden. Bei einem abgeleiteten Mitglied stammen sie aus der eingebauten VORLAGE und nicht aus der Rollenzeile dieses Workspace. Das Bearbeiten der eingebauten Rolle Member ändert also nicht, was ein abgeleitetes Mitglied hat.
addressesarray- Die Adressen, die der Person zugeteilt wurden, nach Adresse sortiert, ein Array pro Adresse mit ihrer eigenen Zugriffsstufe. Leer bei jemandem, der eine Rolle und keine Berechtigungen hat, genau so sieht ein neues Mitglied aus, bis ihm eine Adresse zugeteilt wird, und das ist der richtige Fehlerfall, solange Sie noch entscheiden, was die Person sehen soll.
addresses[].addressIdstring- Die ID der Adresse, und das, was `grantAddress` und `revokeAddress` erwarten. Eine ID, die keine Adresse dieses Workspace ist, wird bei beiden abgelehnt, statt einen Entzug zu melden, der nie stattgefunden hat.
addresses[].addressstring- Die vollständige Adresse, in Kleinbuchstaben, zusammengesetzt aus ihrem lokalen Teil und ihrer Domain.
addresses[].accessstring- Was die Person mit genau dieser einen Adresse tun darf: `member` liest sie und sendet als sie, `viewer` liest sie nur. Dieser Wert und die Rolle müssen einen Versand beide erlauben, bevor er zustande kommt, eine Rolle mit `emails:send` über einer `viewer`-Freigabe sendet also von nichts. Die gespeicherte Spalte heißt `role` und wird hier umbenannt, damit ein Array nicht zwei `role`-Schlüssel aus zwei verschiedenen Vokabularen trägt.
domainsarray- Die ganzen Domains, die der Person zugeteilt wurden, jede mit `domainId`, `domain` und `access`. Eine Domain-Freigabe erreicht jede Adresse darauf, auch später angelegte. Lesen Sie sie daher neben `addresses`, bevor Sie entscheiden, dass jemand eine Adresse nicht erreicht. `grantDomain` und `revokeDomain` nehmen die `domainId`.
createdAtstring or null- Wann die Mitgliedszeile geschrieben wurde, als String nach ISO 8601, und null, wenn es überhaupt keine Mitgliedszeile gibt. Dieses null beschreibt dieselbe Gruppe wie `implied` gleich true: Personen, die Freigaben aus der Zeit vor den Rollen halten und denen seither niemand eine Rolle gegeben hat.
Einladungen
$waiting = $client->members->listAllInvitations(); foreach ($waiting as $invitation) { if ($invitation['expired']) { $client->members->resendInvitation($invitation['id']); }} $client->members->revokeInvitation('winv_6bb640f5b99e47deb758f1f5');add antwortet mit einer Einladung, und dies sind die Aufrufe, die ihr folgen. listInvitations gibt eine OpenEmail\Result\Page mit denen zurück, die noch niemand angenommen hat, listAllInvitations gibt alle in einem einzigen Array zurück, und iterateInvitations gibt einen Generator zurück, der eine nach der anderen liefert. resendInvitation sendet eine erneut mit einem neuen Link und vierzehn weiteren Tagen, und revokeInvitation zieht sie zurück. Eine ausstehende Einladung gewährt nichts, bis sie angenommen wird.
Eine Einladung ist ein Array mit id, email, role, addresses, domains, expiresAt, expired, lastSentAt und createdAt. delivered und deliveryError melden, wie es der letzten Einladungs-E-Mail ergangen ist, sodass ein Skript eine Einladung, die nur geschrieben wurde, von einer unterscheiden kann, die jemanden erreicht hat.
resendInvitation lehnt dieselbe Adresse innerhalb von zehn Minuten ein zweites Mal mit 409 invitation_too_soon ab, und revokeInvitation lehnt eine zuerst angenommene mit 409 invitation_accepted ab. Beide werden als ConflictException geworfen, isConflict() ist also true, und errorCode unterscheidet sie.