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

1. مقدمة

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

ما ستنشئه

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

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

ما ستتعلمه

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

المتطلبات

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

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

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

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

‫Google Cloud Functions
‫Google Cloud Pub/Sub
Google Cloud Vision API
Google Cloud Datastore
Gmail API
Google Sheets API

‫Google Cloud Functions

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

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

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

‫Google Cloud Pub/Sub

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

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

Google Cloud Datastore

‫Google Cloud Datastore هي قاعدة بيانات بدون خادم قابلة للتوسّع وموزّعة.

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

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

Google Cloud Vision

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

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

تفعيل واجهة برمجة التطبيقات Gmail API و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 في الشريط الأفقي الأزرق في أعلى الصفحة:

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

انقر على الزر تشغيل أداة تعديل الرموز لبدء استخدام "أداة تعديل الرموز" في Cloud Shell:

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

تنزيل الرمز

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

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

cd gcf-gmail-codelab

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

3- نظرة عامة على البنية

في ما يلي سير عمل هذا الدرس التطبيقي:

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

4. منح إذن الوصول إلى Gmail

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

تسجيل عميل OAuth

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

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

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

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

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

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

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

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

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

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

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

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

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

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 Functions بضع دقائق. إذا طُلب منك ذلك، امنح Cloud SDK الإذن بتثبيت أوامر الإصدار التجريبي.

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

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

انقر على نشر لتطبيق التغييرات. كرِّر العملية وحدِّث auth_callback أيضًا.

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

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

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

us-central1-my-project.cloudfunctions.net

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

ارجع إلى صفحة بيانات الاعتماد. انقر على اسم عميل 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/

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

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

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

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

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

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

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

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

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

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

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

كما ذكرنا سابقًا، سيتلقّى أي مشترك في موضوع Pub/Sub الذي أنشأته إشعارات عند وصول رسائل جديدة إلى بريدك الوارد. تحدّد 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 API:

// 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 في قائمة Cloud Functions، وابحث عن قسم متغيرات البيئة.

تفعيل الرمز

نفِّذ الأمر أدناه لنشر Cloud Function:

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 Function بضع ثوانٍ.

7. للتجربة:

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