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

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

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

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

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

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

عندما يزور مستخدم تطبيقًا أو يرسل أحد البرامج طلب HTTP GET إلى التطبيق، تشغِّل لغة برمجة التطبيقات الدالة 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.

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

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

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

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

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

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

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

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

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