سرویس HTML: با توابع سرور ارتباط برقرار کنید (original) (raw)
google.script.run یک API جاوا اسکریپت سمت کلاینت ناهمزمان است که به صفحات سرویس HTML امکان فراخوانی توابع برنامه های اسکریپت سمت سرور را می دهد. مثال زیر ابتدایی ترین عملکرد google.script.run را نشان می دهد - فراخوانی یک تابع در سرور از جاوا اسکریپت سمت کلاینت.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }
function doSomething() { Logger.log('I was called!'); }
Index.html
اگر این اسکریپت را به عنوان یک برنامه وب اجرا کنید و از URL آن بازدید کنید، چیزی نمی‌بینید، اما اگر گزارش‌ها را مشاهده کنید، خواهید دید که تابع سرور doSomething() فراخوانی شده است.
فراخوانی های سمت کلاینت به توابع سمت سرور ناهمزمان هستند: پس از درخواست مرورگر که سرور تابع doSomething() را اجرا کند، مرورگر بلافاصله به خط بعدی کد ادامه می دهد بدون اینکه منتظر پاسخ باشد. این بدان معنی است که فراخوانی های عملکرد سرور ممکن است به ترتیب مورد انتظار شما اجرا نشود. اگر همزمان دو تابع را فراخوانی کنید، راهی وجود ندارد که بدانید کدام تابع ابتدا اجرا می شود. نتیجه ممکن است هر بار که صفحه را بارگذاری می کنید متفاوت باشد. در این شرایط، کنترل کننده های موفقیت و کنترل کننده های شکست به کنترل جریان کد شما کمک می کنند.
google.script.run API اجازه می دهد تا 10 تماس همزمان با توابع سرور. اگر یازدهمین تماس را در حالی که 10 هنوز در حال اجرا هستند برقرار کنید، عملکرد سرور تا زمانی که یکی از 10 نقطه آزاد شود به تاخیر می افتد. در عمل، به ندرت باید در مورد این محدودیت فکر کنید، به خصوص که اکثر مرورگرها از قبل تعداد درخواست های همزمان را به همان سرور با تعداد کمتر از 10 محدود می کنند. برای مثال، در فایرفاکس، این محدودیت 6 است. اکثر مرورگرها به طور مشابه تاخیر دارند. درخواست های سرور اضافی تا زمانی که یکی از درخواست های موجود تکمیل شود.
پارامترها و مقادیر بازگشتی
می توانید یک تابع سرور را با پارامترهای مشتری فراخوانی کنید. به طور مشابه، یک تابع سرور می تواند مقداری را به عنوان یک پارامتر به یک کنترل کننده موفقیت ارسال کند.
پارامترهای قانونی و مقادیر بازگشتی، ابتدایی جاوا اسکریپت مانند Number ، Boolean ، String یا null و همچنین اشیاء و آرایه های جاوا اسکریپت هستند که از ابتدایی ها، اشیاء و آرایه ها تشکیل شده اند. یک عنصر form در صفحه نیز به عنوان یک پارامتر قانونی است، اما باید تنها پارامتر تابع باشد، و به عنوان مقدار بازگشتی قانونی نیست. اگر بخواهید یک عنصر Date ، Function ، DOM را علاوه بر form ، یا سایر انواع ممنوعه، از جمله انواع ممنوعه در داخل اشیا یا آرایه ها، ارسال کنید، درخواست ها با شکست مواجه می شوند. اشیایی که ارجاعات دایره ای ایجاد می کنند نیز شکست خواهند خورد و فیلدهای تعریف نشده در آرایه ها null می شوند.
توجه داشته باشید که یک شیء ارسال شده به سرور به یک کپی از اصل تبدیل می شود. اگر یک تابع سرور یک شی را دریافت کند و ویژگی های آن را تغییر دهد، ویژگی های روی کلاینت تحت تأثیر قرار نمی گیرند.
کنترل کننده های موفقیت
از آنجایی که کد سمت سرویس گیرنده بدون انتظار برای تکمیل تماس سرور، تا خط بعدی ادامه می‌یابد، withSuccessHandler(function) به شما امکان می‌دهد یک تابع تماس سمت کلاینت را مشخص کنید تا هنگام پاسخ سرور اجرا شود. اگر تابع سرور یک مقدار را برگرداند، API مقدار را به عنوان یک پارامتر به تابع جدید ارسال می کند.
مثال زیر یک هشدار مرورگر را هنگام پاسخ دادن سرور نشان می دهد. توجه داشته باشید که این نمونه کد نیاز به مجوز دارد زیرا عملکرد سمت سرور به حساب Gmail شما دسترسی دارد. ساده ترین راه برای مجوز دادن به اسکریپت این است که قبل از بارگذاری صفحه، تابع getUnreadEmails() را به صورت دستی از ویرایشگر اسکریپت اجرا کنید. متناوباً، وقتی برنامه وب را اجرا می‌کنید ، می‌توانید آن را به‌عنوان «کاربر در حال دسترسی به برنامه وب» اجرا کنید، در این صورت هنگام بارگیری برنامه از شما درخواست مجوز می‌شود.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }
function getUnreadEmails() { return GmailApp.getInboxUnreadCount(); }
Index.html
فرم ها
اگر یک تابع سرور را با عنصر form به عنوان پارامتر فراخوانی کنید، فرم به یک شی واحد با نام فیلدها به عنوان کلید و مقادیر فیلد به عنوان مقادیر تبدیل می شود. همه مقادیر به رشته تبدیل می شوند، به جز محتویات فیلدهای ورودی فایل، که تبدیل به اشیاء Blob می شوند.
این مثال یک فرم، از جمله فیلد ورودی فایل را بدون بارگیری مجدد صفحه پردازش می کند. فایل را در Google Drive آپلود می کند و سپس URL مربوط به فایل را در صفحه سمت سرویس گیرنده چاپ می کند. در داخل onsubmit handler، کلمه کلیدی this به خود فرم اشاره دارد. توجه داشته باشید که با بارگیری همه فرم‌ها در صفحه، اقدام پیش‌فرض ارسال توسط preventFormSubmit غیرفعال شده است. این امر از هدایت صفحه به یک URL نادرست در صورت استثنا جلوگیری می کند.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }
function processForm(formObject) { var formBlob = formObject.myFile; var driveFile = DriveApp.createFile(formBlob); return driveFile.getUrl(); }