برنامه های وب

اگر برای یک اسکریپت رابط کاربری می‌سازید، می‌توانید اسکریپت را به عنوان یک برنامه وب منتشر کنید. به عنوان مثال، اسکریپتی که به کاربران امکان می‌دهد قرار ملاقات با اعضای تیم پشتیبانی را برنامه‌ریزی کنند، بهتر است به عنوان یک برنامه وب ارائه شود تا کاربران بتوانند مستقیماً از مرورگرهای خود به آن دسترسی داشته باشند.

هم اسکریپت‌های مستقل و هم اسکریپت‌های متصل به برنامه‌های Google Workspace می‌توانند به برنامه‌های وب تبدیل شوند، البته تا زمانی که الزامات زیر را برآورده کنند.

الزامات برنامه‌های وب

یک اسکریپت می‌تواند به عنوان یک برنامه وب منتشر شود اگر این شرایط را برآورده کند:

• این شامل یک تابع doGet(e) یا doPost(e) است.
• این تابع یک شیء HtmlOutput از سرویس HTML یا یک شیء TextOutput از سرویس Content را برمی‌گرداند.

پارامترهای درخواست

وقتی کاربری از یک برنامه بازدید می‌کند یا برنامه‌ای یک درخواست HTTP GET به برنامه ارسال می‌کند، Apps Script تابع doGet(e) را اجرا می‌کند. وقتی برنامه‌ای یک درخواست HTTP POST به برنامه ارسال می‌کند، Apps Script به جای آن doPost(e) اجرا می‌کند. در هر دو مورد، آرگومان e نشان‌دهنده یک پارامتر رویداد است که می‌تواند حاوی اطلاعاتی در مورد هر پارامتر درخواست باشد. ساختار شیء رویداد در جدول زیر نشان داده شده است:

فیلدها
e.queryString	مقدار بخش رشته پرس‌وجوی URL، یا اگر هیچ رشته پرس‌وجوی مشخص نشده باشد null name=alice&n=1&n=2
e.parameter	یک شیء از جفت‌های کلید/مقدار که با پارامترهای درخواست مطابقت دارند. برای پارامترهایی که چندین مقدار دارند، فقط مقدار اول برگردانده می‌شود. {"name": "alice", "n": "1"}
e.parameters	یک شیء مشابه e.parameter ، اما با آرایه‌ای از مقادیر برای هر کلید {"name": ["alice"], "n": ["1", "2"]}
e.pathInfo	مسیر URL بعد از /exec یا /dev . برای مثال، اگر مسیر URL به /exec/hello ختم شود، اطلاعات مسیر hello است.
e.contextPath	استفاده نمی‌شود، همیشه رشته خالی است.
e.contentLength	طول بدنه درخواست برای درخواست‌های POST یا -1 برای درخواست‌های GET 332
e.postData.length	همانند e.contentLength 332
e.postData.type	نوع MIME بدنه POST text/csv
e.postData.contents	متن محتوای بدنه POST Alice,21
e.postData.name	همیشه مقدار "postData" postData

برای مثال، می‌توانید پارامترهایی مانند username و age را به صورت زیر به یک URL ارسال کنید:

https://script.google.com/.../exec?username=jsmith&age=21

سپس، می‌توانید پارامترها را به صورت زیر نمایش دهید:

function doGet(e) {
  var params = JSON.stringify(e);
  return ContentService.createTextOutput(params).setMimeType(ContentService.MimeType.JSON);
}

در مثال بالا، doGet(e) خروجی زیر را برمی‌گرداند:

{
  "queryString": "username=jsmith&age=21",
  "parameter": {
    "username": "jsmith",
    "age": "21"
  },
  "contextPath": "",
  "parameters": {
    "username": [
      "jsmith"
    ],
    "age": [
      "21"
    ]
  },
  "contentLength": -1
}

هشدار: نام پارامترهای زیر توسط سیستم رزرو شده‌اند و نباید در پارامترهای URL یا بدنه‌های POST استفاده شوند:

• c
• sid

استفاده از این پارامترها ممکن است منجر به پاسخ HTTP 405 با پیام خطای "متاسفیم، فایلی که درخواست کرده‌اید وجود ندارد" شود. در صورت امکان، اسکریپت خود را به‌روزرسانی کنید تا از نام پارامترهای متفاوتی استفاده کند.

