انتشار یک برنامه به‌صورت درگاه
هدف
برنامه‌ای را که پیش‌تر کشیده‌اید بردارید و به آن نشانی اینترنتی اختصاصی بدهید تا کسانی که در سازمان شما نیستند — مشتریان، متقاضیان، عموم مردم — بتوانند بدون هیچ ورودی به پلتفرم آن را باز کنند.
پیش از شروع
دو چیز لازم دارید و درگاه بدون اولی ذخیره نمی‌شود:
- یک برنامهٔ استودیویی. درگاه یک نقاشی را منتشر می‌کند، نه اینکه آن را در خود داشته باشد. ساخت برنامهٔ استودیویی را ببینید.
- یک API سفارشی برای هر چیزی که درگاه می‌خواند. درگاه هرگز مستقیم از جدول نمی‌خواند — دلیلش در درگاه چه چیزی را می‌تواند بخواند آمده است. اگر درگاه شما فقط متن و تصویر نشان می‌دهد، از این مورد بگذرید.
گام‌ها
- راه‌حل خود را باز کنید و درگاه‌ها را انتخاب کنید.
- جدید را بزنید.
- یک نام بگذارید. این نامی است که شما و همکارانتان به کار می‌برید؛ چیزی نیست که بازدیدکننده ببیند، چون هر چه بازدیدکننده می‌بیند کشیده شده است.
- از فهرست، برنامهٔ منتشرشده را انتخاب کنید. فقط برنامه‌های همین محیط نمایش داده می‌شوند.
- یک نشانی اینترنتی بنویسید. فقط بخش نخست —
acme-support، نه کل نشانی. بقیهٔ نشانی به استقرار پارس‌ور شما تعلق دارد و راهنمای زیر جعبه نشان می‌دهد نشانی نهایی چه خواهد بود. - چه کسی می‌تواند باز کند را انتخاب کنید. همه یعنی نشانی مستقیم به برنامهٔ شما باز می‌شود؛ کسانی که وارد می‌شوند یک فرم ورود پیش از آن می‌گذارد — ببینید از بازدیدکنندگان بخواهید وارد شوند.
- چه چیزی را می‌خواند را انتخاب کنید — همان APIهای سفارشی که این درگاه اجازهٔ صدا زدنشان را دارد.
- بازدیدکنندگان با این نقش‌ها کار می‌کنند را انتخاب کنید — نقش‌های امنیتی‌ای که هر بازدیدکنندهٔ این درگاه دارد. ببینید درگاه به کدام جدول‌ها دسترسی دارد.
- تا وقتی مشغول کار هستید منتشرشده را تیک نزنید؛ وقتی خواستید نشانی پاسخ بدهد آن را تیک بزنید.
- ذخیره را بزنید.
درگاه چه چیزی را می‌تواند بخواند
درگاه از مسیر APIهای سفارشی‌ای که فهرست می‌کنید می‌خواند، و از هیچ راه دیگری. نمی‌تواند مستقیم از جدول بخواند و هیچ تنظیمی هم برای این کار وجود ندارد.
این عمدی است. کشیدن یک صفحه هرگز نباید به راهی برای قرار دادن ناخواستهٔ یک جدول روی اینترنت تبدیل شود. API سفارشی چیزی است که کسی آگاهانه نوشته است: در اسکریپتی که می‌توانید بخوانید تصمیم می‌گیرد یک غریبه چه ببیند. جدول فقط یک جدول است.
پس اگر صفحه‌ای روی درگاه شما داده لازم دارد، ترتیب کار این است: API سفارشی را تعریف کنید، در فهرست درگاه تیک بزنید، و صفحه را طوری بکشید که از همان بخواند.
نام‌بردن API در صفحهٔ شما
صفحهٔ یک درگاه به‌جای جدول، نام قرارداد را می‌برد:
loadRecords("api:par_articles@1", "articles", { top: 20, orderBy: "par_name" })
api: می‌گوید این یک API سفارشی است؛ par_articles نام منطقی آن است؛ و @1 نسخهٔ آن، چون دو نسخه
از یک API دو قرارداد متفاوت‌اند. همین شکل برای getRecord، createRecord، updateRecord و
deleteRecord هم کار می‌کند — اینکه کدام‌یک را صدا زده‌اید تعیین می‌کند سکو چه می‌کند، و فعل خودِ API
باید بتواند پاسخش دهد. createRecordی که به APIای اشاره کند که فقط می‌خواند، هنگام اجرای صفحه
شکست می‌خورد.
در فهرست برنامه‌ها، صفحهٔ کشیده‌شده مستقیم از جدول‌هایش می‌خواند — این کاری است که برنامهٔ یک کاربرِ
واردشده می‌کند، و به همین دلیل صفحه‌بندی و پالایش دارد. روی درگاه چنین دری وجود ندارد. پس صفحه‌ای که
api: را نام می‌برد روی درگاه باز می‌شود و در پوسته رد می‌شود و همین را می‌گوید، به‌جای آنکه فهرستی
خالی نشان دهد.
اگر یک نقاشی را در هر دو جا می‌خواهید، به دو صفحه نیاز دارد. این معامله‌ای است که سکو آگاهانه کرده است: درگاه شما از راه قراردادی می‌خواند که خودتان نوشته‌اید، و آن قرارداد تصمیم می‌گیرد یک غریبه چه ببیند.
API شما برای یک فهرست باید { "rows": [...], "total": 12 } پاسخ دهد. اگر چیز دیگری پاسخ دهد،
صفحه فهرست خالی نشان می‌دهد نه خطا — پس یک اشتباه در یک API هرگز کل درگاه را خراب نمی‌کند.
این فهرست یک اجازه است، نه یک نقشه. تیک‌زدن یک API یعنی این درگاه می‌تواند آن را صدا بزند؛ همین. اینکه چه وقت، تصمیم صفحهٔ شماست، با نام‌بردن آن. APIای که تیک نزده‌اید رد می‌شود حتی اگر صفحه‌ای بخواهدش — و همین است که نمی‌گذارد یک اشتباه در نقاشی به یک در تبدیل شود.
نوشتن به بازدیدکنندگانی نیاز دارد که وارد می‌شوند — یا به یک آزمون. APIای که POST، PATCH، PUT یا DELETE پاسخ می‌دهد تنها وقتی قابل صداکردن است که چه کسی می‌تواند بازش کند روی «کسانی که وارد می‌شوند» باشد، چون درگاهِ باز کسی را ندارد که تغییر را به او نسبت دهد. تنها راه دور زدن آن، بخش بعدی است.
از کسی که استقرار پارس‌ور شما را اداره می‌کند بپرسید که آیا به میزبان درگاه دامنهٔ دسترسی‌ای که API سفارشی شما می‌خواهد داده شده است یا نه. هر API سفارشی یک دامنه نام می‌برد، و میزبان درگاه همان چیزی است که آن را از طرف بازدیدکنندگان شما نگه می‌دارد — بدون آن، هر خواندن رد می‌شود و صفحه فقط چیزی نشان نمی‌دهد.
درگاه به کدام جدول‌ها دسترسی دارد
APIهای سفارشی‌ای که تیک می‌زنید می‌گویند صفحه کدام قراردادها را می‌تواند صدا بزند. بازدیدکنندگان با این نقش‌ها کار می‌کنند می‌گوید آن قراردادها سپس کدام جدول‌ها را می‌توانند بخوانند و بنویسند — همان نقش‌های امنیتی‌ای که به همکاران خود می‌دهید، با همان مجوزها.
به درگاه نقشی از آنِ خودش بدهید که دقیقاً همان چیزی را اجازه دهد که APIهایش لازم دارند — مثلاً خواندن و ایجاد روی «پرونده‌ها» — نه نقشی که کارکنانتان به کار می‌برند. هر بازدیدکنن دهٔ درگاه، وارد شده یا نشده، آن را دارد.
اگر هیچ نقشی انتخاب نکنید درگاه به هیچ جا نمی‌رسد. فهرست‌هایش خالی است و هر ذخیره‌ای می‌گوید ذخیره نشد. این سمتِ امن است، و نخستین چیزی است که باید بررسی کنید وقتی درگاهی روی صفحه‌ای که درست به نظر می‌رسد چیزی نشان نمی‌دهد.
در درگاهی که بازدیدکنندگان را وارد می‌کند، نقش پایان کار نیست. اگر جدول قاعده‌ای دارد که می‌گوید کدام ردیف مال کیست — ببینید تصمیم بگیرید بازدیدکننده رکوردهای چه کسی را ببیند — هر بازدیدکننده پس از آنکه نقش راهش داد، به ردیف‌های شرکت خودش محدود می‌شود.
نقش مدیر پلتفرم هرگز اینجا پیشنهاد نمی‌شود. بازدیدکننده‌ای که آن را داشته باشد کل محیط را در دست دارد.
اجازه بدهید هر کسی چیزی برایتان بفرستد
گزینهٔ به همه اجازه بده چیزی بفرستند را بزنید — که تنها وقتی دیده می‌شود که چه کسی می‌تواند بازش کند روی «همه» باشد — و آن‌وقت بازدیدکننده‌ای بدون حساب هم می‌تواند بنویسد، به شرط آنکه مرورگرش نخست لحظه‌ای روی معمایی کار کند و ثابت کند اسکریپت نیست.
همین است که فرم تماس را ممکن می‌کند. بدون آن، درگاهی که همه می‌توانند بازش کنند فقط می‌خواند و نمی‌نویسد — یعنی باید از کسی بخواهید پیش از فرستادن یک پیام حساب بسازد، و آن دیگر فرم تماس نیست.
چیزی برای کشیدن نیست و کاری هم از بازدیدکننده خواسته نمی‌شود. نه مربعی برای تیک‌زدن، نه کلمه‌ای کج‌وکوله برای خواندن، نه عکس چراغ راهنما. سکو یک محاسبهٔ کوچک به مرورگر می‌دهد؛ یک لپ‌تاپ پیش از آنکه متوجه شوید تمامش می‌کند و یک گوشی قدیمی لحظه‌ای وقت می‌گیرد و زیر دکمه می‌نویسد «در حال بررسی اینکه شما انسان هستید…». هیچ چیزی دربارهٔ بازدیدکننده جمع نمی‌شود و هیچ چیزی روی صفحه از سرور شرکت دیگری نمی‌آید.
چه چیزی را می‌گیرد و چه چیزی را نه. ارسال انبوه را گران می‌کند: اسکریپتی که می‌توانست ساعتی هزار فرم بفرستد حالا برای هرکدام کار واقعی می‌پردازد، پس عملاً چهل تا می‌فرستد. اما کسی را که مصمم است و حاضر است مرورگرهای واقعی اجرا کند نمی‌گیرد — و هیچ گزینه‌ای در هیچ کجا، با هر نامی، این کار را نمی‌کند. آن را یک فیلتر هرزنامهٔ کارآمد بدانید، نه یک قفل.
سه چیز را تغییر نمی‌دهد:
- چه چیزی صدا زده می‌شود. فقط همان APIهای سفارشی‌ای که بالاتر تیک زدید، دقیقاً مثل قبل.
- چه چیزی نوشته می‌شود. همچنان طرح درخواستِ خودِ API تعیین می‌کند بازدیدکننده کدام فیلدها را می‌تواند بگذارد.
- چه کسی کیست. کسی وارد نشده، پس هیچ چیزی تأیید نشده است. اگر API شما نشانی ایمیلی را که بازدیدکننده تایپ کرده ذخیره می‌کند، آن فقط نشانی‌ای است که کسی تایپ کرده. جایی که این مهم است، به جایش از بازدیدکنندگان بخواهید وارد شوند.
portal-contact-form در samples/solutions/ دقیقاً همین است: یک درگاه باز، یک نوشتن، یک پرونده
پیوست‌شده به آن، و صفحه‌ای در خودِ سایت که می‌گوید به چه چیزی نگاه کنید.
گشودن آن
وقتی درگاهی نشانی داشته باشد، فهرست نشانی را به‌صورت پیوند نشان می‌دهد و گشودن درگاه در نوار فرمان آن را در زبانهٔ تازه باز می‌کند. اگر درگاه را برای ویرایش باز کنید، همان نشانی زیر جعبهٔ نشانی اینترنتی می‌آید، با دو دکمهٔ کوچک کنارش: یکی درگاه را باز می‌کند، برای وقتی که می‌خواهید نگاهش کنید، و دیگری نشانی را رونوشت می‌گیرد، برای وقتی که می‌خواهید آن را برای کسی بفرستید. هیچ‌کدام واژه‌ای نشان نمی‌دهند — نشانی بلند است و برچسب‌ها دکمهٔ دوم را به سطر بعد می‌رانند — پس نشانگر را روی هرکدام ببرید تا بگوید کدام است.
نشانی تنها پس از ذخیره ظاهر می‌شود. تا وقتی برچسب را می‌نویسید، راهنمای زیر جعبه نشان می‌دهد نشانی نهایی چه شکلی خواهد بود؛ پیوندی که از چیزِ ذخیره‌نشده ساخته شود به درگاهی اشاره می‌کند که آنجا نیست.
اگر نصب شما هیچ درگاهی را سرویس نمی‌دهد، نشانی‌ای برای گشودن وجود ندارد و به‌جای پیوند همان راهنما می‌ماند. از کسی که استقرار پارس‌ور شما را اداره می‌کند بپرسید.
این جمله هرگز دربارهٔ درگاه شما نیست — سکو می‌گوید که نتوانسته پاسخ دهد، و نقشهٔ شما، نشانی شما و کلید منتشرشده هیچ‌کدام در آن دخیل نیستند. یکی از دو چیز است و هر دو به کسی مربوط‌اند که نصب شما را اداره می‌کند: سرویس‌ها بالا نیستند، یا میزبان درگاه نمی‌تواند از پارس‌ور اعتبارنامه بگیرد. نشانی اشتباه چیز دیگری می‌گوید («اینجا چیزی منتشر نشده است»)، پس از روی خود صفحه می‌توان این دو را از هم بازشناخت.
آنچه بازدیدکننده می‌بیند
دو چیز در صفحهٔ یک درگاه از آنِ سکوست نه از آنِ شما، و دانستنِ هر دو پیش از آنکه کسی از شما بپرسد می‌ارزد.
درگاه در حالت تیره باز می‌شود. برنامه‌های خودتان در پارس‌ور روشن باز می‌شوند، چون آنجا جایی است که یک روز کاری را در آن می‌نشینید؛ درگاه جایی است که ناآشنایی از پیوندی در یک پیام واردِ آن می‌شود، اغلب با تلفن، و تیره نخستین برخوردِ مهربان‌تری است. دکمه‌ای کوچک برای حالت روشن/تیره در گوشهٔ بالای هر صفحهٔ درگاه شناور است — در انگلیسی سمت راست، در فارسی و عربی سمت چپ — و نخستین باری که بازدیدکننده آن را بفشارد، همان از آن پس انتخاب اوست: مرورگر آن را به یاد می‌سپارد، و پیش‌فرضِ تیره هرگز با کسی که پیش‌تر پاسخ داده است بحث نمی‌کند.
همچنان می‌توانید کلیدِ خودتان را بکشید. setTheme("light") و setTheme("dark") در هر دستگیرهٔ یک
صفحهٔ کشیده‌شده در دسترس‌اند، و دکمه‌ای که شما می‌کشید با دکمهٔ گوشه روی یک تنظیم کار می‌کنند.
دکمهٔ گوشه کفِ کار است، تا درگاه پیش از آنکه کسی به کشیدنِ یکی فکر کند خوانا باشد.
و نقشه خود را با پنجره جفت می‌کند. صفحه در اندازه‌ای کشیده می‌شود، اما در همان اندازه نشان داده نمی‌شود: بلوک‌هایی که پهنای صفحه را می‌گیرند فاصلهٔ خود را تا هر حاشیه نگه می‌دارند و میانه را رها می‌کنند، و چیزهایی که کنار هم کشیده شده‌اند سهمِ خود از پهنا را نگه می‌دارند. پس درگاه در هر پهنایی درونِ پنجره‌ای که باز شده جا می‌شود و چیزی از صفحه بیرون نمی‌زند.
آنچه این جفت‌شدن نمی‌تواند بکند بازچیدن است. دو ستون که کنار هم کشیده شده‌اند کنار هم می‌مانند — روی تلفن دو ستونِ باریک، نه یک ستون با دومی زیرِ اولی. اگر درگاهی روی تلفن اهمیت دارد، صفحه‌ای برای تلفن بکشید: سه نمونهٔ درگاهی روی رومیزی / تبلت / تلفن دقیقاً برای همین‌اند.
دربارهٔ نشانی
هر نشانی فقط به یک درگاه پاسخ می‌دهد، در کل نصب. نه یکی به ازای هر محیط — یکی در مجموع. جلوی همهٔ محیط‌ها یک درِ ورودی واحد هست و بر اساس نشانی تصمیم می‌گیرد درخواست کجا برود.
این یک پیامد دارد که نخستین بار هنگام ارتقای راه‌حل با آن روبه‌رو می‌شوید:
همان راه‌حل را در محیط آزمون یا تولید وارد کنید و نشانی درخواستی‌اش پیش‌تر به محیطی که در آن ساخته شده پاسخ می‌دهد. پس درگاه بدون نشانی و خاموش می‌رسد و در این فهرست با برچسب نشانی می‌خواهد دیده می‌شود.
این خطا نیست و هیچ چیزی در راه‌حل شما خراب نشده است. درگاه توسعه و درگاه تولید شما از ابتدا هم قرار بود نشانی‌های متفاوتی داشته باشند. درگاه را در محیط جدید باز کنید، نشانی دلخواهتان را بدهید و منتشرشده را تیک بزنید.
روشن و خاموش کردن
منتشرشده تنها تیکی در پرتال سازنده است که «روشن» بودنش یعنی هر کس در جهان که نشانی را بداند می‌تواند این را ببیند. بنابراین:
- خاموش شروع می‌شود و تا خودتان روشنش نکنید خاموش می‌ماند.
- تا وقتی درگاه نشانی ندارد روشن نمی‌شود — جایی برای پاسخ دادن نیست. دامنهٔ خودتان تنها پس از تأیید یک نشانی به شمار می‌آید، به همان دلیل: در دامنهٔ تأییدنشده چیزی پاسخ نمی‌دهد.
- خاموش کردنش بی‌درنگ پاسخ‌دهی نشانی را متوقف می‌کند. برنامه‌ای که منتشر می‌کرد دست‌نخورده می‌ماند.
حذف یک درگاه
حذف درگاه پاسخ‌دهی نشانی را متوقف می‌کند و آن نشانی را برای چیز دیگری آزاد می‌کند. برنامه را حذف نمی‌کند — نقاشی همچنان برنامه‌ای می‌ماند که افراد خودتان در پوسته باز می‌کنند، و همین دلیل اصلی جدا بودن انتشار از کشیدن است.