صندوق ورودی جیمیل خود را با توابع Google Cloud تقویت کنید

۱. مقدمه

میلیاردها کسب‌وکار و فرد از Gmail و سایر سرویس‌های G Suite برای برقراری ارتباط و پردازش داده‌ها استفاده می‌کنند. گوگل APIهای G Suite را برای کمک به شما در دسترسی به اطلاعات در این سرویس‌ها به صورت برنامه‌نویسی ارائه می‌دهد و می‌توانید از APIها برای خودکارسازی آسان گردش کار روزانه خود استفاده کنید. در این آزمایشگاه، یک افزونه قدرتمند Gmail خواهید ساخت که به طور خودکار ایمیل‌ها را در پیام‌های دریافتی دسته‌بندی کرده و آن دسته‌ها را در یک برگه Google ذخیره می‌کند. این افزونه از APIهای RESTful G Suite، توابع Google Cloud و سایر سرویس‌های Google Cloud Platform استفاده خواهد کرد.

آنچه خواهید ساخت

در این آزمایش، شما چند تابع ابری متصل به APIهای G Suite و سایر سرویس‌های Google Cloud Platform را ساخته و مستقر خواهید کرد. این توابع:

  • دسترسی امن به داده‌های Gmail و Google Sheets خود را مجاز کنید
  • استخراج تصاویر پیوست شده به هر ایمیل دریافتی
  • با استفاده از Cloud Vision API، آن تصاویر را دسته‌بندی کنید
  • آن دسته‌ها، آدرس فرستنده و نام پیوست را در یک صفحه گوگل بنویسید

آنچه یاد خواهید گرفت

  • اصول اولیه API های RESTful در G Suite
  • اصول اولیه عملکردهای گوگل کلود و سایر سرویس‌های پلتفرم گوگل کلود
  • نحوه دسترسی به جیمیل به صورت برنامه‌نویسی شده با استفاده از توابع ابری گوگل

آنچه شما نیاز خواهید داشت

  • یک حساب گوگل با دسترسی به جیمیل و گوگل شیت. اگر ندارید، اینجا یکی بسازید .
  • دانش اولیه از Javascript/Node.js.

۲. اولویت با اولویت‌های مهم

فعال کردن APIها

در این آزمایش شما از محصولات/سرویس‌های گوگل زیر استفاده خواهید کرد:

  • عملکردهای گوگل کلود
  • میخانه/زیرمجموعه گوگل کلود
  • رابط برنامه‌نویسی کاربردی گوگل کلود ویژن
  • فروشگاه داده ابری گوگل
  • رابط برنامه‌نویسی کاربردی جیمیل
  • رابط برنامه‌نویسی کاربردی گوگل شیت

عملکردهای گوگل کلود

توابع ابری گوگل، پلتفرم توابع به عنوان سرویس بدون سرور گوگل است که به شما امکان می‌دهد قطعه کدهای جداگانه ('توابع') را به روشی ساده و مقیاس‌پذیر اجرا کنید.

برای فعال کردن عملکردهای گوگل کلود، روی منوی همبرگری در سمت چپ بالای صفحه کلیک کنید تا نوار کناری ناوبری سمت چپ باز شود:

f457988e33594bb6.png

در منوی ناوبری، Cloud Functions را پیدا کرده و روی آن کلیک کنید. برای فعال کردن Google Cloud Functions در پروژه خود، روی Enable API کلیک کنید.

میخانه/زیرمجموعه گوگل کلود

Google Cloud Pub/Sub یک بستر ساده و مقیاس‌پذیر برای پخش داده‌ها و تحویل رویداد است. در این آزمایشگاه، این سرویس به عنوان رابط بین Gmail و Google Cloud Functions عمل می‌کند.

برای فعال کردن Google Cloud Pub/Sub، نوار کناری ناوبری سمت چپ را باز کنید، Pub/Sub را پیدا کنید و روی آن کلیک کنید. برای فعال کردن Google Cloud Pub/Sub در پروژه خود، روی فعال کردن API کلیک کنید.

فروشگاه داده ابری گوگل

Google Cloud Datastore یک پایگاه داده بدون سرور است که مقیاس‌پذیر و توزیع‌شده است.

برای فعال کردن Google Cloud Datastore، در نوار کناری سمت چپ، Datastore را پیدا کرده و روی آن کلیک کنید. در صفحه جدید، روی Select Datastore Mode کلیک کنید.

۹۸۰۱۲c۹۱fd۴۰۸۰d۴.png

