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

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

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

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

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

يحتوي على دالة doGet أو doPost.
تعرض الدالة كائن خدمة HTML HtmlOutput أو كائن خدمة المحتوى TextOutput.

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

عندما يزور مستخدم تطبيقًا أو يرسل برنامج إلى التطبيق طلب HTTP GET، تنفِّذ برمجة تطبيقات Google الدالة doGet. عندما يرسل برنامج طلب HTTP POST إلى التطبيق، ينفّذ برمجة تطبيقات 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 مع رسالة الخطأ "عذرًا، الملف الذي طلبته غير متوفر". إذا أمكن، عدِّل النص البرمجي لاستخدام أسماء مَعلمات مختلفة.

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

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

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

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

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

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

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

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

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

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

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

الأذونات

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

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

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

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

تضمين تطبيق الويب في "مواقع Google" {:#embed-web-app}

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

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

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

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

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

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

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

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

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

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

تطبيقات الويب تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.