تعزيز قدرات بريدك الوارد في Gmail باستخدام وظائف Google Cloud

1. مقدمة

يستخدم المليارات من الأنشطة التجارية والأفراد Gmail وخدمات G Suite الأخرى للتواصل ومعالجة البيانات. تقدّم Google واجهات برمجة تطبيقات G Suite لمساعدتك في الوصول إلى المعلومات في هذه الخدمات بشكل آلي، ويمكنك استخدام واجهات برمجة التطبيقات لبرمجة سير العمل اليومي بسهولة. وفي هذا التمرين، ستنشئ إضافة Gmail قوية تصنف تلقائيًا رسائل البريد الإلكتروني في الرسائل الواردة وتحفظ هذه الفئات في جدول بيانات Google. ستستخدم هذه الإضافة واجهات برمجة تطبيقات RESTful في G Suite ووظائف Google Cloud وخدمات Google Cloud Platform الأخرى.

ما الذي ستقوم ببنائه

في هذا التمرين، ستنشئ وتنشر بعض دوال Cloud المرتبطة بواجهات برمجة تطبيقات G Suite وخدمات Google Cloud Platform الأخرى. هذه الدوال:

  • السماح بالوصول الآمن إلى بياناتك في Gmail و"جداول بيانات Google"
  • استخراج الصور المرفقة بأي بريد وارد
  • تصنيف هذه الصور باستخدام Cloud Vision API
  • كتابة هذه الفئات وعنوان المُرسِل واسم المرفق في جدول بيانات Google

ما سوف تتعلمه

  • أساسيات واجهات برمجة تطبيقات RESTful في G Suite
  • أساسيات وظائف Google Cloud وخدمات Google Cloud Platform الأخرى
  • كيفية الوصول إلى Gmail آليًا باستخدام دوال Google Cloud

ما ستحتاجه

  • حساب Google لديه إذن بالوصول إلى Gmail و"جداول بيانات Google". إذا لم يكن لديك حساب، يمكنك إنشاء حساب هنا.
  • معرفة أساسية بلغة JavaScript/Node.js.

2. فلنبدأ بالخطوة الأهم

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

ستستخدم في هذا التمرين المعملي منتجات Google/خدماتها التالية:

  • وظائف Google Cloud
  • Google Cloud Pub/Sub
  • Google Cloud Vision API
  • خدمة تخزين البيانات في Google Cloud
  • Gmail API
  • Google Sheets API

وظائف Google Cloud

Google Cloud Functions هي منصة "الوظائف كخدمة بدون خادم" من Google التي تتيح لك تشغيل مقتطفات فردية من الرموز ("الدوال") بطريقة بسيطة وقابلة للتوسع.

لتفعيل Google Cloud Functions، انقر على قائمة الخطوط الثلاثة أعلى يمين الشاشة لفتح شريط التنقّل الجانبي الأيمن:

f457988e33594bb6.png

ابحث عن Cloud Functions في قائمة التنقّل، وانقر عليها. انقر على تفعيل واجهة برمجة التطبيقات لتفعيل "دوال Google Cloud" في مشروعك.

Google Cloud Pub/Sub

تُعدّ خدمة Google Cloud Pub/Sub أساسًا بسيطًا وقابلاً للتطور لبث البيانات وتقديمها. وفي هذا التمرين المعملي، تعمل هذه الأداة كجهة توصيل بين Gmail ووظائف Google Cloud.

لتفعيل خدمة Google Cloud Pub/Sub، افتح شريط التنقّل الجانبي الأيمن، وابحث عن الزر نشر/اشتراك، ثم انقر عليه. انقر على تفعيل واجهة برمجة التطبيقات لتفعيل خدمة Google Cloud Pub/Sub في مشروعك.

خدمة تخزين البيانات في Google Cloud

"مخزن البيانات في Google Cloud" هو قاعدة بيانات بدون خادم قابلة للتطوير والتوزيع.

لتفعيل خدمة "تخزين البيانات في Google Cloud"، ابحث عن مخزن البيانات في الشريط الجانبي للتنقل في الشريط الجانبي، وانقر عليه. انقر على تحديد وضع تخزين البيانات في الصفحة الجديدة.

