SDK

メンバー

`members.list`、`get`、`add`、`update`、`remove`、`grantAddress`、`revokeAddress`。

すべてのメソッド

members.ts

const people = await openemail.members.list()const member = await openemail.members.get(people[0]!.userId) const sam = await openemail.members.add({  email: '[email protected]',  roleId: support.id,  addressIds: ['2b81de07-…'],  access: 'member',}) await openemail.members.update(sam.userId, { roleId: viewerRoleId }) await openemail.members.grantAddress(sam.userId, {  addressId: 'c40a95f2-…',  access: 'viewer',})await openemail.members.revokeAddress(sam.userId, 'c40a95f2-…') await openemail.members.remove(sam.userId)

1 人につき付与は 2 種類あり、これらを 1 つにまとめてはならない。role は何ができるか、addresses はどのアドレスに対してできるかを表す。両者が揃って初めて許可される。emails:send を持つロールでも invoices@ に対する access: "viewer" であれば、その人はメールを送信できるが、そのアドレスを差出人にして送信することはできない。

どのメソッドもメールアドレスではなく userId を受け取る。唯一の例外が add であり、例外である理由もそこにある。呼び出し側が持っているのはメールアドレスだけでユーザー id はまだ存在せず、それを解決することがこの呼び出しの前半そのものだからである。

implied: true は、そのロールを誰も選んでいないことを意味する。アドレスの付与はあるがロールの行がないため、保持している最も広い付与からロールが推定されている。これは「まだ決まっていない」状態として扱うこと。推定を決定に変えるのが update である。それまでは、アドレスへのアクセスを広げると、その人にできることも黙って広がる。

ワークスペースのオーナーは最初の行に現れ、isOwner: true が付く。一方で add、update、remove はオーナーに対しては member_is_owner で拒否される。共有されていないワークスペースでもメンバーは 0 人ではなく 1 人として報告されるため、シート数を数えるときは isOwner の行を除外すること。

remove は両方の軸、すなわちロールとこのワークスペース上のすべてのアドレス付与を取り除き、addressesRevoked を報告する。範囲が狭いのは revokeAddress の方で、退職した人ではなくチームを異動した人に使う。

パラメーター

emailstring必須: 招待する相手。トリムして小文字化される。相手はまだアカウントを持っていなくてよい。全員に招待が送られ、ロールと付与は相手が承諾した時点で反映される。すでにワークスペースにいる相手は `member_is_owner`(422)になる。
roleIdstring必須: その人が持つことになるロール。1 〜 128 文字で、このワークスペース上に存在するロールでなければならない。未知の id は `role_not_found`(404)になる。オーナーのロールは付与できず `role_immutable`(409)が返る。誰かをオーナーにすることはワークスペースの譲渡であり、そのための呼び出しはここにはないからである。
addressIdsstring[]: 同じ呼び出しで引き渡すアドレス。id は最大 64 個、それぞれ 1 〜 128 文字。このワークスペースのアドレスではない id は拒否される。ロールが先に書き込まれ、付与は 1 件ずつ続くため、不正な id があるとメンバーは作成されたうえで依頼より少ないアドレスしか持たない状態になる。どちらの書き込みも upsert なので、同じボディを再送すれば修正できる。
access'member' | 'viewer': `addressIds` に含まれるすべての id に対して何ができるか。`member` はそのアドレスを読み、そのアドレスとして送信できる。`viewer` は読むだけである。既定値は `member` で、これはコンソールおよび以前の共有経路が一貫して使ってきたレベルである。そのため同じ呼び出しは、スクリプトから行っても画面から行っても同じ意味になる。レベルを混在させたい場合は、異なるものについて後から `grantAddress` を呼ぶこと。

レスポンス

