اعضا
`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;برای هر فرد دو اعطا وجود دارد، و نباید در هم ادغام شوند. role می‌گوید چه کاری مجاز است. addresses و domains می‌گویند روی چه چیزی. هر دو باید هم‌داستان باشند: نقشی با emails:send در حالی که access روی invoices@ برابر viewer است، یعنی کسی که می‌تواند ایمیل بفرستد اما نمی‌تواند از آن نشانی بفرستد. استثنا نقشی است که addresses:all دارد، که فارغ از آنچه addresses فهرست می‌کند به همهٔ نشانی‌ها می‌رسد، چون آن آرایه فقط اعطاهای مستقیم را نگه می‌دارد. پس پیش از آنکه addresses را کل گسترهٔ دسترسی کسی بدانید، permissions را بررسی کنید.
هر فراخوانی دربارهٔ یک فرد، userId او را به‌عنوان آرگومان نخست می‌گیرد، نه ایمیلش را، پس آن را از list یا listAll بخوانید، همان‌طور که نمونه انجام می‌دهد. add تنها استثناست، چون یک نشانی را دعوت می‌کند: آن فرد تنها پس از پذیرفتن دعوت userId دارد، و listInvitations تا آن زمان دعوت‌نامه را دنبال می‌کند. بدنهٔ add، update، grantAddress و grantDomain یک آرایه است که کلیدهایش نام‌های camelCase در API هستند (roleId، addressIds، addressId).
list یک OpenEmail\Result\Page برمی‌گرداند، listAll همهٔ اعضا را در یک آرایه برمی‌گرداند، و iterate یک Generator برمی‌گرداند که هر بار یک عضو را yield می‌کند. عضو به‌صورت یک آرایه با کلیدهای camelCase برمی‌گردد، و role یک آرایه درون آن است، پس $member['role']['name'] نام نقش را می‌خواند.
اگر implied برابر true باشد، یعنی هیچ‌کس نقش را انتخاب نکرده است. آن فرد نشانی یا دامنه دارد و ردیف نقش ندارد، پس نقش از گسترده‌ترین اعطایی که دارد استنتاج شده است. آن را «هنوز تصمیم‌گیری نشده» بدانید، و update همان چیزی است که استنتاج را به تصمیم تبدیل می‌کند. تا آن زمان، گسترده‌تر کردن دسترسی او به نشانی‌ها بی‌صدا کارهایی را که مجاز است گسترده‌تر می‌کند.
مالک فضای کاری نخستین ردیف است و isOwner در آن برابر true است، در حالی که add، update و remove همچنان او را با member_is_owner رد می‌کنند، یک 422 که به‌صورت ValidationException پرتاب می‌شود. فضای کاری‌ای که با کسی به اشتراک گذاشته نشده یک عضو گزارش می‌کند نه صفر، پس وقتی صندلی‌ها را می‌شمارید isOwner را کنار بگذارید: count(array_filter($client->members->listAll(), fn(array $member): bool => !$member['isOwner'])).
remove هر دو محور را برمی‌دارد، یعنی نقش «و» همهٔ اعطاهای نشانی و دامنه روی این فضای کاری، و در addressesRevoked گزارش می‌کند که با احتساب دامنه‌ها چند اعطا را لغو کرده است. revokeAddress مورد محدودتر است، برای کسی که تیمش عوض شده نه کسی که رفته است، و revokeDomain همین کار را برای یک دامنهٔ کامل انجام می‌دهد.
add، update، remove و چهار فراخوانی اعطا و لغو از توکن دسترسی OAuth کد تأیید هویت می‌خواهند، و از کلید API هرگز. تا وقتی توکن کدی تأیید نکرده باشد، این فراخوانی‌ها یک PermissionException پرتاب می‌کنند که isStepUpRequired() آن true است. add و grantDomain همچنین به طرحی نیاز دارند که تیم را در بر بگیرد، و روی طرحی که چنین نیست یک PermissionException پرتاب می‌کنند که errorCode آن برابر plan_required است.
پارامترها
emailstringالزامی- چه کسی دعوت شود، با حذف فاصله‌های ابتدا و انتها و با حروف کوچک. هنوز لازم نیست حساب داشته باشد: همه دعوت می‌شوند و نقش و اعطاها هنگام پذیرش اعمال می‌شوند. کسی که از پیش در فضای کاری است `member_is_owner` (422) می‌گیرد. نشانی‌ای که با گذرواژهٔ خودش وارد می‌شود قابل دعوت نیست و با `mailbox_login` (403) برمی‌گردد، پس به‌جای آن ایمیل خودِ آن فرد را دعوت کنید.
roleIdstringالزامی- نقشی که خواهد داشت، 1 تا 128 نویسه، و باید نقشی روی همین فضای کاری باشد: شناسهٔ ناشناخته `role_not_found` (404) است که به‌صورت `NotFoundException` پرتاب می‌شود. نقش مالک قابل اعطا نیست و با `role_immutable` (409) برمی‌گردد، چون مالک کردن کسی یعنی انتقال فضای کاری، و برای آن اینجا فراخوانی‌ای وجود ندارد.
addressIdsarray- آدرس‌هایی که دعوت‌نامه با خود دارد، حداکثر 64 شناسه که هرکدام 1 تا 128 نویسه است، و هنگام پذیرفته شدن دعوت اعطا می‌شوند. هر شناسه پیش از نوشته شدن هر چیزی بررسی می‌شود، پس شناسه‌ای که آدرسی روی این فضای کاری نباشد کل فراخوانی را با 422 `member_not_found` رد می‌کند و چیزی فرستاده نمی‌شود. دعوت دوبارهٔ همان آدرس در کمتر از ده دقیقه 409 `invitation_too_soon` است.
domainIdsarray- دامنه‌های کاملی که دعوت‌نامه با خود می‌برد، حداکثر 64 شناسه، که هنگام پذیرفته شدن اعطا می‌شوند. اعطای یک دامنه به همهٔ نشانی‌های آن دامنه می‌رسد، از جمله نشانی‌هایی که بعداً ساخته می‌شوند. شناسه‌ای که دامنه‌ای روی این فضای کاری نباشد، مانند یک نشانی، 422 `member_not_found` است.
accessstring- با هر شناسه در `addressIds` و `domainIds` چه می‌تواند بکند: `member` نشانی را می‌خواند و از آن می‌فرستد، `viewer` فقط می‌خواند. پیش‌فرض `member` است، همان سطحی که کنسول و مسیر قدیمی‌تر اشتراک‌گذاری همیشه به کار برده‌اند، تا یک فراخوانی از اسکریپت و از صفحه یک معنا داشته باشد. برای ترکیبی از سطوح، پس از آن برای مواردی که متفاوت‌اند `grantAddress` را فراخوانی کنید.
پاسخ
objectstring- همیشه `member`. یک حذف با همین مقدار پاسخ می‌دهد، به‌همراه `userId` او، `deleted` با مقدار true و `addressesRevoked`، و هیچ‌یک از فیلدهای دیگرِ زیر.
userIdstring- شناسهٔ حساب او، و دستگیره‌ای که هر فراخوانی دیگرِ اعضا به‌عنوان آرگومان نخست می‌گیرد: `get`، `update`، `remove` و چهار فراخوانی اعطا و لغو. افزودن کسی تنها فراخوانی‌ای است که به‌جای آن با ایمیل کار می‌کند، چون کسی که همکاری را می‌افزاید نشانی او را می‌داند نه شناسه‌اش را.
emailstring- ایمیل روی حساب او، بازتاب‌شده همان‌گونه که آن ردیف ذخیره‌اش می‌کند. این منبع هرگز آن را نمی‌نویسد، و کوچک‌سازی حروف در `add` به آدرسی که برای جست‌وجو می‌فرستید مربوط است نه به آنچه بازمی‌گردد. پس از مالک، فهرست اعضا بر اساس همین فیلد مرتب می‌شود نه بر اساس زمان پیوستن افراد، چون این فهرست برای یافتن یک نفر خوانده می‌شود نه برای دیدن آنچه تغییر کرده است.
namestring or null- نام نمایشی او، برگرفته از حسابش، که ستونش همیشه مقداری دارد. null در نوع آن احتیاطی است، نه وضعیتی که دیده شده این API تولید کند. این نام به خودِ او تعلق دارد نه به فضای کاری، پس هیچ چیز روی این منبع نمی‌تواند آن را تنظیم کند.
imagestring or null- آواتار او، گرفته‌شده از حسابش، و وقتی تنظیمش نکرده باشد null.
role.idstring or null- شناسهٔ نقشی که دارد، که به شکل `$member['role']['id']` خوانده می‌شود، یا null وقتی کسی آن را انتخاب نکرده. `implied` را ببینید. null در اینجا تنها حالتی است که `role` یک استنتاج را گزارش می‌کند نه تصمیمی که کسی گرفته.
role.namestring- نام نقش. برای عضوی که نقشش استنتاجی است، نام الگوی درون‌ساختی است که دسترسی او به آن نگاشت می‌شود، نه ردیفی در این فضای کاری.
role.builtinstring or null- اینکه نقش کدام نقش درون‌ساخت است، `owner`، `admin`، `member`، `viewer`، `developer` یا `billing`، یا null برای نقشی سفارشی. `owner` فقط روی ردیف خودِ مالک، در کنار `isOwner` برابر true، می‌آید. واگذاری آن نقش به هر کسی با `role_immutable` (409) رد می‌شود.
isOwnerbool- دقیقاً روی یک ردیف true است، همان حسابی که فضای کاری بر اساس آن کلید خورده است. او هرچه ردیف نقشش بگوید همهٔ مجوزها را دارد، نخست مرتب می‌شود، و `add`، `update` و `remove` همگی او را با `member_is_owner` رد می‌کنند. وقتی صندلی‌ها را می‌شمارید او را کنار بگذارید.
impliedbool- وقتی true است که این فرد اعطای نشانی یا دامنه دارد و ردیف عضویت ندارد، پس نقشش استنتاج شده نه انتخاب: هر اعطای `member` آن را نقش درون‌ساخت Member می‌کند، وگرنه Viewer. برای مالک هرگز true نیست. آن را به‌صورت «برآمده از دسترسی» نشان دهید. تا وقتی یک `update` این استنتاج را به تصمیم تبدیل نکند، گسترش دسترسی او به نشانی‌ها بی‌صدا دامنهٔ کارهای مجازش را هم گسترش می‌دهد.
permissionsarray- مجوزهای نقش که روی عضو گسترده شده‌اند، تا یک خواندن بدون گرفتن نقش به «آیا مجاز است؟» پاسخ دهد. برای عضوی که نقشش استنتاجی است، این مجوزها از «الگوی» درون‌ساخت می‌آیند نه از ردیف نقش در این فضای کاری، پس ویرایش نقش درون‌ساخت Member آنچه را عضو استنتاجی دارد تغییر نمی‌دهد.
addressesarray- آدرس‌هایی که به او داده شده‌اند، مرتب‌شده بر اساس آدرس، هرکدام یک آرایه با سطح دسترسی خودش. برای کسی که نقش دارد و اعطایی ندارد خالی است، و یک عضو تازه تا وقتی آدرسی به او داده نشده همین شکل است، و این همان شکستِ درستی است که باید رخ دهد تا وقتی هنوز در حال تصمیم‌گیری دربارهٔ آنچه باید ببیند هستید.
addresses[].addressIdstring- شناسهٔ آدرس، و همان چیزی که `grantAddress` و `revokeAddress` می‌گیرند. شناسه‌ای که آدرسی روی این فضای کاری نباشد در هر دو رد می‌شود، نه اینکه لغوی گزارش شود که هرگز رخ نداده است.
addresses[].addressstring- آدرس کامل، با حروف کوچک، بازسازی‌شده از بخش محلی و دامنه‌اش.
addresses[].accessstring- با همین یک نشانی چه می‌تواند بکند: `member` آن را می‌خواند و از آن می‌فرستد، `viewer` فقط می‌خواند. هم این و هم نقش باید اجازهٔ ارسال بدهند تا ارسالی رخ دهد، پس نقشی با `emails:send` روی اعطای `viewer` از هیچ نشانی‌ای نمی‌فرستد. نام ستون ذخیره‌شده `role` است، و اینجا نامش عوض شده تا یک آرایه دو کلید `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 از دعوت‌نامه‌هایی که هنوز کسی نپذیرفته برمی‌گرداند، listAllInvitations همه را در یک آرایه برمی‌گرداند، و iterateInvitations یک Generator برمی‌گرداند که هر بار یکی را yield می‌کند. resendInvitation دعوت‌نامه را با پیوندی تازه و چهارده روز دیگر دوباره می‌فرستد، و revokeInvitation آن را پس می‌گیرد. دعوت‌نامهٔ در انتظار تا پذیرفته نشود هیچ چیزی اعطا نمی‌کند.
دعوت‌نامه یک آرایه است با id، email، role، addresses، domains، expiresAt، expired، lastSentAt و createdAt. delivered و deliveryError گزارش می‌دهند که آخرین ایمیل دعوت چه سرنوشتی داشته است، تا یک اسکریپت بتواند دعوت‌نامه‌ای را که فقط نوشته شده از دعوت‌نامه‌ای که به دست کسی رسیده تشخیص دهد.
resendInvitation همان نشانی را اگر دو بار در ده دقیقه بیاید با 409 invitation_too_soon رد می‌کند، و revokeInvitation دعوت‌نامه‌ای را که پیش‌تر پذیرفته شده با 409 invitation_accepted رد می‌کند. هر دو به‌صورت ConflictException پرتاب می‌شوند، پس isConflict() برابر true است و errorCode آن‌ها را از هم جدا می‌کند.