98012c91fd4080d4.png

يمكنك استخدام أي موقع لقاعدة البيانات في هذا التمرين المعملي. انقر على إنشاء قاعدة بيانات لتفعيل خدمة "تخزين البيانات في Google Cloud". وقد يستغرق إكماله بضع دقائق.

رؤية Google Cloud

Google Cloud Vision API هي خدمة فعّالة لتعلُّم الآلة تستخدم نماذج مدرَّبة مسبقًا لاستخلاص الإحصاءات من صورك.

راجِع التعليمات أدناه للحصول على معلومات حول كيفية تفعيل Google Cloud Vision API.

تفعيل واجهة برمجة تطبيقات Gmail وGoogle Sheets API وGoogle Cloud Vision API

مرة أخرى، افتح شريط التنقل الجانبي الأيمن، وابحث عن واجهات برمجة التطبيقات الخدمات: انقر على المكتبة. في عمود البحث عن واجهات برمجة التطبيقات الخدمات، اكتب Gmail. في نتائج البحث، اختَر Gmail API وانقر على تفعيل.

ارجع إلى صفحة "مكتبة واجهة برمجة التطبيقات". ابحث عن Google Sheets API وفعِّلها.

كرر العملية. ابحث عن Cloud Vision API وفعِّلها.

فتح Google Cloud Shell

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

لفتح Google Cloud Shell، انقر على الزر تفعيل Cloud Shell في الشريط الأفقي الأزرق العلوي:

fd5c2925ca9cdfdd.png

ستظهر لوحة جديدة في أسفل الشاشة:

34f498402e910802.png

انقر على الزر تشغيل محرِّر الرموز لبدء محرِّر رموز Cloud Shell:

10f8631ef48bed22.png

سيتم فتح محرّر رموز Cloud Shell في نافذة جديدة.

تنزيل الرمز

نفِّذ الأمر أدناه في Cloud Shell لنسخ المشروع:

git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git

cd gcf-gmail-codelab

من المفترض أن يظهر لك مجلد جديد، "gcf-gmail-codelab"، في "محرِّر رموز Cloud Shell".

3- نظرة عامة على الهندسة المعمارية

في ما يلي سير عمل هذا التمرين المعملي:

79c5d3e43f674b33.png

  1. يُعِدّ المستخدم إشعارات Gmail الفورية: في كل مرة تصل فيها رسالة جديدة إلى البريد الوارد، سيرسل Gmail إشعارًا إلى خدمة Cloud Pub/Sub.
  2. تعمل خدمة Cloud Pub/Sub على إرسال إشعار الرسالة الجديدة إلى دوال Google Cloud.
  3. عند وصول إشعار الرسالة الجديدة، يتصل مثيل Cloud Functions بخدمة Gmail ويسترد الرسالة الجديدة.
  4. إذا كانت الرسالة تحتوي على صورة كمرفق، يستدعي مثيل Cloud Functions واجهة برمجة التطبيقات Cloud Vision API لتحليل المرفق.
  5. يعدِّل مثيل دوال السحابة الإلكترونية "جدول بيانات Google" من اختيارك، لتحديد المستخدم الذي يرسل الرسالة ومكان تنزيل المرفق.

4. السماح بالوصول إلى Gmail

قبل إعداد إحدى وظائف السحابة الإلكترونية لقراءة رسائلك الإلكترونية تلقائيًا، عليك تفويض وصولها إلى Gmail. يجب تسجيل عميل OAuth لدى Google وإنشاء معرِّف عميل مرتبط به.

تسجيل عميل OAuth

في قائمة التنقل اليمنى من Google Cloud Console، ابحث عن واجهات برمجة التطبيقات الخدمات: انقر على شاشة موافقة OAuth.

91b2a3bac30bb2c5.png

اكتب اسمًا في الحقل اسم التطبيق، مثل GCF + درس تطبيقي حول ترميز Gmail. اترك الإعدادات الأخرى كما هي، ومرِّر لأسفل الصفحة وانقر على حفظ.

إنشاء معرّف عميل مرتبط