object'member': 常に `member`。削除時も同じ値に加えて対象の `userId`、`deleted: true`、`addressesRevoked` が返り、以下の他のフィールドは返らない。
userIdstring: その人のアカウント id であり、他のすべてのメンバー呼び出しがパスで受け取る識別子である。get、update、remove とアドレス関連の 2 つの呼び出しがこれにあたる。唯一メールアドレスから動作するのが追加の呼び出しで、同僚を追加する人が知っているのは id ではなくアドレスだからである。
emailstring: その人のアカウントに登録されたメールアドレス。行に保存されているとおりに返される。このリソースがこの値を書き込むことはなく、`add` での小文字化は検索のために送ったアドレスに適用されるものであって、返ってくる値には適用されない。メンバー一覧はオーナーの次から、参加時期ではなくこの値で並ぶ。一覧は変更点を見るためではなく、特定の 1 人を探すために読まれるものだからである。
namestring | null: その人の表示名。アカウントから取得され、そちらの列は NOT NULL である。型に null が含まれているのは防御的な措置であり、この API がその状態を返したことが確認されているわけではない。表示名はワークスペースではなく本人に属するため、このリソースから設定する手段はない。
imagestring | null: その人のアバター。アカウントから取得され、設定されていない場合は null。
role.idstring | null: その人が持つロールの id。誰も選んでいない場合は null。`implied` を参照。ここが null のときだけ、`role` は誰かが下した決定ではなく推定を報告している。
role.namestring: ロールの名前。推定されたメンバーの場合、これはそのアクセスが解決した組み込みテンプレートの名前であり、このワークスペース上の行ではない。
role.builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null: そのロールがどの組み込みロールにあたるか。カスタムロールの場合は null。`owner` はオーナー自身の行にのみ `isOwner: true` と並んで現れる。このロールを誰かに割り当てようとすると `role_immutable`(409)で拒否される。
isOwnerboolean: ちょうど 1 行、ワークスペースの所有者となっているアカウントの行でのみ true になる。その人はロールの行が何を示していてもすべての権限を持ち、並び順では先頭に来る。`add`、`update`、`remove` はいずれも `member_is_owner` で拒否する。シート数を数えるときはこの行を除外すること。
impliedboolean: その人にアドレスの付与はあるがメンバーの行がなく、ロールが選ばれたのではなく推定された場合に true になる。`member` の付与が 1 つでもあれば組み込みの Member に、なければ Viewer に解決される。オーナーで true になることはない。UI には「アクセスから推定」と表示すること。PATCH によって推定が決定に変わるまでは、アドレスへのアクセスを広げると、その人にできることも黙って広がる。
permissionsPermission[]: ロールの権限をメンバー上に平坦化したもの。1 回の読み取りで、ロールを取得せずに「この人はできるか」に答えられる。推定されたメンバーの場合、権限はこのワークスペースのロール行ではなく組み込みのテンプレートから取られるため、組み込みの Member ロールを編集しても、推定されたメンバーが持つ権限は変わらない。
addressesMemberAddress[]: その人に付与されたアドレス。アドレス順に並び、それぞれに固有のアクセスレベルが付く。ロールだけを持ち付与がない人では空になる。アドレスが付与されるまでの新規メンバーはこの状態であり、その人に何を見せるかを決めている間はこれが望ましい失敗の仕方である。
addresses[].addressIdstring: アドレスの id であり、`grantAddress` と `revokeAddress` が受け取る値。このワークスペースのアドレスではない id は両方で拒否される。実際には行われなかった取り消しを報告することはない。
addresses[].addressstring: 完全なアドレス。小文字化され、ローカル部とドメインから再構成される。
addresses[].access'member' | 'viewer': この 1 つのアドレスに対して何ができるか。`member` は読み取りとそのアドレスからの送信ができ、`viewer` は読み取りのみである。送信が行われるにはこの値とロールの両方が許可している必要があるため、`viewer` の付与の上に `emails:send` を持つロールがあっても、送信できるアドレスは 1 つもない。保存されている列名は `role` だが、1 つのオブジェクトが異なる語彙に由来する 2 つの `role` を持たないよう、ここでは名前を変えている。
createdAtstring | null: メンバーの行が書き込まれた日時。ISO 8601 で表され、メンバーの行がまったく存在しない場合は null。この null が示す集団は `implied: true` と同じであり、ロールという仕組みができる前からアドレスを持ち、その後も誰もロールを与えていない人たちである。