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

1. مقدمه

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

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

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

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

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

  • اصول G Suite RESTful API
  • مبانی توابع Google Cloud و سایر خدمات Google Cloud Platform
  • چگونه با استفاده از توابع Google Cloud به صورت برنامه نویسی به جیمیل دسترسی پیدا کنیم

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

2. اول چیزها

API ها را فعال کنید

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

  • توابع Google Cloud
  • Google Cloud Pub/Sub
  • Google Cloud Vision API
  • Google Cloud Datastore
  • Gmail API
  • Google Sheets API

توابع Google Cloud

Google Cloud Functions پلتفرم توابع بدون سرور گوگل است که به شما امکان می دهد تکه های کد ("توابع") را به روشی ساده و مقیاس پذیر اجرا کنید.

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

f457988e33594bb6.png

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

Google Cloud Pub/Sub

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

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

Google Cloud Datastore

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

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

98012c91fd4080d4.png

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

Google Cloud Vision

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 برگردید. Google Sheets API را جستجو کنید و آن را فعال کنید.

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

Google Cloud Shell را باز کنید

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

برای باز کردن Google Cloud Shell، روی دکمه Activate Cloud Shell در نوار افقی آبی بالا کلیک کنید:

fd5c2925ca9cdfdd.png

یک پنل جدید در پایین صفحه ظاهر می شود:

34f498402e910802.png

روی دکمه Launch code editor کلیک کنید تا Cloud Shell Code Editor راه اندازی شود:

10f8631ef48bed22.png

Cloud Shell Code Editor در یک پنجره جدید باز می شود.

کد را دانلود کنید

دستور زیر را در Cloud Shell خود اجرا کنید تا پروژه کلون شود:

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

cd gcf-gmail-codelab

باید پوشه جدیدی به نام gcf-gmail-codelab را مشاهده کنید که در ویرایشگر کد پوسته ابری ظاهر می شود.

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

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

79c5d3e43f674b33.png

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

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

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

مشتری OAuth را ثبت کنید

در منوی پیمایش سمت چپ Google Cloud Console، APIs & Services را پیدا کنید. روی صفحه رضایت OAuth کلیک کنید.

91b2a3bac30bb2c5.png

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

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

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

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

1160d8027ea52d90.png

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

در کد نمونه، auth/index.js دو تابع Cloud، auth_init و auth_callback را مشخص می‌کند، که با استفاده از شناسه مشتری و رمز سرویس گیرنده که ایجاد کرده‌اید، برای انجام فرآیند مجوز کار با هم کار می‌کنند.

برای بررسی کد، auth/index.js در Cloud Shell Code Editor باز کنید.

فرآیند مجوز دو نوع توکن را برمی‌گرداند: توکن‌های دسترسی و نشانه‌های تازه‌سازی .

  • توکن‌های دسترسی، مدارک هویتی کوتاه‌مدتی هستند که به هر کسی که آن‌ها را در اختیار دارد، به داده‌های شما دسترسی وسیعی می‌دهد. auth_callback آنها را در Cloud Datastore ذخیره می کند.
  • توکن‌های Refresh برای به دست آوردن نشانه‌های دسترسی جدید استفاده می‌شوند و به طور قابل توجهی عمر طولانی‌تری دارند.

به طور معمول، آنها یا رمزگذاری شده و/یا جدا از توکن های دسترسی ذخیره می شوند.

auth/env_vars.yaml را در ویرایشگر کد پوسته ابری ویرایش کنید. 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 در لیست توابع Cloud کلیک کنید و به تب Trigger بروید.

cb094bd341f9b299.png

45678a327c80e0f1.png

URL موجود در صفحه را کپی کنید. به صفحه توابع Cloud برگردید، روی auth_init در لیست توابع ابری کلیک کنید. در برگه عمومی ، روی ویرایش کلیک کنید. روی متغیرهای محیطی، شبکه، مهلت زمانی و موارد دیگر کلیک کنید و مقدار GOOGLE_CALLBACK_URL را با نشانی اینترنتی که به تازگی کپی کردید جایگزین کنید.

939ca3bd38047282.png

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

در آخر، منوی پیمایش سمت چپ را باز کنید و روی APIs & Services > Domain verification کلیک کنید. برای افزودن دامنه مجاز، روی افزودن دامنه کلیک کنید. برای مثال، اگر نشانی اینترنتی که قبلاً کپی کرده‌اید به نظر می‌رسد

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

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

us-central1-my-project.cloudfunctions.net

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

4348748f232ceb87.png

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

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

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

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

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

159bad719432582c.png

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

5. اعلان‌های فشار Gmail را تنظیم کنید

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

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

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

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

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

348ab0a7e0c9cd03.png

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

cfdad62fd02de004.png

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

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

6. پیام های دریافتی را پردازش کنید

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

برای بررسی کد، pubsub/index.js در Cloud Shell Code Editor باز کنید.

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

اعلان فشار 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 Sheet را به‌روزرسانی کنید

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

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

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

شناسه صفحه گسترده شما abcdefghij01234567890 است. در Cloud Shell Code Editor، gcf-gmail-codelab/pubsub/env_vars.yaml را به‌روزرسانی کنید و YOUR-GOOGLE-SHEET-ID با مقدار خود جایگزین کنید.

watchGmailMessages برای افزودن اطلاعات به API Google Sheets متصل می‌شود: 

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 Code Editor، gcf-gmail-codelab/pubsub/env_vars.yaml را باز کنید و YOUR-GOOGLE-CLIENT-ID ، YOUR-GOOGLE-CLIENT-SECRET و YOUR-GOOGLE-CALLBACK-URL با مقادیر خودتان جایگزین کنید. می‌توانید این مقادیر را در Google Cloud Console بیابید: توابع Cloud را در منوی پیمایش سمت چپ باز کنید، auth_init را در لیست توابع Cloud انتخاب کنید و به دنبال بخش متغیرهای محیط باشید.

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

دستور زیر را برای استقرار تابع 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 اجرا شود.

7. آن را امتحان کنید

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