メンバー
`members->list`、`listAll`、`iterate`、`get`、`add`、`update`、`remove`、`grantAddress`、`revokeAddress`、`grantDomain`、`revokeDomain`、そしてその隣の招待のメソッド。
すべてのメソッド
$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;1 人につき付与は 2 種類あり、これらを 1 つにまとめてはいけません。role は何ができるか、addresses と domains はどのアドレスやドメインに対してできるかを表します。両者が揃って初めて許可されます。emails:send を持つロールでも invoices@ に対する access が viewer であれば、その人はメールを送信できますが、そのアドレスから送信することはできません。例外は addresses:all を持つロールで、addresses に何が並んでいてもすべてのアドレスに届きます。その配列には直接の付与しか入らないからです。そのため、addresses をその人が届く範囲のすべてと読む前に permissions を確認してください。
1 人に関する呼び出しはどれも、メールアドレスではなくその人の userId を第 1 引数に取るため、サンプルのように list や listAll から読み取ってください。唯一の例外は add で、アドレスを招待するからです。その人が userId を持つのは招待を受け入れてからで、それまでは listInvitations で招待を追えます。add、update、grantAddress、grantDomain のボディは、API の camelCase の名前（roleId、addressIds、addressId）をキーとする 1 つの配列です。
list は OpenEmail\Result\Page を 1 つ返し、listAll はすべてのメンバーを 1 つの配列で返し、iterate はメンバーを 1 人ずつ yield する Generator を返します。メンバーは camelCase のキーを持つ配列として返り、role はその中の配列なので、$member['role']['name'] でロールの名前を読めます。
implied が true のときは、そのロールを誰も選んでいないことを意味します。アドレスやドメインの付与はあるがロールの行がないため、保持している最も広い付与からロールが推定されています。これは「まだ決まっていない」状態として扱ってください。推定を決定に変えるのが update です。それまでは、アドレスへのアクセスを広げると、その人にできることも黙って広がります。
ワークスペースのオーナーは最初の行に現れ、isOwner が true です。一方で add、update、remove はオーナーに対しては member_is_owner で拒否します。これは ValidationException としてスローされる 422 です。共有されていないワークスペースでもメンバーは 0 人ではなく 1 人として報告されるため、シート数を数えるときは isOwner を除外してください。count(array_filter($client->members->listAll(), fn(array $member): bool => !$member['isOwner'])) のようにします。
remove は両方の軸、つまりロール「と」このワークスペース上のすべてのアドレスとドメインの付与を取り除き、取り消した付与の数をドメインの分も含めて addressesRevoked で報告します。範囲が狭いのは revokeAddress の方で、退職した人ではなくチームを異動した人に使います。revokeDomain はドメイン全体について同じことを行います。
add、update、remove と、4 つの付与・取り消しの呼び出しは、OAuth アクセストークンには確認コードを求めますが、API キーには求めません。トークンが確認コードを得るまで、これらは isStepUpRequired() が true の PermissionException をスローします。add と grantDomain にはチームを含むプランも必要で、そうでないプランでは errorCode が plan_required の PermissionException をスローします。
パラメーター
emailstring必須- 招待する相手で、前後の空白が取り除かれ、小文字化されます。相手はまだアカウントを持っていなくてかまいません。全員に招待が送られ、ロールと付与は相手が承諾した時点で反映されます。すでにワークスペースにいる相手は `member_is_owner`（422）になります。独自のパスワードでサインインするアドレスは招待できず、`mailbox_login`（403）が返るため、代わりにその人自身のメールアドレスを招待してください。
roleIdstring必須- その人が持つことになるロールで、1〜128 文字、このワークスペース上に存在するロールでなければなりません。未知の id は `role_not_found`（404）になり、`NotFoundException` としてスローされます。オーナーのロールは付与できず `role_immutable`（409）が返ります。誰かをオーナーにすることはワークスペースの譲渡であり、そのための呼び出しはここにはないからです。
addressIdsarray- 招待に含めるアドレス。id は最大 64 個、それぞれ 1 〜 128 文字で、招待が承諾された時点で付与される。何かが書き込まれる前にすべての id が検査されるため、このワークスペースのアドレスではない id が 1 つでもあると、呼び出し全体が 422 `member_not_found` で拒否され、何も送信されない。同じアドレスを 10 分以内に再度招待すると 409 `invitation_too_soon` になる。
domainIdsarray- 招待に含めるドメイン全体で、最大 64 個の id。招待が承諾されたときに付与されます。ドメインの付与は、後から作られたものも含め、そのドメイン上のすべてのアドレスに及びます。このワークスペースのドメインでない id は、アドレスと同じく 422 `member_not_found` になります。
accessstring- `addressIds` と `domainIds` に含まれるすべての id に対して何ができるか。`member` はそのアドレスを読み、そのアドレスとして送信できます。`viewer` は読むだけです。既定値は `member` で、これはコンソールおよび以前の共有経路が一貫して使ってきたレベルです。そのため同じ呼び出しは、スクリプトから行っても画面から行っても同じ意味になります。レベルを混在させたい場合は、異なるものについて後から `grantAddress` を呼び出してください。
レスポンス
objectstring- 常に `member`。削除時も同じ値に加えて、対象の `userId`、true の `deleted`、`addressesRevoked` が返り、以下の他のフィールドは返りません。
userIdstring- その人のアカウント id で、他のすべてのメンバー呼び出しが第 1 引数に取るハンドルです。`get`、`update`、`remove` と、4 つの付与・取り消しの呼び出しがこれにあたります。唯一メールアドレスから動作するのが追加の呼び出しで、同僚を追加する人が知っているのは id ではなくアドレスだからです。
emailstring- その人のアカウントに登録されたメールアドレス。行に保存されているとおりに返される。このリソースがこの値を書き込むことはなく、`add` での小文字化は検索のために送ったアドレスに適用されるものであって、返ってくる値には適用されない。メンバー一覧はオーナーの次から、参加時期ではなくこの値で並ぶ。一覧は変更点を見るためではなく、特定の 1 人を探すために読まれるものだからである。
namestring or null- その人の表示名で、アカウントから取得されます。そちらの列には常に値があります。型に null が含まれているのは防御的な措置であり、この API がその状態を返したことが確認されているわけではありません。表示名はワークスペースではなく本人に属するため、このリソースから設定する手段はありません。
imagestring or null- その人のアバター。アカウントから取得され、設定されていない場合は null。
role.idstring or null- その人が持つロールの id で、`$member['role']['id']` として読みます。誰も選んでいない場合は null です。`implied` を参照してください。ここが null のときだけ、`role` は誰かが下した決定ではなく推定を報告しています。
role.namestring- ロールの名前。推定されたメンバーの場合、これはそのアクセスが対応する組み込みテンプレートの名前であり、このワークスペース上の行ではありません。
role.builtinstring or null- そのロールがどの組み込みロール（`owner`、`admin`、`member`、`viewer`、`developer`、`billing`）にあたるか。カスタムロールの場合は null です。`owner` はオーナー自身の行にのみ、true の `isOwner` と並んで現れます。このロールを誰かに割り当てようとすると `role_immutable`（409）で拒否されます。
isOwnerbool- ちょうど 1 行、ワークスペースの所有者となっているアカウントの行でのみ true になる。その人はロールの行が何を示していてもすべての権限を持ち、並び順では先頭に来る。`add`、`update`、`remove` はいずれも `member_is_owner` で拒否する。シート数を数えるときはこの行を除外すること。
impliedbool- その人にアドレスやドメインの付与はあるがメンバーの行がなく、ロールが選ばれたのではなく推定された場合に true になります。`member` の付与が 1 つでもあれば組み込みの Member に、なければ Viewer になります。オーナーで true になることはありません。「アクセスから推定」と表示してください。`update` によって推定が決定に変わるまでは、アドレスへのアクセスを広げると、その人にできることも黙って広がります。
permissionsarray- ロールの権限をメンバー上に平坦化したもので、1 回の読み取りで、ロールを取得せずに「この人はできるか」に答えられます。推定されたメンバーの場合、権限はこのワークスペースのロール行ではなく組み込みの「テンプレート」から取られるため、組み込みの Member ロールを編集しても、推定されたメンバーが持つ権限は変わりません。
addressesarray- その人に付与されたアドレスで、アドレス順に並び、それぞれが固有のアクセスレベルを持つ配列です。ロールだけを持ち付与がない人では空になります。アドレスが付与されるまでの新規メンバーはこの状態であり、その人に何を見せるかを決めている間は、これが望ましい失敗の仕方です。
addresses[].addressIdstring- アドレスの id であり、`grantAddress` と `revokeAddress` が受け取る値。このワークスペースのアドレスではない id は両方で拒否される。実際には行われなかった取り消しを報告することはない。
addresses[].addressstring- 完全なアドレス。小文字化され、ローカル部とドメインから再構成される。
addresses[].accessstring- この 1 つのアドレスに対して何ができるか。`member` は読み取りとそのアドレスからの送信ができ、`viewer` は読み取りのみです。送信が行われるにはこの値とロールの両方が許可している必要があるため、`viewer` の付与の上に `emails:send` を持つロールがあっても、どこからも送信できません。保存されている列名は `role` ですが、1 つの配列が異なる語彙に由来する 2 つの `role` キーを持たないよう、ここでは名前を変えています。
domainsarray- その人に付与されたドメイン全体で、それぞれ `domainId`、`domain`、`access` を持ちます。ドメインの付与は、後から作られたものも含めてそのドメイン上のすべてのアドレスに及ぶため、誰かがあるアドレスに届かないと判断する前に、`addresses` と並べて読んでください。`grantDomain` と `revokeDomain` は `domainId` を受け取ります。
createdAtstring or null- メンバーの行が書き込まれた時刻で、ISO 8601 の文字列です。メンバーの行がまったく存在しない場合は null です。この null が示す集団は、`implied` が true の人と同じです。ロールという仕組みができる前から付与を持ち、その後も誰もロールを与えていない人たちです。
招待
$waiting = $client->members->listAllInvitations(); foreach ($waiting as $invitation) { if ($invitation['expired']) { $client->members->resendInvitation($invitation['id']); }} $client->members->revokeInvitation('winv_6bb640f5b99e47deb758f1f5');add は招待を返し、その後に続く呼び出しがこれらです。listInvitations はまだ誰も承諾していない招待の OpenEmail\Result\Page を 1 つ返し、listAllInvitations はそのすべてを 1 つの配列で返し、iterateInvitations は招待を 1 つずつ yield する Generator を返します。resendInvitation は新しいリンクとさらに 14 日の期限を付けて再送し、revokeInvitation は招待を取り消します。承諾待ちの招待は、承諾されるまで何も与えません。
招待は id、email、role、addresses、domains、expiresAt、expired、lastSentAt、createdAt を持つ配列です。delivered と deliveryError は最後の招待メールがどうなったかを報告するため、スクリプトは、書き込まれただけの招待と相手に届いた招待を区別できます。
resendInvitation は同じアドレスへの 10 分以内の 2 回目を 409 invitation_too_soon で拒否し、revokeInvitation は先に承諾された招待を 409 invitation_accepted で拒否します。どちらも ConflictException としてスローされるため、isConflict() が true になり、errorCode で区別できます。