استقرار یک اسکریپت به عنوان یک برنامه وب

برای پیاده‌سازی یک اسکریپت به عنوان یک برنامه وب، مراحل زیر را دنبال کنید:

1. در سمت راست بالای پروژه اسکریپت، روی Deploy > New deployment کلیک کنید.
2. در کنار «انتخاب نوع»، روی «فعال کردن انواع استقرار» > «برنامه وب» کلیک کنید.
3. اطلاعات مربوط به برنامه وب خود را در فیلدهای زیر «پیکربندی استقرار» وارد کنید.
4. روی استقرار کلیک کنید.

شما می‌توانید آدرس اینترنتی (URL) برنامه وب را با کسانی که مایل به استفاده از برنامه خود هستید، به اشتراک بگذارید، البته به شرطی که به آنها دسترسی داده باشید.

توجه: برنامه‌های وب مستقر در یک دامنه، در صورت تغییر مالکیت آنها به یک درایو مشترک یا حساب کاربری در دامنه دیگر، از کار می‌افتند. این مشکل را می‌توان با درخواست از مالک یا همکار جدید برای استقرار مجدد برنامه وب در دامنه جدید اصلاح کرد. از طرف دیگر، اگر برنامه وب به دامنه اصلی خود بازگردانده شود، برنامه وب بدون نیاز به استقرار مجدد، دوباره برای آن دامنه شروع به کار خواهد کرد.

آزمایش استقرار یک برنامه وب

برای آزمایش اسکریپت خود به عنوان یک برنامه وب، مراحل زیر را دنبال کنید:

1. در سمت راست بالای پروژه اسکریپت، روی Deploy > Test deployments کلیک کنید.
2. در کنار «انتخاب نوع»، روی «فعال کردن انواع استقرار » > «برنامه وب» کلیک کنید.
3. در زیر نشانی اینترنتی برنامه وب، روی کپی کلیک کنید.

4. آدرس اینترنتی (URL) را در مرورگر خود وارد کنید و برنامه وب خود را آزمایش کنید.

   این آدرس اینترنتی (URL) به /dev ختم می‌شود و فقط کاربرانی که دسترسی ویرایش اسکریپت را دارند می‌توانند به آن دسترسی داشته باشند. این نمونه از برنامه همیشه آخرین کد ذخیره شده را اجرا می‌کند و فقط برای آزمایش در طول توسعه در نظر گرفته شده است.

برای آزمایش ویژگی OAuth جزئی در برنامه وب، مطمئن شوید که پروژه شما از قبل هیچ مجوزی ندارد. برای باطل کردن هرگونه مجوز موجود، از ScriptApp.invalidateAuth استفاده کنید.

هشدار: هنگام استقرار برنامه‌های وب برای اجرا به عنوان توسعه‌دهنده، باید هنگام مدیریت توکن‌های OAuth که از طریق ScriptApp.getOAuthToken() به دست می‌آیند، نهایت دقت را به خرج دهید. این توکن‌ها می‌توانند به برنامه‌های دیگر اجازه دسترسی به داده‌های شما را بدهند - هرگز آنها را به کلاینت منتقل نکنید.

مجوزها

مجوزهای یک برنامه وب بسته به نحوه اجرای برنامه متفاوت است:

• اجرای برنامه توسط من — در این حالت، اسکریپت همیشه توسط شما، مالک اسکریپت، اجرا می‌شود، صرف نظر از اینکه چه کسی به برنامه وب دسترسی دارد.
• اجرای برنامه به عنوان کاربری که به برنامه وب دسترسی دارد — در این حالت، اسکریپت تحت هویت کاربر فعالی که از برنامه وب استفاده می‌کند اجرا می‌شود. این رویکرد مجوز باعث می‌شود که برنامه وب هنگام تأیید دسترسی توسط کاربر، ایمیل مالک اسکریپت را نشان دهد.

هشدار: برای جلوگیری از سوءاستفاده، Apps Script محدودیت‌هایی را بر میزان مجاز بودن یک برنامه وب که به عنوان کاربر اجرا می‌شود توسط کاربران جدید اعمال می‌کند. این محدودیت‌ها، از جمله عوامل دیگر، به این بستگی دارد که آیا حساب کاربری منتشرکننده بخشی از دامنه Google Workspace است یا خیر.

