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

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

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

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

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

• يحتوي على دالة doGet(e) أو doPost(e).
• تُعرِض الدالة عنصر خدمة HTML HtmlOutput أو عنصر خدمة محتوى TextOutput.

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

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

تحذير: أسماء المَعلمات التالية محجوزة من قِبل النظام ويجب عدم استخدامها في مَعلمات عناوين URL أو في أجسام POST:

• c
• sid

قد يؤدي استخدام هذه المَعلمات إلى ظهور استجابة HTTP 405 مع رسالة الخطأ: "نعتذر، الملف الذي طلبته غير متوفّر". إذا أمكن، عدِّل النص البرمجي لاستخدام أسماء مَعلمات مختلفة.

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

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

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

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

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

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

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

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

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

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

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

الأذونات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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