برنامه های وب

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

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

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

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

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

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

وقتی کاربری از یک برنامه بازدید می‌کند یا برنامه‌ای یک درخواست HTTP GET به برنامه ارسال می‌کند، Google Apps Script تابع doGet را اجرا می‌کند. وقتی برنامه‌ای یک درخواست HTTP POST به برنامه ارسال می‌کند، Apps Script به جای آن doPost اجرا می‌کند. در هر دو مورد، آرگومان 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 خروجی زیر را برمی‌گرداند:

{
  "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. روی استقرار کلیک کنید.

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

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

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

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

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

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

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

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

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

مجوزها

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

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

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

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

برنامه وب خود را در سایت‌های گوگل جاسازی کنید {:#embed-web-app}

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

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

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

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

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

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

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

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

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

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

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