اعضا
`members.list`، `list_all`، `iterate`، `get`، `add`، `update`، `remove`، `grant_address`، `revoke_address` و متدهای دعوت‌نامه در کنارشان.
همهٔ متدها
from openemail import openemail roles = openemail.roles.list_all()support = next(role for role in roles if role['name'] == 'Support')viewer = next(role for role in roles if role['builtin'] == 'viewer') invitation = openemail.members.add({ 'email': '[email protected]', 'roleId': support['id'], 'addressIds': ['2b81de07-…'], 'access': 'member',}) people = openemail.members.list_all()sam = next(person for person in people if person['email'] == '[email protected]')member = openemail.members.get(sam['userId']) openemail.members.update(sam['userId'], {'roleId': viewer['id']}) openemail.members.grant_address(sam['userId'], { 'addressId': 'c40a95f2-…', 'access': 'viewer',})openemail.members.revoke_address(sam['userId'], 'c40a95f2-…') openemail.members.remove(sam['userId'])برای هر فرد دو اعطا وجود دارد و نباید در هم ادغام شوند. role می‌گوید چه کاری مجاز است؛ addresses می‌گوید روی چه چیزی. هر دو باید هم‌داستان باشند: نقشی با emails:send همراه با 'access': 'viewer' روی invoices@ یعنی کسی که می‌تواند ایمیل بفرستد اما نمی‌تواند از آن آدرس بفرستد. استثنا نقشی است که addresses:all را دارد، که هر چه addresses فهرست کند به همهٔ آدرس‌ها می‌رسد، چون آن آرایه فقط اعطاهای مستقیم را دارد، پس پیش از آنکه آن را همهٔ دسترسی یک نفر بخوانید، permissions را بررسی کنید.
هر متد userId را می‌گیرد، نه ایمیل را. add تنها استثناست، چون یک آدرس را دعوت می‌کند: آن فرد تنها پس از پذیرفتن دعوت userId دارد، و list_invitations تا آن زمان دعوت‌نامه را دنبال می‌کند.
'implied': True یعنی هیچ‌کس نقش را انتخاب نکرده است. آن فرد آدرس دارد و ردیف نقش ندارد، پس نقش از گسترده‌ترین اعطایی که دارد استنتاج شده است. آن را «هنوز تصمیم‌گیری نشده» بدانید، و update همان چیزی است که استنتاج را به تصمیم تبدیل می‌کند. تا آن زمان، گسترده‌تر کردن دسترسی آدرسی او بی‌صدا کارهایی را که مجاز است گسترده‌تر می‌کند.
مالک فضای کاری نخستین ردیف است و با 'isOwner': True نشانه‌گذاری می‌شود، در حالی که add، update و remove همچنان با member_is_owner او را رد می‌کنند. یک فضای کاری به‌اشتراک‌گذاشته‌نشده یک عضو گزارش می‌کند نه صفر عضو، پس وقتی صندلی‌ها را می‌شمارید isOwner را کنار بگذارید.
remove هر دو محور را می‌گیرد، یعنی نقش و همهٔ اعطاهای آدرس روی این فضای کاری، و addressesRevoked را گزارش می‌کند. revoke_address مورد باریک است، برای کسی که تیمش عوض شده نه کسی که رفته است.
پارامترها
emailstrالزامی- چه کسی دعوت شود، trimشده و با حروف کوچک. هنوز لازم نیست حساب داشته باشد: همه دعوت می‌شوند و نقش و اعطاها هنگام پذیرش اعمال می‌شوند. کسی که از پیش در فضای کاری است `member_is_owner` (422) می‌گیرد.
roleIdstrالزامی- نقشی که خواهد داشت، 1 تا 128 نویسه، و باید نقشی روی همین فضای کاری باشد: شناسهٔ ناشناخته `role_not_found` (404 Not Found) است. نقش مالک قابل اعطا نیست و با `role_immutable` (409 Conflict) بازمی‌گردد، چون مالک کردن کسی یعنی انتقال فضای کاری و برای آن اینجا فراخوانی‌ای وجود ندارد.
addressIdslist[str]- آدرس‌هایی که دعوت‌نامه با خود دارد، حداکثر 64 شناسه که هرکدام 1 تا 128 نویسه است، و هنگام پذیرفته شدن دعوت اعطا می‌شوند. هر شناسه پیش از نوشته شدن هر چیزی بررسی می‌شود، پس شناسه‌ای که آدرسی روی این فضای کاری نباشد کل فراخوانی را با 422 `member_not_found` رد می‌کند و چیزی فرستاده نمی‌شود. دعوت دوبارهٔ همان آدرس در کمتر از ده دقیقه 409 `invitation_too_soon` است.
accessLiteral['member', 'viewer']- با هر شناسه در `addressIds` چه می‌تواند بکند: `member` آدرس را می‌خواند و از آن می‌فرستد، `viewer` فقط می‌خواند. پیش‌فرض `member` است، همان سطحی که کنسول و مسیر قدیمی اشتراک‌گذاری همیشه به کار برده‌اند، تا یک فراخوانی از اسکریپت و از صفحه یک معنا بدهد؛ برای ترکیبی از سطوح، بعداً برای موارد متفاوت `grant_address` را صدا بزنید.
پاسخ
objectLiteral['member']- همیشه `member`. یک حذف با همین مقدار پاسخ می‌دهد، به‌همراه `userId` او، `'deleted': True` و `addressesRevoked`، و هیچ‌یک از فیلدهای دیگرِ زیر.
userIdstr- شناسهٔ حساب او، و همان دستگیره‌ای که هر فراخوانی دیگر عضو در مسیر می‌گیرد: get، update، remove و هر دو فراخوانی آدرس. افزودن کسی تنها فراخوانی‌ای است که به‌جای آن با ایمیل کار می‌کند، چون کسی که همکاری را اضافه می‌کند آدرس او را می‌داند نه شناسه‌اش را.
emailstr- ایمیل روی حساب او، بازتاب‌شده همان‌گونه که آن ردیف ذخیره‌اش می‌کند. این منبع هرگز آن را نمی‌نویسد، و کوچک‌سازی حروف در `add` به آدرسی که برای جست‌وجو می‌فرستید مربوط است نه به آنچه بازمی‌گردد. پس از مالک، فهرست اعضا بر اساس همین فیلد مرتب می‌شود نه بر اساس زمان پیوستن افراد، چون این فهرست برای یافتن یک نفر خوانده می‌شود نه برای دیدن آنچه تغییر کرده است.
namestr | None- نام نمایشی او، گرفته‌شده از حسابش، جایی که آن ستون NOT NULL است. `None` در تایپ جنبهٔ احتیاطی دارد نه حالتی که از این API دیده شده باشد. این نام به خودِ او تعلق دارد نه به فضای کاری، پس هیچ‌چیز روی این منبع نمی‌تواند آن را تنظیم کند.
imagestr | None- آواتار او، گرفته‌شده از حسابش، و وقتی تنظیمش نکرده باشد null.
role.idstr | None- شناسهٔ نقشی که دارد، یا وقتی هیچ‌کس آن را انتخاب نکرده باشد null. `implied` را ببینید. یک null اینجا تنها موردی است که `role` به‌جای تصمیمِ کسی، یک استنتاج را گزارش می‌کند.
role.namestr- نام نقش. برای عضو implied این نامِ قالب داخلی‌ای است که دسترسی او به آن رسیده است، نه ردیفی روی این فضای کاری.
role.builtinLiteral['owner', 'admin', 'member', 'viewer', 'developer', 'billing'] | None- اینکه نقش کدام نقش داخلی است، یا برای نقشی سفارشی null. `owner` تنها روی ردیف خودِ مالک ظاهر می‌شود، در کنار `'isOwner': True`؛ اختصاص آن نقش به هر کسی با `role_immutable` (409 Conflict) رد می‌شود.
isOwnerbool- دقیقاً روی یک ردیف true است، همان حسابی که فضای کاری بر اساس آن کلید خورده است. او هرچه ردیف نقشش بگوید همهٔ مجوزها را دارد، نخست مرتب می‌شود، و `add`، `update` و `remove` همگی او را با `member_is_owner` رد می‌کنند. وقتی صندلی‌ها را می‌شمارید او را کنار بگذارید.
impliedbool- وقتی true است که این فرد اعطای آدرس داشته باشد و ردیف عضویت نداشته باشد، یعنی نقشش به‌جای انتخاب شدن استنتاج شده است: هر اعطای `member` به Member داخلی می‌رسد و در غیر این صورت به Viewer. برای مالک هرگز true نیست. آن را به‌صورت «استنتاج‌شده از دسترسی» نمایش دهید. تا وقتی یک PATCH استنتاج را به تصمیم تبدیل نکند، گسترده‌تر کردن دسترسی آدرسی او بی‌صدا کارهایی را که مجاز است گسترده‌تر می‌کند.
permissionslist[Permission]- مجوزهای نقش که روی عضو صاف شده‌اند، تا یک خواندن به پرسش «آیا مجاز است؟» بدون گرفتن نقش پاسخ دهد. برای عضو implied این مجوزها از قالب داخلی می‌آیند نه از ردیف نقش این فضای کاری، پس ویرایش نقش داخلی Member چیزی را که یک عضو implied دارد تغییر نمی‌دهد.
addresseslist[MemberAddressResource]- آدرس‌هایی که به او داده شده‌اند، مرتب‌شده بر اساس آدرس، هرکدام با سطح دسترسی خودش. برای کسی که نقش دارد و اعطایی ندارد خالی است، و یک عضو تازه تا وقتی آدرسی به او داده نشده همین شکل است، و این همان شکستِ درستی است که باید رخ دهد تا وقتی هنوز در حال تصمیم‌گیری دربارهٔ آنچه باید ببیند هستید.
addresses[].addressIdstr- شناسهٔ آدرس، و همان چیزی که `grant_address` و `revoke_address` می‌گیرند. شناسه‌ای که آدرسی روی این فضای کاری نباشد در هر دو رد می‌شود، نه اینکه لغوی گزارش شود که هرگز رخ نداده است.
addresses[].addressstr- آدرس کامل، با حروف کوچک، بازسازی‌شده از بخش محلی و دامنه‌اش.
addresses[].accessLiteral['member', 'viewer']- با همین یک آدرس چه می‌تواند بکند: `member` آن را می‌خواند و از آن می‌فرستد، `viewer` فقط می‌خواند. پیش از آنکه ارسالی رخ دهد هم این و هم نقش باید اجازه دهند، پس نقشی با `emails:send` روی یک اعطای `viewer` از هیچ‌جا نمی‌فرستد؛ نام ستون ذخیره‌شده `role` است و اینجا تغییر نام یافته تا یک object دو `role` از دو واژگان متفاوت را با خود حمل نکند.
createdAtstr | None- زمان نوشته شدن ردیف عضویت او، ISO-8601، و وقتی اصلاً ردیف عضویتی نباشد null. آن null همان جمعیتی را توصیف می‌کند که `'implied': True`: کسانی که از پیش از پیدایش نقش‌ها آدرس دارند و از آن زمان هیچ‌کس نقشی به آنان نداده است.
دعوت‌نامه‌ها
from openemail import openemail waiting = openemail.members.list_all_invitations() for invitation in waiting: if invitation['expired']: openemail.members.resend_invitation(invitation['id']) openemail.members.revoke_invitation('winv_6bb640f5b99e47deb758f1f5')add با یک دعوت‌نامه پاسخ می‌دهد، و این‌ها فراخوانی‌هایی‌اند که پیگیری‌اش می‌کنند: list_invitations، list_all_invitations و iterate_invitations دعوت‌نامه‌هایی را می‌خوانند که هنوز کسی نپذیرفته، resend_invitation یکی را با لینکی تازه و چهارده روز بیشتر دوباره می‌فرستد، و revoke_invitation آن را پس می‌گیرد. دعوت‌نامهٔ منتظر تا پذیرفته نشود چیزی نمی‌دهد.
resend_invitation یک نشانی را اگر در ده دقیقه دو بار بخواهید با 409 invitation_too_soon رد می‌کند، و revoke_invitation دعوت‌نامه‌ای را که پیش‌تر پذیرفته شده با 409 invitation_accepted رد می‌کند.
کدهای تأیید هویت
add، update، remove، grant_address و revoke_address پیش از آنکه چیزی را تغییر دهند از توکن دسترسی OAuth کد تأیید هویت می‌خواهند، و resend_invitation و revoke_invitation نمی‌خواهند. فراخوانی یک OpenEmailApiError را raise می‌کند که is_step_up_required آن True است: با security.begin_step_up() یک کد بخواهید، کدی را که شخص به شما می‌دهد با security.verify_step_up({'code': ...}) بررسی کنید، سپس دوباره فراخوانی کنید. هر تأیید هویت 60 دقیقه اعتبار دارد، و از کلید API هرگز خواسته نمی‌شود.
مرجع
members.list()مرجع کاملmembers.list_all()مرجع کاملmembers.iterate()مرجع کاملmembers.get()مرجع کاملmembers.add()مرجع کاملmembers.update()مرجع کاملmembers.remove()مرجع کاملmembers.grant_address()مرجع کاملmembers.revoke_address()مرجع کاملmembers.list_invitations()مرجع کاملmembers.list_all_invitations()مرجع کاملmembers.iterate_invitations()مرجع کاملmembers.resend_invitation()مرجع کاملmembers.revoke_invitation()مرجع کامل