משתמשים ב-Google Cloud Functions כדי לשפר את תיבת הדואר הנכנס של Gmail

1. מבוא

מיליארדי עסקים ואנשים פרטיים משתמשים ב-Gmail ובשירותים אחרים של G Suite כדי לתקשר ולעבד נתונים. ‫Google מציעה ממשקי G Suite API כדי לעזור לכם לגשת למידע בשירותים האלה באופן פרוגרמטי, ואתם יכולים להשתמש בממשקי ה-API כדי לבצע אוטומציה של תהליך העבודה היומיומי שלכם בקלות. במעבדה הזו תיצרו תוסף יעיל ל-Gmail שמסווג באופן אוטומטי אימיילים בהודעות נכנסות ושומר את הסיווגים האלה בגיליון אלקטרוני של Google. התוסף הזה ישתמש בממשקי RESTful API של G Suite, ב-Google Cloud Functions ובשירותים אחרים של Google Cloud Platform.

מה תפַתחו

בשיעור ה-Lab הזה תבנו ותפרסו כמה פונקציות של Cloud Functions שמחוברות לממשקי API של G Suite ולשירותים אחרים של Google Cloud Platform. הפונקציות האלה:

איך מאשרים גישה מאובטחת לנתונים ב-Gmail וב-Google Sheets
חילוץ תמונות שמצורפות לכל אימייל נכנס
סיווג התמונות באמצעות Cloud Vision API
כותבים את הקטגוריות האלה, את הכתובת של השולח ואת השם של הקובץ המצורף בגיליון אלקטרוני ב-Google Sheets

מה תלמדו

היסודות של ממשקי API מסוג RESTful של G Suite
יסודות ב-Google Cloud Functions ובשירותים אחרים של Google Cloud Platform
איך ניגשים ל-Gmail באופן פרוגרמטי באמצעות Google Cloud Functions

מה צריך

חשבון Google עם גישה ל-Gmail ול-Google Sheets. אם אין לכם חשבון, כאן אפשר ליצור חשבון.
ידע בסיסי ב-JavaScript או ב-Node.js.

2. השלב הראשון

הפעלת ממשקי ה-API

בשיעור ה-Lab הזה תשתמשו במוצרים ובשירותים הבאים של Google:

‫Google Cloud Functions
Google Cloud Pub/Sub
Google Cloud Vision API
Google Cloud Datastore
ממשק ה-API של Gmail
Google Sheets API

‫Google Cloud Functions

‫Google Cloud Functions היא פלטפורמת פונקציות כשירות (FaaS) בלי שרת (serverless) של Google, שמאפשרת להריץ קטעי קוד בודדים (פונקציות) בצורה פשוטה וניתנת להרחבה.

כדי להפעיל את Google Cloud Functions, לוחצים על סמל האפשרויות הנוספות (3 קווים) בפינה הימנית העליונה של המסך כדי לפתוח את סרגל הצד לניווט:

בתפריט הניווט, מחפשים את Cloud Functions ולוחצים עליו. לוחצים על Enable API כדי להפעיל את Google Cloud Functions בפרויקט.

Google Cloud Pub/Sub

‫Google Cloud Pub/Sub הוא בסיס פשוט וניתן להרחבה להזרמת נתונים ולמסירת אירועים. בשיעור ה-Lab הזה הוא משמש כבלדר בין Gmail לבין Google Cloud Functions.

כדי להפעיל את Google Cloud Pub/Sub, פותחים את סרגל הצד לניווט בצד ימין, מאתרים את Pub/Sub ולוחצים עליו. לוחצים על Enable API כדי להפעיל את Google Cloud Pub/Sub בפרויקט.

Google Cloud Datastore

‫Google Cloud Datastore הוא מסד נתונים ללא שרת (serverless) עם יכולת התאמה רחבה ומבוזר.

כדי להפעיל את Google Cloud Datastore, בסרגל הצד לניווט שמימין, מחפשים את Datastore ולוחצים עליו. בדף החדש, לוחצים על Select Datastore Mode (בחירת מצב Datastore).

אפשר להשתמש בכל מיקום של מסד נתונים לשיעור ה-Lab הזה. לוחצים על יצירת מסד נתונים כדי להפעיל את 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 (ממשקי API ושירותים). לוחצים על ספרייה. בשדה Search for APIs & Services (חיפוש ממשקי API ושירותים), מקלידים Gmail. בתוצאות החיפוש, בוחרים באפשרות Gmail API ולוחצים על הפעלה.

חוזרים לדף API Library. מחפשים את Google Sheets API ומפעילים אותו.

חוזרים על התהליך. מחפשים את Cloud Vision API ומפעילים אותו.

פתיחת Google Cloud Shell

בשיעור ה-Lab הזה תשתמשו ב-Google Cloud Shell כדי לבצע את רוב הפעולות. ‫Cloud Shell מספקת לכם גישה למשאבים שלכם ב-Google Cloud Platform דרך שורת הפקודה ישירות מהדפדפן, כך שאתם יכולים לנהל אותם בלי להשתמש במחשב מקומי.

