メンバー
`members.list`、`list_all`、`iterate`、`get`、`add`、`update`、`remove`、`grant_address`、`revoke_address`、そしてその隣の招待のメソッド。
すべてのメソッド
support_role_id = "role_8b1f4c2e9a7d3b60e5f1a2c4"viewer_role_id = "role_2c7e9a1f4b8d3e60c5a7f1b9" invitation = client.members.add( email: "[email protected]", roleId: support_role_id, addressIds: ["2b81de07-9c3f-4a61-b8e2-5d07f4c19a36"], access: "member")puts invitation[:id], invitation[:expiresAt] people = client.members.list_allputs people.map { |person| "#{person[:email]} #{person[:userId]}" } sam_id = "q7Vd3kX9mT2pLw8RzN4bYc6HfJ1sGa5E"member = client.members.get(sam_id)puts member.dig(:role, :name), member[:implied] client.members.update(sam_id, roleId: viewer_role_id) address_id = "c40a95f2-1e7b-4d38-a6c9-82f05b3d7e14"client.members.grant_address(sam_id, addressId: address_id, access: "viewer")client.members.revoke_address(sam_id, address_id) removed = client.members.remove(sam_id)puts removed[:addressesRevoked]1 人につき付与は 2 種類あり、これらを 1 つにまとめてはいけません。role は何ができるか、addresses はどのアドレスに対してできるかを表します。両者が揃って初めて許可されます：emails:send を持つロールでも invoices@ に対する access: "viewer" であれば、その人はメールを送信できますが、そのアドレスから送信することはできません。例外は addresses:all を持つロールで、addresses に何が並んでいてもすべてのアドレスに届きます。その Array には直接の付与しか入らないからです。そのため、addresses をその人が届く範囲のすべてと読む前に permissions を確認してください。
1 人に関する呼び出しはどれも、メールアドレスではなくその人の userId を第 1 引数に取るため、サンプルのように list や list_all から読み取ってください。唯一の例外は add で、アドレスを招待するからです：その人が userId を持つのは招待を受け入れてからで、それまでは list_invitations で招待を追えます。リクエストボディのフィールドは API の camelCase の名前のまま（roleId:、addressIds:、addressId:）、キーワード引数または 1 つの Hash として渡します。
list は OpenEmail::Page を 1 つ返し、list_all はすべてのメンバーを 1 つの Array で返し、iterate は各メンバーをブロックに yield するか、ブロックがなければ Enumerator を返します。メンバーは Symbol キーの Hash として返り、role はその中の Hash なので、member.dig(:role, :name) でロールの名前を読めます。
implied: true は、そのロールを誰も選んでいないことを意味する。アドレスの付与はあるがロールの行がないため、保持している最も広い付与からロールが推定されている。これは「まだ決まっていない」状態として扱うこと。推定を決定に変えるのが update である。それまでは、アドレスへのアクセスを広げると、その人にできることも黙って広がる。
ワークスペースのオーナーは最初の行に現れ、isOwner: true が付きます。一方で add、update、remove はオーナーに対しては member_is_owner で拒否します。これは OpenEmail::ValidationError として送出される 422 です。共有されていないワークスペースでもメンバーは 0 人ではなく 1 人として報告されるため、シート数を数えるときは isOwner を除外してください：client.members.list_all.count { |member| !member[:isOwner] }。
remove は両方の軸、つまりロール「と」このワークスペース上のすべてのアドレス付与を取り除き、addressesRevoked を報告します。範囲が狭いのは revoke_address の方で、退職した人ではなくチームを異動した人に使います。
パラメーター
emailString必須- 招待する相手。トリムして小文字化される。相手はまだアカウントを持っていなくてよい。全員に招待が送られ、ロールと付与は相手が承諾した時点で反映される。すでにワークスペースにいる相手は `member_is_owner`(422)になる。
roleIdString必須- その人が持つことになるロールで、1〜128 文字、このワークスペース上に存在するロールでなければなりません：未知の id は `role_not_found`（404）になり、`OpenEmail::NotFoundError` として送出されます。オーナーのロールは付与できず `role_immutable`（409）が返ります。誰かをオーナーにすることはワークスペースの譲渡であり、そのための呼び出しはここにはないからです。
addressIdsArray<String>- 招待に含めるアドレス。id は最大 64 個、それぞれ 1 〜 128 文字で、招待が承諾された時点で付与される。何かが書き込まれる前にすべての id が検査されるため、このワークスペースのアドレスではない id が 1 つでもあると、呼び出し全体が 422 `member_not_found` で拒否され、何も送信されない。同じアドレスを 10 分以内に再度招待すると 409 `invitation_too_soon` になる。
accessString- `addressIds` に含まれるすべての id に対して何ができるか：`member` はそのアドレスを読み、そのアドレスとして送信できます。`viewer` は読むだけです。既定値は `member` で、これはコンソールおよび以前の共有経路が一貫して使ってきたレベルです。そのため同じ呼び出しは、スクリプトから行っても画面から行っても同じ意味になります。レベルを混在させたい場合は、異なるものについて後から `grant_address` を呼び出してください。
レスポンス
objectString- 常に `member`。削除時も同じ値に加えて対象の `userId`、`deleted: true`、`addressesRevoked` が返り、以下の他のフィールドは返らない。
userIdString- その人のアカウント id で、他のすべてのメンバー呼び出しが第 1 引数に取るハンドルです：`get`、`update`、`remove` とアドレス関連の 2 つの呼び出しがこれにあたります。唯一メールアドレスから動作するのが追加の呼び出しで、同僚を追加する人が知っているのは id ではなくアドレスだからです。
emailString- その人のアカウントに登録されたメールアドレス。行に保存されているとおりに返される。このリソースがこの値を書き込むことはなく、`add` での小文字化は検索のために送ったアドレスに適用されるものであって、返ってくる値には適用されない。メンバー一覧はオーナーの次から、参加時期ではなくこの値で並ぶ。一覧は変更点を見るためではなく、特定の 1 人を探すために読まれるものだからである。
nameString or nil- その人の表示名で、アカウントから取得されます。そちらの列には常に値があります。型に nil が含まれているのは防御的な措置であり、この API がその状態を返したことが確認されているわけではありません。表示名はワークスペースではなく本人に属するため、このリソースから設定する手段はありません。
imageString or nil- その人のアバターで、アカウントから取得されます。設定されていない場合は nil です。
role.idString or nil- その人が持つロールの id で、`member.dig(:role, :id)` として読みます。誰も選んでいない場合は nil です。`implied` を参照してください。ここが nil のときだけ、`role` は誰かが下した決定ではなく推定を報告しています。
role.nameString- ロールの名前。推定されたメンバーの場合、これはそのアクセスが対応する組み込みテンプレートの名前であり、このワークスペース上の行ではありません。
role.builtinString or nil- そのロールがどの組み込みロール（`owner`、`admin`、`member`、`viewer`、`developer`、`billing`）にあたるか。カスタムロールの場合は nil です。`owner` はオーナー自身の行にのみ `isOwner: true` と並んで現れます。このロールを誰かに割り当てようとすると `role_immutable`（409）で拒否されます。
isOwnerBoolean- ちょうど 1 行、ワークスペースの所有者となっているアカウントの行でのみ true になる。その人はロールの行が何を示していてもすべての権限を持ち、並び順では先頭に来る。`add`、`update`、`remove` はいずれも `member_is_owner` で拒否する。シート数を数えるときはこの行を除外すること。
impliedBoolean- その人にアドレスの付与はあるがメンバーの行がなく、ロールが選ばれたのではなく推定された場合に true になります：`member` の付与が 1 つでもあれば組み込みの Member に、なければ Viewer になります。オーナーで true になることはありません。「アクセスから推定」と表示してください。`update` によって推定が決定に変わるまでは、アドレスへのアクセスを広げると、その人にできることも黙って広がります。
permissionsArray<String>- ロールの権限をメンバー上に平坦化したもので、1 回の読み取りで、ロールを取得せずに「この人はできるか」に答えられます。推定されたメンバーの場合、権限はこのワークスペースのロール行ではなく組み込みの「テンプレート」から取られるため、組み込みの Member ロールを編集しても、推定されたメンバーが持つ権限は変わりません。
addressesArray<Hash>- その人に付与されたアドレス。アドレス順に並び、それぞれに固有のアクセスレベルが付く。ロールだけを持ち付与がない人では空になる。アドレスが付与されるまでの新規メンバーはこの状態であり、その人に何を見せるかを決めている間はこれが望ましい失敗の仕方である。
addresses[].addressIdString- アドレスの id で、`grant_address` と `revoke_address` が受け取る値です。このワークスペースのアドレスではない id は、実際には行われなかった取り消しを報告するのではなく、両方で拒否されます。
addresses[].addressString- 完全なアドレス。小文字化され、ローカル部とドメインから再構成される。
addresses[].accessString- この 1 つのアドレスに対して何ができるか：`member` は読み取りとそのアドレスからの送信ができ、`viewer` は読み取りのみです。送信が行われるにはこの値とロールの両方が許可している必要があるため、`viewer` の付与の上に `emails:send` を持つロールがあっても、どこからも送信できません。保存されている列名は `role` ですが、1 つの Hash が異なる語彙に由来する 2 つの `role` キーを持たないよう、ここでは名前を変えています。
createdAtString or nil- メンバーの行が書き込まれた時刻で、ISO 8601 の String です。メンバーの行がまったく存在しない場合は nil です。この nil が示す集団は `implied: true` と同じです：ロールという仕組みができる前からアドレスを持ち、その後も誰もロールを与えていない人たちです。
招待
waiting = client.members.list_all_invitations waiting.each do |invitation| client.members.resend_invitation(invitation[:id]) if invitation[:expired]end client.members.revoke_invitation("winv_6bb640f5b99e47deb758f1f5")add は招待を返し、その後に続く呼び出しがこれらです。list_invitations はまだ誰も承諾していない招待の OpenEmail::Page を 1 つ返し、list_all_invitations はそのすべてを 1 つの Array で返し、iterate_invitations は各招待をブロックに yield するか Enumerator を返します。resend_invitation は新しいリンクとさらに 14 日の期限を付けて再送し、revoke_invitation は招待を取り消します。承諾待ちの招待は、承諾されるまで何も与えません。
resend_invitation は同じアドレスへの 10 分以内の 2 回目を 409 invitation_too_soon で拒否し、revoke_invitation は先に承諾された招待を 409 invitation_accepted で拒否します。どちらも OpenEmail::ConflictError として送出されるため、conflict? が true になり、code で区別できます。