تمرين عملي على النص البرمجي لتطبيقات Google: الوصول إلى جداول بيانات Google والخرائط وGmail في 4 أسطر من الرمز!

1. مقدمة عن برمجة تطبيقات Google

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

أهداف الدورة التعليمية

• كيفية استخدام برمجة تطبيقات Google مع خدمات Google المختلفة، مثل "جداول بيانات Google" و"خرائط Google" وGmail
• تطوير الرموز البرمجية باستخدام أداة التعديل داخل المتصفّح في "برمجة تطبيقات Google"

المتطلبات

• متصفّح ويب متصل بالإنترنت
• حساب Google (قد تتطلّب حسابات Google Workspace موافقة المشرف)
• معرفة أساسية بـ جداول بيانات Google
• إمكانية قراءة ترميز A1 في "جداول بيانات Google"

2. استطلاع

كيف ستستخدم هذا الدرس التطبيقي حول الترميز/الدليل التوجيهي/التعليمي؟

قراءة المحتوى فقط قراءة المحتوى وإكمال التمارين

ما هو تقييمك لتجربتك مع أدوات المطوّرين وواجهات برمجة التطبيقات في Google Workspace؟

مبتدئ متوسط متقدّم

3- نظرة عامة

بعد أن عرفت موضوع هذا الدرس العملي، ما الذي ستفعله بالضبط؟

1. تعرَّف على بعض المعلومات عن برمجة تطبيقات المستندة إلى JavaScript.
2. أنشئ جدول بيانات في "جداول بيانات Google".
3. أدخِل عنوان الشارع في الخلية العلوية اليمنى من جدول البيانات (A1).
4. تعرَّف على كيفية فتح أداة تعديل النصوص البرمجية لبرمجة تطبيقات لأي مستند.
5. تعديل رمز برمجة تطبيقات وحفظه وتشغيله
6. استخدِم Gmail لعرض النتيجة.

لنبدأ

ما هي برمجة تطبيقات Google؟

برمجة تطبيقات Google هي منصة تطوير تسهّل سرعة وسهولة إنشاء نصوص برمجية وتطبيقات صغيرة تتكامل مع Google Workspace. باستخدام "برمجة تطبيقات Google"، يمكنك إجراء ما يلي:

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

NOTE: لا يتناول هذا الدرس التطبيقي حول الترميز كيفية كتابة رمز JavaScript. هدفنا هو أن نساعدك في التعرّف على بيئة تطوير برمجة تطبيقات والاطّلاع على أنواع التطبيقات التي يمكنك إنشاؤها باستخدامها.

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

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

4. إنشاء جدول بيانات Google وإدخال عنوان شارع

في جدول بيانات Google جديد، أدخِل عنوان شارع صالحًا باتّباع التعليمات التالية:

1. أنشئ جدول بيانات Google باستخدام رابط الاختصار هذا (sheets.google.com/create). بدلاً من ذلك، انتقِل إلى Google Drive (drive.google.com) وانقر على جديد > جداول بيانات Google > جدول بيانات فارغ.

2. في جدول البيانات الفارغ، انتقِل إلى الخلية الأولى في أعلى يمين الصفحة (A1). ستظهر في العمود A والصف 1. إذا كنت بحاجة إلى إعادة التعرّف على هذا النظام، يمكنك الاطّلاع على وصف نظام A1.
3. أدخِل عنوان شارع صالحًا في الخلية. اختَر عنوانًا في أي مكان في العالم مع تحديد الموقع الجغرافي بدقة باستخدام عنوان شارع أو رمز بريدي أو مزيج من المدينة والولاية/المقاطعة. في ما يلي مثال على عنوان في مدينة نيويورك:

هذا كل ما عليك فعله في ورقة البيانات. هيا نفتح المحرِّر ونكتب بعض التعليمات البرمجية.

5- تعديل رمز برمجة تطبيقات Google

بعد إنشاء "جدول بيانات Google" جديد، حان الوقت لتعديل النص البرمجي المرتبط به. اتّبِع هذه الإرشادات:

فتح أداة تعديل النصوص البرمجية

في شريط القوائم، اختَر الإضافات > برمجة التطبيقات لفتح أداة تعديل الرموز في المتصفّح لخدمة "برمجة التطبيقات".

في علامة تبويب متصفّح جديدة، يعرض محرّر الرموز البرمجية النص البرمجي التلقائي المرتبط بالحاوية لورقة البيانات. يتم تلقائيًا إنشاء دالة تلقائية باسم myFunction() ويتم وضع المؤشر داخل الدالة حتى تتمكّن من البدء.

إرسال خريطة Google للعنوان عبر البريد الإلكتروني

رمز "النموذج" الذي يتم تقديمه لك فارغ، لذا دعنا نستبدله بتطبيقنا.

1. في أداة تعديل النصوص البرمجية، استبدِل كتلة الرمز myFunction() التلقائية بمجموعة الرموز التالية:

/** @OnlyCurrentDoc */
function sendMap() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var address = sheet.getRange('A1').getValue();
  var map = Maps.newStaticMap().addMarker(address);
  GmailApp.sendEmail('YOUR_EMAIL_ADDR', 'Map', 'See below.', {attachments:[map]});
}

2. استبدِل عنوان البريد الإلكتروني النائب ('YOUR_EMAIL_ADDR') بعنوان صالح. على سبيل المثال، [e-mail].
3. لحفظ النص، انقر على "حفظ" .
4. لإعادة تسمية مشروع برمجة تطبيقات، انقر على مشروع بلا عنوان، وأدخِل عنوانًا لمشروعك، ثم انقر على إعادة التسمية.