انتقِل إلى علامة التبويب بيانات الاعتماد. انقر على إنشاء بيانات اعتماد واختَر معرِّف عميل OAuth. اختَر نوع تطبيق الويب وأدخِل اسمًا له (يمكنك استخدام الدرس التطبيقي حول ترميز GCF + Gmail هنا)، ثم انقر على إنشاء. اترك حقول "القيود" فارغة في الوقت الحالي.

اكتب معرِّف العميل وسر العميل المعروض في النافذة المنبثقة. يمكنك النقر على اسم العميل في الصفحة لعرض هذه القيم مرة أخرى:

1160d8027ea52d90.png

إجراء عملية التفويض

في نموذج الرمز البرمجي، تحدّد auth/index.js دالتَي السحابة الإلكترونية، auth_init وauth_callback، تعملان معًا لتنفيذ عملية التفويض، باستخدام معرِّف العميل وسر العميل الذي أنشأته للتو.

لفحص الرمز، افتح auth/index.js في "محرِّر رموز Cloud Shell".

تعرض عملية التفويض نوعين من الرموز المميزة: رموز الدخول والرموز المميزة لإعادة التحميل.

  • رموز الدخول هي إثباتات قصيرة الأجل للهوية تمنح أي شخص يمتلكها إمكانية الوصول المُفصَّل إلى بياناتك. تحفظها خدمة "auth_callback" في "مخزن البيانات في السحابة الإلكترونية".
  • تُستخدم رموز إعادة التحميل للحصول على رموز دخول جديدة، وعمرها أطول بكثير.

يتم عادةً تشفير هذه الرموز و/أو تخزينها بشكل منفصل عن رموز الدخول.

يمكنك تعديل auth/env_vars.yaml في "محرِّر رموز Cloud Shell". استبدل YOUR-GOOGLE-CLIENT-ID وYOUR-GOOGLE-CLIENT-SECRET بقيم خاصة بك. اطّلِع على الخطوة السابقة للحصول على مزيد من المعلومات. أبقِ قيمتَي YOUR-GOOGLE-CLIENT-CALLBACK-URL وYOUR-PUBSUB-TOPIC بدون تغيير في الوقت الحالي.

a2b4853c39a78bc6.png

بعد تعديل auth/env_vars.yaml، شغِّل الأمر التالي في Cloud Shell لنشر دوال Cloud:

cd ~
cd gcf-gmail-codelab/auth

# Deploy Cloud Function auth_init
gcloud functions deploy auth_init --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

# Deploy Cloud Function auth_callback
gcloud functions deploy auth_callback --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

قد يستغرق نشر دوال السحابة بضع دقائق. امنح حزمة Cloud SDK الإذن لتثبيت أوامر الإصدار التجريبي إذا طُلب منك ذلك.

بعد ذلك، انتقِل إلى Google Cloud Console، وانقر على Cloud Functions في قائمة التنقّل اليمنى. انقر على auth_callback في قائمة "وظائف السحابة الإلكترونية"، وبدِّل إلى علامة التبويب التشغيل.

cb094bd341f9b299.png

45678a327c80e0f1.png

انسخ عنوان URL في الصفحة. ارجع إلى صفحة "وظائف السحابة الإلكترونية"، وانقر على auth_init في قائمة "دوال السحابة الإلكترونية". في علامة التبويب الإعدادات العامة، انقر على تعديل. انقر على المتغيّرات البيئية والشبكات والمهلات والمزيد واستبدِل قيمة GOOGLE_CALLBACK_URL بعنوان URL الذي نسخته للتو.

939ca3bd38047282.png

انقر على نشر لتطبيق التغييرات. يُرجى تكرار العملية وتعديل "auth_callback" أيضًا.

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

https://us-central1-my-project.cloudfunctions.net/auth_callback

يجب إضافة ما يلي كنطاق معتمد:

us-central1-my-project.cloudfunctions.net

اضغط على إضافة نطاق للتأكيد.

4348748f232ceb87.png

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

أزِل الجزء /auth_callback من عنوان URL وأضِف الجزء المتبقي كمصدر JavaScript معتمد. على سبيل المثال، إذا كان عنوان URL يبدو مثل