توجه: می‌توانید با استفاده از درایو مشترک ، در برنامه‌های وب همکاری کنید. وقتی یک برنامه وب در یک درایو مشترک مستقر می‌شود، انتخاب «اجرا به عنوان شما» باعث می‌شود برنامه وب تحت اختیار کاربری که آن را مستقر کرده است اجرا شود (زیرا هیچ مالک اسکریپتی وجود ندارد).

برنامه وب خود را در سایت‌های گوگل جاسازی کنید

هشدار: برنامه‌های وب جاسازی‌شده هنوز برای جلوگیری از استفاده مخرب، مشمول مجوزهای دسترسی هستند. اگر به نظر نمی‌رسد برنامه وب جاسازی‌شده شما کار کند، بررسی کنید که آیا مجوزهای تعیین‌شده توسط مالک برنامه وب و مدیر دامنه اجازه استفاده از آن را می‌دهند یا خیر.

برای جاسازی یک برنامه وب در Google Sites، ابتدا باید آن را مستقر کنید . همچنین به آدرس اینترنتی مستقر شده (Deployed URL) از کادر محاوره‌ای Deploy نیاز دارید.

برای جاسازی یک برنامه وب در صفحه Sites ، این مراحل را دنبال کنید:

1. صفحه سایت‌هایی را که می‌خواهید برنامه وب را به آن اضافه کنید، باز کنید.
2. گزینه درج > جاسازی نشانی وب را انتخاب کنید.
3. آدرس اینترنتی برنامه وب را وارد کنید و سپس روی افزودن کلیک کنید.

برنامه وب در یک قاب در پیش‌نمایش صفحه ظاهر می‌شود. وقتی صفحه را منتشر می‌کنید، بینندگان سایت شما ممکن است قبل از اجرای عادی برنامه وب، نیاز به تأیید آن داشته باشند. برنامه‌های وب غیرمجاز، درخواست‌های تأیید را به کاربر نشان می‌دهند.

برنامه‌های وب و تاریخچه مرورگر

ممکن است مطلوب باشد که یک برنامه وب Apps Script یک برنامه چند صفحه‌ای یا یک برنامه با رابط کاربری پویا که از طریق پارامترهای URL کنترل می‌شود را شبیه‌سازی کند. برای انجام خوب این کار، می‌توانید یک شیء وضعیت (state object) برای نمایش رابط کاربری یا صفحه برنامه تعریف کنید و وضعیت را هنگام پیمایش کاربر در برنامه، در تاریخچه مرورگر وارد کنید. همچنین می‌توانید به رویدادهای تاریخچه گوش دهید تا برنامه وب شما هنگام پیمایش کاربر با دکمه‌های مرورگر، رابط کاربری صحیح را نمایش دهد. با پرس و جو از پارامترهای URL در زمان بارگذاری، می‌توانید رابط کاربری برنامه خود را به صورت پویا بر اساس آن پارامترها بسازید و به کاربر اجازه دهید برنامه را در یک حالت خاص شروع کند.

Apps Script دو ​​API جاوا اسکریپت ناهمزمان سمت کلاینت ارائه می‌دهد تا به ایجاد برنامه‌های وب که به تاریخچه مرورگر مرتبط هستند، کمک کند:

• google.script.history متدهایی را برای پاسخ پویا به تغییرات تاریخچه مرورگر ارائه می‌دهد. این شامل موارد زیر است: قرار دادن حالت‌ها (اشیاء ساده‌ای که می‌توانید تعریف کنید) در تاریخچه مرورگر، جایگزینی حالت برتر در پشته تاریخچه، و تنظیم یک تابع فراخوانی شنونده برای پاسخ به تغییرات تاریخچه.

• google.script.url ابزاری برای بازیابی پارامترهای URL صفحه فعلی و قطعه URL، در صورت وجود، فراهم می‌کند.

این APIهای تاریخچه فقط برای برنامه‌های وب در دسترس هستند. آنها برای نوارهای کناری، دیالوگ‌ها یا افزونه‌ها پشتیبانی نمی‌شوند. این قابلیت همچنین برای استفاده در برنامه‌های وب تعبیه شده در Google Sites توصیه نمی‌شود.