כדי לפתוח את Google Cloud Shell, לוחצים על הלחצן Activate Cloud Shell בסרגל הכחול האופקי העליון:

בתחתית המסך תופיע חלונית חדשה:

כדי להפעיל את Cloud Shell Code Editor, לוחצים על הלחצן Launch code editor (הפעלת עורך הקוד):

ייפתח חלון חדש של Cloud Shell Code Editor.

הורדת הקוד

מריצים את הפקודה הבאה ב-Cloud Shell כדי לשכפל את הפרויקט:

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

cd gcf-gmail-codelab

תיקייה חדשה, gcf-gmail-codelab, אמורה להופיע בכלי לעריכת קוד ב-Cloud Shell.

3. סקירה כללית של הארכיטקטורה

בהמשך מתואר תהליך העבודה של שיעור ה-Lab הזה:

המשתמש מגדיר התראות פוש ב-Gmail: בכל פעם שהודעה חדשה מגיעה לתיבת הדואר הנכנס, Gmail שולח התראה ל-Cloud Pub/Sub.
שירות Cloud Pub/Sub מעביר את ההתראה על ההודעה החדשה אל Google Cloud Functions.
כשמתקבלת התראה על הודעה חדשה, מופעלת Cloud Functions שמתחברת ל-Gmail ומאחזרת את ההודעה החדשה.
אם האימייל כולל תמונה כקובץ מצורף, המופע של Cloud Functions קורא ל-Cloud Vision API כדי לנתח את הקובץ המצורף.
המופע של Cloud Functions מעדכן גיליון אלקטרוני ב-Google Sheets לפי בחירתכם, ומציין מי שלח את ההודעה ואיפה אפשר להוריד את הקובץ המצורף.

4. אישור גישה ל-Gmail

לפני שמגדירים Cloud Function לקריאה אוטומטית של האימיילים, צריך לאשר את הגישה שלו ל-Gmail. תצטרכו לרשום לקוח OAuth ב-Google וליצור מזהה לקוח משויך.

רישום לקוח OAuth

בתפריט הניווט הימני במסוף Google Cloud, מחפשים את האפשרות APIs & Services. לוחצים על מסך הסכמה ל-OAuth.

כותבים שם בשדה Application name (שם האפליקציה), למשל GCF + Gmail Codelab. לא משנים את שאר ההגדרות, גוללים למטה בדף ולוחצים על שמירה.

יצירת מזהה לקוח משויך

עוברים לכרטיסייה Credentials (פרטי כניסה). לוחצים על Create Credentials (יצירת פרטי כניסה) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth). בוחרים בסוג אפליקציית אינטרנט, נותנים לו שם (אפשר להשתמש שוב ב-GCF + Gmail Codelab) ולוחצים על Create. בשלב הזה, משאירים את השדות Restrictions (הגבלות) ריקים.

רושמים את מזהה הלקוח ואת הסוד של הלקוח שמופיעים בחלון הקופץ. כדי לראות שוב את הערכים האלה, אפשר ללחוץ על שם הלקוח בדף:

ביצוע תהליך ההרשאה

בקוד לדוגמה, auth/index.js מציין שתי Cloud Functions, ‏ auth_init ו-auth_callback, שפועלות יחד כדי לבצע את תהליך ההרשאה, באמצעות מזהה הלקוח והסוד של הלקוח שיצרתם זה עתה.

כדי לבדוק את הקוד, פותחים את הקובץ auth/index.js ב-Cloud Shell Code Editor.

תהליך ההרשאה מחזיר שני סוגים של אסימונים: אסימוני גישה ואסימוני רענון.

אסימוני גישה הם הוכחות זהות לטווח קצר שמעניקות לכל מי שמחזיק בהם גישה מוגבלת לנתונים שלכם. auth_callback שומרת אותם ב-Cloud Datastore.
אסימוני רענון משמשים לקבלת אסימוני גישה חדשים, והם תקפים למשך זמן ארוך יותר.

בדרך כלל הם מוצפנים או מאוחסנים בנפרד מאסימוני הגישה.

עורכים את הקובץ auth/env_vars.yaml ב-Cloud Shell Code Editor. מחליפים את 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 יופעלו. אם תתבקשו, תצטרכו לתת ל-Cloud SDK הרשאה להתקין פקודות בגרסת בטא.

לאחר מכן, עוברים אל מסוף Google Cloud ולוחצים על Cloud Functions בתפריט הניווט הימני. לוחצים על auth_callback ברשימת Cloud Functions ועוברים לכרטיסייה Trigger (טריגר).

מעתיקים את כתובת ה-URL שבדף. חוזרים לדף Cloud Functions ולוחצים על auth_init ברשימת Cloud Functions. בכרטיסייה כללי, לוחצים על עריכה. לוחצים על Environmental variables, networking, timeouts and more (משתני סביבה, רשת, פסק זמן ועוד) ומחליפים את הערך של GOOGLE_CALLBACK_URL בכתובת ה-URL שהעתקתם.

לוחצים על פריסה כדי להחיל את השינויים. חוזרים על התהליך ומעדכנים גם את auth_callback.