https://us-central1-my-project.cloudfunctions.net/auth_callback

يجب إضافة ما يلي كأصل:

https://us-central1-my-project.cloudfunctions.net/

159bad719432582c.png

اضغط على Enter للتأكيد، ثم انقر على حفظ لتطبيق التغييرات.

5- إعداد الإشعارات الفورية في Gmail

إذا نجحت عملية التفويض، سيتصل تطبيق auth_callback تلقائيًا بواجهة برمجة تطبيقات Gmail لإعداد الإشعارات الفورية.

لتلقي الإشعارات الفورية في Gmail، يجب عليك إنشاء موضوع نشر/اشتراك. سيتلقى أي مشترك في الموضوع إشعارات الرسائل الواردة تلقائيًا عند وصوله من Gmail.

لإنشاء موضوع على خدمة Pub/Sub، انتقِل إلى Google Cloud Console وانقر على نشر/اشتراك >. المواضيع في قائمة التنقّل اليمنى انقر على إنشاء موضوع. اكتب اسم الموضوع، مثل gmail-watch، ثم انقر على إنشاء. بالإضافة إلى ذلك، يجب منح Gmail إذنًا لإرسال رسائل إلى موضوع النشر/الاشتراك: انقر على قائمة السياق للموضوع الذي أنشأته للتو (ثلاث نقاط رأسية)، واختر الأذونات. انقر على إضافة أعضاء، وحدِّد gmail-api-push@system.gserviceaccount.com كعضو جديد، وامنحه دور نشر/اشتراك >. ناشر/اشتراك في النشر وأخيرًا، انقر على حفظ لتطبيق التغييرات.

عدِّل دالة Cloud Function auth_callback لتحديد موضوع النشر/الاشتراك الذي تريد استخدامه. انقر على Cloud Functions في قائمة التنقّل اليمنى، واختَر auth_callback في قائمة "دوال السحابة الإلكترونية". في علامة التبويب الإعدادات العامة، انقر على تعديل. انقر على المزيد واستبدِل قيمة PUBSUB_TOPIC باسم موضوع النشر/الاشتراك الذي أنشأته للتو. انقر على حفظ لتطبيق التغييرات.

أنت الآن جاهز لمصادقة وإعداد الإشعارات الفورية في Gmail. انتظِر إلى أن يتم الانتهاء من التغييرات الجديدة، ثم ارجع إلى صفحة وظائف السحابة الإلكترونية، واختَر auth_init في قائمة وظائف السحابة الإلكترونية، ثم انتقِل إلى علامة التبويب المشغّل. انقر على عنوان URL وستتم إعادة توجيهك إلى صفحة تسجيل الدخول باستخدام حساب Google:

348ab0a7e0c9cd03.png

سجِّل الدخول باستخدام حساب Gmail تملكه. ستؤدي أي رسالة جديدة تصل إلى البريد الوارد للحساب إلى تشغيل إشعار فوري. بعد تسجيل الدخول، ستظهر لك الصفحة أدناه:

cfdad62fd02de004.png

انقر على سماح لمنح الإذن بالوصول. سيُكمل auth_callback عملية التفويض ويحفظ رموز الدخول ويضبط الإشعارات الفورية في Gmail نيابةً عنك. من المفترض أن تظهر الرسالة Successfully set up Gmail push notifications في المتصفّح عند اكتمال هذه العملية.

يستخدم هذا الدرس التطبيقي حول الترميز حزمة @google-cloud/express-oauth2-handlers لتنفيذ عملية التفويض بشكل مبرمَج نيابةً عنك. لمزيد من المعلومات، يُرجى الاطّلاع على مستودعه على GitHub.

6- معالجة الرسائل الواردة

كما ذكرنا سابقًا، سيتلقّى أي مشترك في موضوع "النشر/الاشتراك" الذي أنشأته إشعارات عند وصول رسائل جديدة إلى بريدك الوارد. تحدّد pubsub/index.js دالة السحابة الإلكترونية، watchGmailMessages، التي بعد نشرها كمشترك في الموضوع، ستقرأ الرسائل الجديدة وتصنِّف الصور المرفقة وتصدِّر هذه الفئات إلى "جدول بيانات Google".

