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

1. مقدّمة حول برمجة تطبيقات Google

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

ما ستتعرَّف عليه

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

المتطلبات

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

2. استطلاع

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

القراءة فقط اقرأها وأكمِل التمارين

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

حديث متوسط بارع

3- نظرة عامة

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

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

لنبدأ

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

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

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

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

إذا كنت مبتدئًا في استخدام 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 جديد، حان الوقت لتعديل النص البرمجي المرتبط. اتّبِع هذه الإرشادات:

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

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

في علامة تبويب المتصفح الجديدة، يعرض محرِّر الرموز النص البرمجي التلقائي Contain-bound لورقة البيانات. يتم إنشاء دالة تلقائية باسم 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. لإعادة تسمية مشروع "برمجة تطبيقات Google"، انقر على مشروع بلا عنوان، وأدخِل عنوانًا لمشروعك، ثم انقر على إعادة تسمية.

مراجعة الرمز

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

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

/** @OnlyCurrentDoc */

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

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

function sendMap() {

يستدعي السطر التالي Data Service (خدمة جدول البيانات) التي يمكن الوصول إليها من "برمجة تطبيقات 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() من قائمة الدوال وانقر على تشغيل.

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

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

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

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

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

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

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

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

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

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

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

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

الوثائق

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

الفيديوهات

• نص عفوي تمامًا
• معرض مطوّري برامج Google Workspace

الأخبار و التحديثات

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

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

مبتدئ

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

مزايا متوسطة

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

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

• إنشاء "العروض التقديمية من Google" من Markdown HTML باستخدام واجهة برمجة تطبيقات "العروض التقديمية من Google"