شما می‌توانید از هر مکان پایگاه داده‌ای برای این آزمایش استفاده کنید. برای فعال کردن Google Cloud Datastore روی Create Database کلیک کنید؛ تکمیل این فرآیند ممکن است چند دقیقه طول بکشد.

گوگل کلود ویژن

Google Cloud Vision API یک سرویس یادگیری ماشینی قدرتمند است که از مدل‌های از پیش آموزش‌دیده برای استخراج بینش از تصاویر شما استفاده می‌کند.

برای اطلاعات بیشتر در مورد نحوه فعال کردن Google Cloud Vision API، به دستورالعمل‌های زیر مراجعه کنید.

فعال کردن Gmail API، Google Sheets API و Google Cloud Vision API

یک بار دیگر، نوار کناری ناوبری سمت چپ را باز کنید و APIs & Services را پیدا کنید. روی Library کلیک کنید. در فیلد Search for APIs & Services ، عبارت Gmail را تایپ کنید. در نتایج جستجو، Gmail API را انتخاب کرده و روی Enable کلیک کنید.

به صفحه کتابخانه API برگردید. API مربوط به Google Sheets را جستجو کنید و آن را فعال کنید.

این فرآیند را تکرار کنید. Cloud Vision API را جستجو کرده و آن را فعال کنید.

باز کردن پوسته ابری گوگل

در این آزمایش، شما از Google Cloud Shell برای انجام اکثر عملیات استفاده خواهید کرد. Cloud Shell دسترسی خط فرمان به منابع Google Cloud Platform شما را مستقیماً از مرورگرتان فراهم می‌کند و به شما امکان می‌دهد بدون استفاده از یک دستگاه محلی، آنها را مدیریت کنید.

برای باز کردن پوسته ابری گوگل، روی دکمه فعال‌سازی پوسته ابری در نوار افقی آبی بالا کلیک کنید:

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 ظاهر می‌شود.

۳. نمای کلی معماری

روند کار این آزمایشگاه به شرح زیر است:

79c5d3e43f674b33.png

  1. کاربر اعلان‌های فوری جیمیل را تنظیم می‌کند: هر بار که پیام جدیدی به صندوق ورودی می‌رسد، جیمیل یک اعلان به Cloud Pub/Sub ارسال می‌کند.
  2. Cloud Pub/Sub اعلان پیام جدید را به توابع Google Cloud ارسال می‌کند.
  3. به محض رسیدن اعلان پیام جدید، یک نمونه از توابع ابری به جیمیل متصل می‌شود و پیام جدید را بازیابی می‌کند.
  4. اگر ایمیل دارای تصویر به عنوان پیوست باشد، نمونه Cloud Functions، Cloud Vision API را برای تجزیه و تحلیل پیوست فراخوانی می‌کند.
  5. نمونه توابع ابری، یک برگه گوگل (Google Sheet) دلخواه شما را به‌روزرسانی می‌کند و مشخص می‌کند چه کسی پیام را ارسال می‌کند و فایل پیوست را از کجا دانلود کنید.

۴. اجازه دسترسی به جیمیل را بدهید

قبل از تنظیم یک تابع ابری برای خواندن خودکار ایمیل‌هایتان، باید دسترسی آن را به Gmail مجاز کنید. باید یک کلاینت OAuth را در گوگل ثبت کنید و یک شناسه کلاینت مرتبط ایجاد کنید.

یک کلاینت OAuth ثبت کنید

در منوی ناوبری سمت چپ کنسول ابری گوگل، APIها و خدمات را پیدا کنید. روی صفحه رضایت OAuth کلیک کنید.

۹۱b2a3bac30bb2c5.png

در فیلد نام برنامه ، یک نام تایپ کنید، مانند GCF + Gmail Codelab . سایر تنظیمات را دست نخورده بگذارید، به پایین صفحه بروید و روی ذخیره کلیک کنید.

ایجاد یک شناسه کلاینت مرتبط

به برگه اعتبارنامه‌ها بروید. روی «ایجاد اعتبارنامه‌ها» کلیک کنید و شناسه کلاینت OAuth را انتخاب کنید. نوع برنامه وب را انتخاب کنید، به آن نامی بدهید (می‌توانید دوباره از GCF + Gmail Codelab در اینجا استفاده کنید) و روی «ایجاد» کلیک کنید. فعلاً فیلدهای «محدودیت‌ها» را خالی بگذارید.