لفحص الرمز، افتح pubsub/index.js في "محرِّر رموز Cloud Shell".

جارٍ استرداد الرسائل

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

// Look up the most recent message.
const listMessagesRes = await gmail.users.messages.list({
  userId: email,
  maxResults: 1
});
const messageId = listMessagesRes.messages[0].id;

// Get the message using the message ID.
const message = await gmail.users.messages.get({
  userId: email,
  id: messageId
});

return message;

تحليل مرفقات الصور

إذا كانت الرسالة تحتوي على مرفق صورة، سيطلب تطبيق "watchGmailMessages" من واجهة Cloud Vision API إضافة تعليقات توضيحية إلى الصورة. في هذا الدرس التطبيقي حول الترميز، ستطلب من Cloud Vision API تصنيف الصورة وعرض عدد من علاماتها. على سبيل المثال، إذا تم توفيرها مع صورة للسماء الزرقاء، قد تعرض Cloud Vision API العلامات الأزرق والسماء والطبيعة.

يستخدم watchGmailMessages مكتبة Cloud Vision API لـ Node.js لطلب واجهة برمجة تطبيقات Cloud Vision:

// Tag the attachment using Cloud Vision API
const analyzeAttachment = async (data, filename) => {
  var topLabels = ['', '', ''];
  if (filename.endsWith('.png') || filename.endsWith('.jpg')) {
    const [analysis] = await visionClient.labelDetection({
      image: {
        content: Buffer.from(data, 'base64')
      }
    });
    const labels = analysis.labelAnnotations;
    topLabels = labels.map(x => x.description).slice(0, 3);
  }

  return topLabels;
};

تحديث جدول بيانات Google

يصدِّر watchGmailMessages نتائج هذا التحليل إلى "جدول بيانات Google". وهي تتضمن اسم المرسل واسم المرفق وعلامات مرفقات الصور (إن وجدت).

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

https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0

رقم تعريف جدول بياناتك هو abcdefghij01234567890. في "محرِّر رموز Cloud Shell"، عدِّل gcf-gmail-codelab/pubsub/env_vars.yaml واستبدِل YOUR-GOOGLE-SHEET-ID بالقيمة الخاصة بك.

يرتبط watchGmailMessages بـ Google Sheets API لإلحاق المعلومات:

const updateReferenceSheet = async (from, filename, topLabels) => {
  await googleSheets.spreadsheets.values.append({
    spreadsheetId: SHEET,
    range: SHEET_RANGE,
    valueInputOption: 'USER_ENTERED',
    requestBody: {
      range: SHEET_RANGE,
      majorDimension: 'ROWS',
      values: [
        [from, filename].concat(topLabels)
      ]
    }
  });
};

خطوة أخرى أخيرة

في "محرِّر رموز Cloud Shell"، افتح gcf-gmail-codelab/pubsub/env_vars.yaml واستبدِل YOUR-GOOGLE-CLIENT-ID وYOUR-GOOGLE-CLIENT-SECRET وYOUR-GOOGLE-CALLBACK-URL بقيمك الخاصة. يمكنك العثور على هذه القيم في Google Cloud Console: افتح Cloud Functions في قائمة التنقّل اليمنى، واختَر auth_init في قائمة دوال السحابة الإلكترونية، وابحث عن قسم متغيّرات البيئة.

نشر الرمز

شغّل الأمر أدناه لنشر دالة السحابة:

cd ~

cd gcf-gmail-codelab/pubsub

gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml

في حال تسمية موضوع Cloud Pub/Sub باسم غير "gmail-watch"، استبدِل gmail-watch في الأمر أعلاه باسم الموضوع. قد يستغرق نشر الدالة Cloud بضع ثوانٍ.

7. جرّبه الآن

تهانينا، لقد انتهيت! إرسال رسالة إلكترونية إلى نفسك مع مرفق صورة. في غضون بضع ثوانٍ، سيظهر لك "جدول بيانات Google" الذي أنشأته يتم تعديله تلقائيًا استنادًا إلى المعلومات التي قدّمتها.