اعضا
`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]برای هر فرد دو اعطا وجود دارد، و نباید در هم ادغام شوند. role می‌گوید چه کاری مجاز است. addresses می‌گوید روی چه چیزی. هر دو باید هم‌داستان باشند: نقشی با emails:send همراه با access: "viewer" روی invoices@ یعنی کسی که می‌تواند ایمیل بفرستد اما نمی‌تواند از آن نشانی بفرستد. استثنا نقشی است که addresses:all دارد، که فارغ از آنچه addresses فهرست می‌کند به همهٔ نشانی‌ها می‌رسد، چون آن Array فقط اعطاهای مستقیم را نگه می‌دارد. پس پیش از آنکه addresses را کل دامنهٔ دسترسی کسی بدانید، permissions را بررسی کنید.
هر فراخوانی دربارهٔ یک فرد، userId او را به‌عنوان آرگومان نخست می‌گیرد، نه ایمیلش را، پس آن را از list یا list_all بخوانید، همان‌طور که نمونه انجام می‌دهد. add تنها استثناست، چون یک نشانی را دعوت می‌کند: آن فرد تنها پس از پذیرفتن دعوت userId دارد، و list_invitations تا آن زمان دعوت‌نامه را دنبال می‌کند. فیلدهای بدنهٔ درخواست نام‌های camelCase در API را نگه می‌دارند (roleId:، addressIds:، addressId:) و به‌صورت کلیدواژه یا یک Hash داده می‌شوند.
list یک OpenEmail::Page برمی‌گرداند، list_all همهٔ اعضا را در یک Array برمی‌گرداند، و iterate هر عضو را به یک بلاک yield می‌کند یا بدون بلاک یک Enumerator برمی‌گرداند. عضو به‌صورت یک Hash با کلیدهای Symbol برمی‌گردد، و role یک Hash درون آن است، پس member.dig(:role, :name) نام نقش را می‌خواند.
implied: true یعنی هیچ‌کس نقش را انتخاب نکرده است. آن فرد آدرس دارد و ردیف نقش ندارد، پس نقش از گسترده‌ترین اعطایی که دارد استنتاج شده است. آن را «هنوز تصمیم‌گیری نشده» بدانید، و update همان چیزی است که استنتاج را به تصمیم تبدیل می‌کند. تا آن زمان، گسترده‌تر کردن دسترسی آدرسی او بی‌صدا کارهایی را که مجاز است گسترده‌تر می‌کند.
مالک فضای کاری نخستین ردیف است و با isOwner: true مشخص می‌شود، در حالی که add، update و remove همچنان او را با member_is_owner رد می‌کنند، یک 422 که به‌صورت OpenEmail::ValidationError raise می‌شود. فضای کاری‌ای که با کسی به اشتراک گذاشته نشده یک عضو گزارش می‌کند نه صفر، پس وقتی صندلی‌ها را می‌شمارید isOwner را کنار بگذارید: client.members.list_all.count { |member| !member[:isOwner] }.
remove هر دو محور را برمی‌دارد، یعنی نقش «و» همهٔ اعطاهای نشانی روی این فضای کاری، و addressesRevoked را گزارش می‌کند. revoke_address مورد محدودتر است، برای کسی که تیمش عوض شده نه کسی که رفته است.
پارامترها
emailStringالزامی- چه کسی دعوت شود، trimشده و با حروف کوچک. هنوز لازم نیست حساب داشته باشد: همه دعوت می‌شوند و نقش و اعطاها هنگام پذیرش اعمال می‌شوند. کسی که از پیش در فضای کاری است `member_is_owner` (422) می‌گیرد.
roleIdStringالزامی- نقشی که خواهد داشت، 1 تا 128 نویسه، و باید نقشی روی همین فضای کاری باشد: شناسهٔ ناشناخته `role_not_found` (404) است که به‌صورت `OpenEmail::NotFoundError` raise می‌شود. نقش مالک قابل اعطا نیست و با `role_immutable` (409) برمی‌گردد، چون مالک کردن کسی یعنی انتقال فضای کاری، و برای آن اینجا فراخوانی‌ای وجود ندارد.
addressIdsArray<String>- آدرس‌هایی که دعوت‌نامه با خود دارد، حداکثر 64 شناسه که هرکدام 1 تا 128 نویسه است، و هنگام پذیرفته شدن دعوت اعطا می‌شوند. هر شناسه پیش از نوشته شدن هر چیزی بررسی می‌شود، پس شناسه‌ای که آدرسی روی این فضای کاری نباشد کل فراخوانی را با 422 `member_not_found` رد می‌کند و چیزی فرستاده نمی‌شود. دعوت دوبارهٔ همان آدرس در کمتر از ده دقیقه 409 `invitation_too_soon` است.
accessString- با هر شناسه در `addressIds` چه می‌تواند بکند: `member` نشانی را می‌خواند و از آن می‌فرستد، `viewer` فقط می‌خواند. پیش‌فرض `member` است، همان سطحی که کنسول و مسیر قدیمی‌تر اشتراک‌گذاری همیشه به کار برده‌اند، تا یک فراخوانی از اسکریپت و از صفحه یک معنا داشته باشد. برای ترکیبی از سطوح، پس از آن برای مواردی که متفاوت‌اند `grant_address` را فراخوانی کنید.
پاسخ
objectString- همیشه `member`. یک حذف با همین مقدار پاسخ می‌دهد، به‌همراه `userId` او، `deleted: true` و `addressesRevoked`، و هیچ‌یک از فیلدهای دیگرِ زیر.
userIdString- شناسهٔ حساب او، و دستگیره‌ای که هر فراخوانی دیگرِ اعضا به‌عنوان آرگومان نخست می‌گیرد: `get`، `update`، `remove` و هر دو فراخوانی نشانی. افزودن کسی تنها فراخوانی‌ای است که به‌جای آن با ایمیل کار می‌کند، چون کسی که همکاری را می‌افزاید نشانی او را می‌داند نه شناسه‌اش را.
emailString- ایمیل روی حساب او، بازتاب‌شده همان‌گونه که آن ردیف ذخیره‌اش می‌کند. این منبع هرگز آن را نمی‌نویسد، و کوچک‌سازی حروف در `add` به آدرسی که برای جست‌وجو می‌فرستید مربوط است نه به آنچه بازمی‌گردد. پس از مالک، فهرست اعضا بر اساس همین فیلد مرتب می‌شود نه بر اساس زمان پیوستن افراد، چون این فهرست برای یافتن یک نفر خوانده می‌شود نه برای دیدن آنچه تغییر کرده است.
nameString or nil- نام نمایشی او، برگرفته از حسابش، که ستونش همیشه مقداری دارد. nil در نوع آن احتیاطی است، نه وضعیتی که دیده شده این API تولید کند. این نام به خودِ او تعلق دارد نه به فضای کاری، پس هیچ چیز روی این منبع نمی‌تواند آن را تنظیم کند.
imageString or nil- آواتار او، برگرفته از حسابش، و nil وقتی آن را تنظیم نکرده باشد.
role.idString or nil- شناسهٔ نقشی که دارد، که به شکل `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- دقیقاً روی یک ردیف true است، همان حسابی که فضای کاری بر اساس آن کلید خورده است. او هرچه ردیف نقشش بگوید همهٔ مجوزها را دارد، نخست مرتب می‌شود، و `add`، `update` و `remove` همگی او را با `member_is_owner` رد می‌کنند. وقتی صندلی‌ها را می‌شمارید او را کنار بگذارید.
impliedBoolean- وقتی true است که این فرد اعطای نشانی دارد و ردیف عضویت ندارد، پس نقشش استنتاج شده نه انتخاب: هر اعطای `member` آن را نقش درون‌ساخت Member می‌کند، وگرنه Viewer. برای مالک هرگز true نیست. آن را به‌صورت «برآمده از دسترسی» نشان دهید. تا وقتی یک `update` این استنتاج را به تصمیم تبدیل نکند، گسترش دسترسی او به نشانی‌ها بی‌صدا دامنهٔ کارهای مجازش را هم گسترش می‌دهد.
permissionsArray<String>- مجوزهای نقش که روی عضو گسترده شده‌اند، تا یک خواندن بدون گرفتن نقش به «آیا مجاز است؟» پاسخ دهد. برای عضوی که نقشش استنتاجی است، این مجوزها از «الگوی» درون‌ساخت می‌آیند نه از ردیف نقش در این فضای کاری، پس ویرایش نقش درون‌ساخت Member آنچه را عضو استنتاجی دارد تغییر نمی‌دهد.
addressesArray<Hash>- آدرس‌هایی که به او داده شده‌اند، مرتب‌شده بر اساس آدرس، هرکدام با سطح دسترسی خودش. برای کسی که نقش دارد و اعطایی ندارد خالی است، و یک عضو تازه تا وقتی آدرسی به او داده نشده همین شکل است، و این همان شکستِ درستی است که باید رخ دهد تا وقتی هنوز در حال تصمیم‌گیری دربارهٔ آنچه باید ببیند هستید.
addresses[].addressIdString- شناسهٔ نشانی، و همان چیزی که `grant_address` و `revoke_address` می‌گیرند. شناسه‌ای که نشانی‌ای در این فضای کاری نباشد در هر دو رد می‌شود، به‌جای آنکه لغوی گزارش شود که هرگز رخ نداده.
addresses[].addressString- آدرس کامل، با حروف کوچک، بازسازی‌شده از بخش محلی و دامنه‌اش.
addresses[].accessString- با همین یک نشانی چه می‌تواند بکند: `member` آن را می‌خواند و از آن می‌فرستد، `viewer` فقط می‌خواند. هم این و هم نقش باید اجازهٔ ارسال بدهند تا ارسالی رخ دهد، پس نقشی با `emails:send` روی اعطای `viewer` از هیچ نشانی‌ای نمی‌فرستد. نام ستون ذخیره‌شده `role` است، و اینجا نامش عوض شده تا یک Hash دو کلید `role` از دو واژگان متفاوت نداشته باشد.
createdAtString or nil- زمانی که ردیف عضویت او نوشته شد، به‌صورت یک String با قالب ISO 8601، و 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 از دعوت‌نامه‌هایی که هنوز کسی نپذیرفته برمی‌گرداند، list_all_invitations همه را در یک Array برمی‌گرداند، و iterate_invitations هرکدام را به یک بلاک yield می‌کند یا یک Enumerator برمی‌گرداند. resend_invitation دعوت‌نامه را با پیوندی تازه و چهارده روز دیگر دوباره می‌فرستد، و revoke_invitation آن را پس می‌گیرد. دعوت‌نامهٔ در انتظار تا پذیرفته نشود هیچ چیزی اعطا نمی‌کند.
resend_invitation همان نشانی را اگر دو بار در ده دقیقه بیاید با 409 invitation_too_soon رد می‌کند، و revoke_invitation دعوت‌نامه‌ای را که پیش‌تر پذیرفته شده با 409 invitation_accepted رد می‌کند. هر دو به‌صورت OpenEmail::ConflictError raise می‌شوند، پس conflict? برابر true است و code آن‌ها را از هم جدا می‌کند.