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

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

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

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

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

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

عندما يزور مستخدم تطبيقًا أو يرسل برنامج طلب 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
}

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

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

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

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

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

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

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

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

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

لاختبار ميزة OAuth الدقيق على تطبيق الويب، تأكَّد من أنّ مشروعك لا يتضمّن بعض أذونات الوصول. لإبطال أي عمليات تفويض حالية، استخدِم ScriptApp.invalidateAuth. بالنسبة إلى أي تطبيقات ويب تم نشرها وتشغيلها باسم المستخدم النشط، عدِّل حقل JSON الخاص بالسمة executeAs في ملف البيان إلى USER_DEPLOYING.

الأذونات

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

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

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

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

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

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

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

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

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

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

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

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

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