شناسه کلاینت و رمز کلاینت برگردانده شده را در پنجره بازشو یادداشت کنید. می‌توانید برای مشاهده مجدد این مقادیر، روی نام کلاینت خود در صفحه کلیک کنید:

1160d8027ea52d90.png

انجام فرآیند مجوزدهی

در کد نمونه، auth/index.js دو تابع ابری، 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 را فعلاً بدون تغییر بگذارید.

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 اجازه نصب دستورات بتا را بدهید.

سپس، به کنسول ابری گوگل بروید و در منوی ناوبری سمت چپ روی Cloud Functions کلیک کنید. در لیست Cloud Functions روی auth_callback کلیک کنید و به تب Trigger بروید.

cb094bd341f9b299.png

۴۵۶۷۸a۳۲۷c۸۰e۰f۱.png

آدرس اینترنتی (URL) موجود در صفحه را کپی کنید. به صفحه توابع ابری (Cloud Functions) برگردید، در فهرست توابع ابری (Cloud Functions) روی auth_init کلیک کنید. در تب عمومی (General) ، روی ویرایش (Edit) کلیک کنید. روی متغیرهای محیطی (Environmental variables)، شبکه (networking)، زمان‌های انتظار (timeouts and more ) کلیک کنید و مقدار GOOGLE_CALLBACK_URL را با آدرس اینترنتی (URL) که کپی کرده‌اید، جایگزین کنید.

939ca3bd38047282.png

برای اعمال تغییرات، روی Deploy کلیک کنید. فرآیند را تکرار کنید و auth_callback را نیز به‌روزرسانی کنید.

در نهایت، منوی ناوبری سمت چپ را باز کنید و روی APIها و خدمات > تأیید دامنه کلیک کنید. برای افزودن یک دامنه مجاز، روی افزودن دامنه کلیک کنید. به عنوان مثال، اگر URL که قبلاً کپی کرده‌اید به شکل زیر باشد

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

شما باید موارد زیر را به عنوان دامنه مجاز اضافه کنید:

us-central1-my-project.cloudfunctions.net

برای تأیید، افزودن دامنه را فشار دهید.

4348748f232ceb87.png

به صفحه اعتبارنامه‌ها برگردید. روی نام کلاینت OAuth خود کلیک کنید و URL کپی شده را به عنوان یک URL تغییر مسیر مجاز اضافه کنید. برای تأیید، Enter را فشار دهید.

قسمت /auth_callback را از URL حذف کنید و بقیه را به عنوان یک Authorized Javascript origin اضافه کنید. برای مثال، اگر URL شما به شکل زیر باشد

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

شما باید موارد زیر را به عنوان مبدا اضافه کنید:

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

159bad719432582c.png

برای تأیید، Enter را فشار دهید و برای اعمال تغییرات، روی ذخیره کلیک کنید.

۵. اعلان‌های جیمیل را تنظیم کنید

اگر فرآیند احراز هویت با موفقیت انجام شود، auth_callback به طور خودکار API جیمیل را برای تنظیم اعلان‌های فوری فراخوانی می‌کند.

برای دریافت اعلان‌های فوری جیمیل، باید یک موضوع Pub/Sub ایجاد کنید. هر مشترکی که در این موضوع مشترک شود، اعلان‌های پیام‌های دریافتی را به محض رسیدن از جیمیل به طور خودکار دریافت خواهد کرد.

برای ایجاد یک موضوع Pub/Sub، به کنسول Google Cloud بروید و در منوی ناوبری سمت چپ روی Pub/Sub > Topics کلیک کنید. روی ایجاد موضوع کلیک کنید. نام موضوع، مانند gmail-watch تایپ کنید و روی ایجاد کلیک کنید. علاوه بر این، باید به Gmail اجازه دهید تا به موضوع Pub/Sub شما پیام ارسال کند: روی منوی زمینه موضوعی که تازه ایجاد کرده‌اید (سه نقطه عمودی) کلیک کنید و Permissions را انتخاب کنید؛ روی Add Members کلیک کنید، gmail-api-push@system.gserviceaccount.com را به عنوان عضو جدید مشخص کنید و نقش Pub/Sub > Pub/Sub Publisher را به آن بدهید؛ در نهایت، برای اعمال تغییرات روی Save کلیک کنید.

تابع ابری auth_callback به‌روزرسانی کنید تا مشخص شود از کدام موضوع Pub/Sub استفاده شود. در منوی ناوبری سمت چپ روی Cloud Functions کلیک کنید و در لیست Cloud Functions، auth_callback انتخاب کنید. در تب General ، روی Edit کلیک کنید. روی More کلیک کنید و مقدار PUBSUB_TOPIC را با نام موضوع Pub/Sub که ایجاد کرده‌اید جایگزین کنید. برای اعمال تغییرات، روی Save کلیک کنید.