לבסוף, פותחים את תפריט הניווט השמאלי ולוחצים על APIs & Services (ממשקי API ושירותים) > Domain verification (אימות דומיין). כדי להוסיף דומיין מורשה, לוחצים על הוספת דומיין. לדוגמה, אם כתובת ה-URL שהעתקתם קודם נראית כך:

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

צריך להוסיף את הדומיין הבא כדומיין מורשה:

us-central1-my-project.cloudfunctions.net

לוחצים על הוספת דומיין כדי לאשר.

חוזרים לדף Credentials. לוחצים על השם של לקוח 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 ובתפריט הניווט השמאלי לוחצים על Pub/Sub > Topics. לוחצים על יצירת נושא. מקלידים את שם הנושא, למשל gmail-watch, ולוחצים על יצירה. בנוסף, צריך לתת ל-Gmail הרשאה לשלוח הודעות לנושא Pub/Sub: לוחצים על תפריט ההקשר של הנושא שיצרתם (שלוש נקודות אנכיות) ובוחרים באפשרות הרשאות. לוחצים על הוספת חברים, מציינים את gmail-api-push@system.gserviceaccount.com כחבר חדש ומקצים לו את התפקיד Pub/Sub > פרסום הודעות ב-Pub/Sub. לבסוף, לוחצים על שמירה כדי להחיל את השינויים.

מעדכנים את פונקציה של Cloud Functions auth_callback כדי לציין באיזה נושא Pub/Sub להשתמש. בתפריט הניווט הימני, לוחצים על Cloud Functions ובוחרים באפשרות auth_callback ברשימת Cloud Functions. בכרטיסייה כללי, לוחצים על עריכה. לוחצים על עוד ומחליפים את הערך של PUBSUB_TOPIC בשם של נושא Pub/Sub שיצרתם. לוחצים על שמירה כדי להחיל את השינויים.

עכשיו אפשר לאשר ולהגדיר התראות פוש ב-Gmail. מחכים עד שהשינויים החדשים יסתיימו, ואז חוזרים לדף Cloud Functions, בוחרים באפשרות auth_init ברשימת הפונקציות Cloud ועוברים לכרטיסייה Trigger. לוחצים על כתובת ה-URL, ותועברו לדף כניסה באמצעות חשבון Google:

נכנסים באמצעות חשבון Gmail שבבעלותכם. כל הודעה חדשה שתגיע לתיבת הדואר הנכנס של החשבון תפעיל התראה. אחרי הכניסה לחשבון, יופיע הדף הבא:

לוחצים על אישור כדי לאשר את הגישה. auth_callback ישלים את תהליך ההרשאה, ישמור את אסימוני הגישה ויגדיר עבורכם התראות פוש ב-Gmail. בסיום התהליך, ההודעה Successfully set up Gmail push notifications תופיע בדפדפן.

ב-codelab הזה נעשה שימוש בחבילה @google-cloud/express-oauth2-handlers כדי לבצע אוטומציה של תהליך ההרשאה. מידע נוסף זמין במאגר שלו ב-GitHub.

6. עיבוד הודעות נכנסות

כמו שציינו קודם, כל מי שמנוי לנושא Pub/Sub שיצרתם יקבל התראות כשהודעות חדשות יגיעו לתיבת הדואר הנכנס שלכם. ‫pubsub/index.js מציין פונקציה של Cloud Functions‏, watchGmailMessages, שאחרי הפריסה שלה כמנוי לנושא, תקרא את ההודעות החדשות, תסווג את התמונות המצורפות ותייצא את הסיווגים האלה לגיליון אלקטרוני ב-Google Sheets.

כדי לבדוק את הקוד, פותחים את הקובץ pubsub/index.js ב-Cloud Shell Code Editor.

שליפת הודעות

התראות פוש ב-Gmail כוללות את כתובת האימייל שאליה משויכת ההתראה, ומזהה היסטוריה. לצורך פשטות, ב-Codelab הזה פשוט תבקשו מ-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 כדי להוסיף הערות לתמונה. ב-codelab הזה, תבקשו מ-Cloud Vision API לסווג את התמונה ולהחזיר מספר תגי תמונה. לדוגמה, אם תספקו תמונה של שמיים כחולים, יכול להיות ש-Cloud Vision API יחזיר את התגים blue,‏ sky ו-nature.

‫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 Sheets

watchGmailMessages מייצא את תוצאות הניתוח הזה לגיליון אלקטרוני ב-Google Sheets. הוא כולל את שם השולח, את שם הקובץ המצורף ותגים של קבצים מצורפים של תמונות (אם יש כאלה).

קודם יוצרים גיליון אלקטרוני ב-Google Sheets. פותחים את Google Sheets ולוחצים על התבנית ריק בקטע יצירה של גיליון אלקטרוני חדש. מעתיקים את המזהה של הגיליון. לדוגמה, אם הכתובת בדפדפן נראית כך:

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 מתחבר ל-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 Code Editor, פותחים את הקובץ 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 Functions:

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 Sheets יתעדכן אוטומטית במידע שסיפקתם.