تطبيقات الويب

إذا أنشأت واجهة مستخدم لنص برمجي، يمكنك نشر النص البرمجي كتطبيق ويب. على سبيل المثال، من الأفضل تقديم نص برمجي يتيح للمستخدمين تحديد مواعيد مع أعضاء فريق الدعم كتطبيق ويب حتى يتمكّن المستخدمون من الوصول إليه مباشرةً من متصفّحيهم.

يمكن تحويل كلٍّ من النصوص البرمجية المستقلة والنصوص البرمجية المرتبطة بالتطبيقات إلى تطبيقات ويب، شرط أن تستوفي المتطلبات الواردة أدناه.

متطلبات تطبيقات الويب

يمكن نشر نص برمجي كتطبيق ويب إذا كان يستوفي المتطلبات التالية:

مَعلمات الطلب

عندما يزور مستخدم تطبيقًا أو يرسل برنامج طلب HTTP GET إلى التطبيق، تُنفِّذ Apps Script الدالة doGet(e). عندما يُرسِل برنامج طلب HTTP POST إلى التطبيق، ستعمل برمجة التطبيقات على تنفيذ 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
}

نشر نص برمجي كتطبيق ويب

لنشر نص برمجي كتطبيق ويب، اتّبِع الخطوات التالية:

  1. في أعلى يسار مشروع النصوص البرمجية، انقر على نشر > نشر جديد.
  2. بجانب "اختيار النوع"، انقر على تفعيل أنواع عمليات النشر > تطبيق الويب.
  3. أدخِل المعلومات عن تطبيق الويب في الحقول ضمن "إعدادات النشر".
  4. انقر على نشر.

يمكنك مشاركة عنوان URL لتطبيق الويب مع المستخدمين الذين تريد أن يستخدموا تطبيقك، شرط أن تكون قد منحت هؤلاء المستخدمين الإذن بالوصول إلى التطبيق.

اختبار عملية نشر تطبيق ويب

لاختبار النص البرمجي كتطبيق ويب، اتّبِع الخطوات التالية:

  1. في أعلى يسار مشروع النصوص البرمجية، انقر على نشر > اختبار عمليات النشر.
  2. بجانب "اختيار النوع"، انقر على تفعيل أنواع عمليات النشر > تطبيق ويب.
  3. ضمن عنوان URL لتطبيق الويب، انقر على نسخ.

  4. الصِق عنوان URL في المتصفّح واختَبر تطبيق الويب.

    ينتهي عنوان URL هذا بـ /dev ولا يمكن الوصول إليه إلا من قِبل المستخدمين الذين لديهم إذن وصول تعديل إلى النص البرمجي. يشغِّل هذا المثيل من التطبيق دائمًا رمز الإصدار الذي تم حفظه مؤخرًا، وهو مخصّص للاختبار فقط أثناء التطوير.

الأذونات

تختلف أذونات تطبيق الويب حسب الطريقة التي تختارها لتنفيذ التطبيق:

  • تنفيذ التطبيق بالنيابة عني: في هذه الحالة، يتم تنفيذ النص البرمجي دائمًا بصفتك مالك النص البرمجي، بغض النظر عمن يصل إلى تطبيق الويب.
  • تنفيذ التطبيق بصفتك المستخدم الذي يصل إلى التطبيق المتوافق مع الويب: في هذه الحالة، يتم تنفيذ النص البرمجي باستخدام هوية المستخدم النشط الذي يستخدم التطبيق المتوافق مع الويب. يؤدي أسلوب إذن الولوج هذا إلى عرض التطبيق المتوافق مع الويب لعنوان البريد الإلكتروني الخاص بمالك النص البرمجي عندما يمنح المستخدم الإذن بالوصول.

تضمين تطبيق الويب في "مواقع Google"

لتضمين تطبيق ويب في "مواقع Google"، يجب أولاً نشره. ستحتاج أيضًا إلى عنوان URL المنشور من مربّع حوار Deploy.

لتضمين تطبيق ويب في صفحة مواقع Google، اتّبِع الخطوات التالية:

  1. افتح صفحة "مواقع Google" التي تريد إضافة تطبيق الويب إليها.
  2. اختَر إدراج > تضمين عنوان URL.
  3. الصِق عنوان URL لتطبيق الويب، ثم انقر على إضافة.

يظهر تطبيق الويب في إطار في معاينة الصفحة. عند نشر الصفحة، قد يحتاج زوّار موقعك الإلكتروني إلى تفويض تطبيق الويب قبل أن يتم تنفيذه بشكلٍ طبيعي. تعرِض تطبيقات الويب غير المصرَّح بها طلبات تفويض للمستخدم.

تطبيقات الويب وسجلّ المتصفّح

قد يكون من المفيد أن يحاكي تطبيق ويب Apps Script تطبيقًا مكوّنًا من عدة صفحات، أو تطبيقًا يتضمّن واجهة مستخدم ديناميكية يتم التحكّم فيها من خلال مَعلمات عناوين URL. لتنفيذ ذلك بشكلٍ جيد، يمكنك تحديد عنصر حالة لتمثيل واجهة مستخدم التطبيق أو صفحته، ودفع الحالة إلى سجلّ المتصفّح أثناء تنقّل المستخدِم في تطبيقك. يمكنك أيضًا الاستماع إلى أحداث السجلّ لكي يعرض تطبيق الويب واجهة المستخدم الصحيحة عندما تنقّل المستخدِم ذهابًا وإيابًا باستخدام أزرار المتصفّح. من خلال طلب معلمات عنوان URL في وقت التحميل، يمكنك جعل تطبيقك ينشئ واجهة المستخدم ديناميكيًا استنادًا إلى هذه المَعلمات، ما يسمح للمستخدم ب بدء التطبيق في حالة معيّنة.

توفّر Apps Script واجهات برمجة تطبيقات JavaScript غير المتزامنة من جهة العميل للمساعدة في إنشاء تطبيقات ويب مرتبطة بسجلّ المتصفّح:

  • google.script.history يوفّر طرقًا للسماح بالاستجابة الديناميكية لتغييرات سجلّ المتصفّح. ويشمل ذلك: دفع الحالات (كائنات بسيطة يمكنك تحديدها) إلى سجلّ التصفّح، واستبدال الحالة العلوية في حزمة السجلّ، وضبط وظيفة callback لمستقبل الرسائل بهدف الاستجابة لتغييرات السجلّ.

  • يوفّر google.script.url الوسائل لاسترداد مَعلمات عنوان URL للصفحة الحالية وجزء عنوان URL، في حال توفّرها.

لا تتوفّر واجهات برمجة التطبيقات هذه للسجلّ إلّا لتطبيقات الويب. ولا يمكن استخدامها في الأشرطة الجانبية أو مربّعات الحوار أو الإضافات. ولا يُنصح أيضًا باستخدام هذه الوظيفة في تطبيقات الويب المضمّنة في "مواقع Google".