مراجعة الرمز البرمجي

لنراجع أسطر دالة sendMap() الأربعة التي تشكّل التطبيق بأكمله. من المثير للاهتمام أنّ الرمز يشير إلى 3 منتجات مختلفة من Google.

السطر الأول هو تعليق توضيحي يؤثر في التفويض:

/** @OnlyCurrentDoc */

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

يستخدم الرمز تعريف دالة JavaScript عادية لـ sendMap():

function sendMap() {

يستدعي السطر التالي خدمة جداول بيانات Google التي يمكن الوصول إليها من "برمجة تطبيقات Google" من خلال الكائن SpreadsheetApp. يتم تعيين ورقة البيانات التي تم إرجاعها إلى متغيّر يحمل الاسم نفسه. يحصل الإجراء getActiveSheet() على مرجع لكائن ورقة البيانات الحالية ويخزّنه في المتغير sheet.

  var sheet = SpreadsheetApp.getActiveSheet();

باستخدام العنصر sheet، نشير إلى نطاق الخلايا (لخلية واحدة) في تنسيق A1 باستخدام getRange(). "النطاق" هو مجموعة من الخلايا، بما في ذلك خلية واحدة مثل الخلية A1 (التي أدخلنا العنوان فيها). لاسترداد ما هو داخل النطاق، تعرض الطريقة getValue() قيمة الخلية أعلى اليمين في النطاق وتعيّن القيمة للمتغيّر address. يمكنك أيضًا محاولة إضافة المزيد من العناوين والقراءة من خلايا مختلفة.

  var address = sheet.getRange('A1').getValue();

يربط سطر الرمز البرمجي الثالث بخدمة "خرائط Google" باستخدام العنصر Maps. ينشئ newStaticMap() عنصر إنشاء الخريطة الثابت، ويضيف الإجراء addMarker() "دبوسًا" إلى الخريطة باستخدام العنوان في ورقة البيانات.

  var map = Maps.newStaticMap().addMarker(address);

أخيرًا، تستدعي خدمة Gmail من خلال العنصر MailApp الطريقة sendEmail() لإرسال الرسالة الإلكترونية التي تتضمّن النص "يُرجى الاطّلاع أدناه" وصورة الخريطة كمرفق.

  GmailApp.sendEmail('[e-mail]', 'Map', 'See below.', {attachments:[map]});
}

6. تشغيل تطبيق "جداول بيانات Google" و"خرائط Google" وGmail

بعد تسمية الدالة وحفظها، حان الوقت لتشغيلها. في أعلى المحرّر، تأكَّد من اختيار sendMap() من قائمة الدوال، ثم انقر على تشغيل.

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

انقر على مراجعة الأذونات للمتابعة.

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

1. في مربّع حوار التطبيق الذي لم يتم التحقّق منه، انقر على إعدادات متقدّمة.
2. انقر على الانتقال إلى اسم مشروعك (غير آمن).
3. انقر على سماح.

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

بعد ذلك، ستظهر نافذة حوار OAuth2 تطلب الإذن بالوصول إلى ورقة البيانات وإرسال رسائل إلكترونية نيابةً عنك:

بعد منح الإذن، يتم تنفيذ النص البرمجي حتى اكتماله.

تحقَّق من حساب البريد الإلكتروني الذي أرسلت منه رسالتك، وستجد رسالة إلكترونية بعنوان "خريطة" ورسالة تبدو على النحو التالي:

عند فتح المرفق في الرسالة الإلكترونية، من المفترض أن تظهر لك "خرائط Google" مع دبوس على العنوان الذي أدخلته في ورقة البيانات:

من خلال أربعة أسطر فقط من الرمز البرمجي، تمكّنت من الوصول إلى 3 منتجات مختلفة من Google بطريقة مفيدة.

7. مراجع إضافية

يتوفّر الرمز البرمجي المعروض في هذا الدرس التطبيقي حول الترميز أيضًا في مستودع GitHub على الرابط github.com/googleworkspace/apps-script-intro-codelab. في ما يلي المزيد من المراجع لمساعدتك في التعرّف بشكلٍ أعمق على المواد التي تم تناولها في هذا الدرس التطبيقي حول الترميز واستكشاف طرق أخرى للوصول إلى أدوات المطوّرين من Google آليًا.

الوثائق

• موقع مستندات برمجة تطبيقات Google
• برمجة تطبيقات Google‏: خدمة Gmail
• برمجة التطبيقات: خدمة جداول البيانات
• برمجة التطبيقات: خدمة "خرائط Google"

الفيديوهات

• Totally Unscripted
• معرض مطوّري Google Workspace

الأخبار والإشعارات

• مدوّنة "مطوّرو Google Workspace"
• ‫Twitter: مطوّرو Google Workspace (@workspacedevs)

دروس تطبيقية أخرى حول الترميز

مبتدئ

• [جداول بيانات Google] أساسيات "برمجة تطبيقات Google" مع "جداول بيانات Google"
• [واجهات REST API] استخدام Google Workspace وواجهات Google API للوصول إلى الملفات والمجلدات في Google Drive

متوسّط

• [برمجة تطبيقات] إضافات Google Workspace في Gmail
• [برمجة تطبيقات] روبوتات مخصّصة في Hangouts Chat
• [واجهات REST API] استخدام "جداول بيانات Google" كأداة لإعداد التقارير في تطبيقك
• [واجهات REST API] إنشاء عروض تقديمية على "العروض التقديمية من Google" باستخدام BigQuery API

التطبيقات المرجعية

• إنشاء "عروض تقديمية من Google" من Markdown وHTML باستخدام Slides API