اکنون آماده‌ی تأیید و تنظیم اعلان‌های فوری جیمیل هستید. صبر کنید تا تغییرات جدید نهایی شوند، سپس به صفحه‌ی توابع ابری برگردید، در فهرست توابع ابری، auth_init انتخاب کنید و به برگه‌ی Trigger بروید. روی URL کلیک کنید تا به صفحه‌ی ورود با گوگل هدایت شوید:

۳۴۸ab0a7e0c9cd03.png

با حساب جیمیل خود وارد شوید. هر پیام جدیدی که به صندوق ورودی حساب وارد شود، یک اعلان فوری (push notification) را فعال می‌کند. پس از ورود، صفحه زیر را مشاهده خواهید کرد:

cfdad62fd02de004.png

برای تأیید دسترسی، روی «اجازه دادن» کلیک کنید. auth_callback فرآیند تأیید را تکمیل می‌کند، توکن‌های دسترسی را ذخیره می‌کند و اعلان‌های فشاری Gmail را برای شما تنظیم می‌کند. پس از اتمام این فرآیند، باید پیام Successfully set up Gmail push notifications در مرورگر خود مشاهده کنید.

این آزمایشگاه کد از بسته @google-cloud/express-oauth2-handlers برای خودکارسازی گردش کار احراز هویت برای شما استفاده می‌کند. برای اطلاعات بیشتر، به مخزن آن در GitHub مراجعه کنید.

۶. پردازش پیام‌های دریافتی

همانطور که قبلاً اشاره کردیم، هر مشترکی که در موضوع Pub/Sub که ایجاد کرده‌اید، مشترک شود، هنگام رسیدن پیام‌های جدید به صندوق ورودی خود، اعلان‌هایی دریافت خواهد کرد. pubsub/index.js یک تابع ابری به نام watchGmailMessages را مشخص می‌کند که پس از استقرار به عنوان مشترک در موضوع، پیام‌های جدید را می‌خواند، تصاویر پیوست شده را دسته‌بندی می‌کند و آن دسته‌ها را به یک صفحه Google صادر می‌کند.

برای بررسی کد، pubsub/index.js را در ویرایشگر کد Cloud Shell باز کنید.

بازیابی پیام‌ها

یک اعلان فوری جیمیل شامل آدرس ایمیلی است که اعلان به آن مرتبط است و یک شناسه تاریخچه. برای سادگی، در این آزمایشگاه کد، شما به سادگی از 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 را برای حاشیه‌نویسی تصویر فراخوانی می‌کند. در این آزمایشگاه کد، از رابط برنامه‌نویسی Cloud Vision می‌خواهید که تصویر را طبقه‌بندی کرده و تعدادی برچسب تصویر را برگرداند؛ برای مثال، اگر تصویری از آسمان آبی ارائه شود، رابط برنامه‌نویسی Cloud Vision ممکن است برچسب‌های آبی ، آسمان و طبیعت را برگرداند.

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;
};

به‌روزرسانی گوگل شیت

watchGmailMessages نتایج این تحلیل را به یک صفحه گوگل (Google Sheet) منتقل می‌کند. این صفحه شامل نام فرستنده، نام پیوست و برچسب‌های پیوست‌های تصویری (در صورت وجود) است.

ابتدا، یک گوگل شیت ایجاد کنید. گوگل شیت را باز کنید و در قسمت «شروع یک صفحه گسترده جدید» روی الگوی خالی کلیک کنید. شناسه صفحه خود را کپی کنید. به عنوان مثال، اگر آدرس در مرورگر شما به این شکل است:

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 پیدا کنید: Cloud Functions را در منوی ناوبری سمت چپ باز کنید، auth_init را در لیست Cloud Functions انتخاب کنید و بخش Environment variables را جستجو کنید.

کد را مستقر کنید

برای استقرار عملکرد Cloud، دستور زیر را اجرا کنید: 

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 اعمال شود.

۷. امتحانش کنید

تبریک، کارتان تمام شد! یک ایمیل حاوی تصویر ضمیمه برای خودتان ارسال کنید. ظرف چند ثانیه خواهید دید که صفحه گوگلی که ایجاد کرده‌اید به طور خودکار با اطلاعاتی که ارائه می‌دهید به‌روزرسانی می‌شود.