דף זה תורגם על ידי Cloud Translation API.

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

1. מבוא

מיליארדי עסקים ואנשים פרטיים משתמשים ב-Gmail ובשירותים אחרים של G Suite כדי לתקשר ולעבד נתונים. Google מציעה ממשקי API של G Suite שיעזרו לכם לגשת למידע בשירותים האלה באופן פרוגרמטי. תוכלו להשתמש בממשקי ה-API כדי להפוך בקלות את תהליך העבודה היומיומי שלכם לאוטומטי. בשיעור ה-Lab הזה תפתחו תוסף Gmail חזק שמסווג באופן אוטומטי אימיילים בהודעות נכנסות ושומר את הקטגוריות האלה בגיליון אלקטרוני ב-Google Sheets. התוסף הזה ישתמש בממשקי 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
Google Cloud Pub/Sub
Google Cloud Vision API
מאגר הנתונים של Google Cloud
ממשק ה-API של Gmail
Google Sheets API

פונקציות Google Cloud

Google Cloud Functions היא פלטפורמת שרת ללא שרת (serverless Functions) של 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

Google Cloud Datastore הוא מסד נתונים ללא שרת (serverless) שניתן להרחבה ולהפצה.

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

בשיעור ה-Lab הזה תוכלו להשתמש בכל מיקום של מסד נתונים. לוחצים על Create Database כדי להפעיל את Google Cloud Datastore. עשויות להימשך כמה דקות.

Google Cloud Vision

Google Cloud Vision API הוא שירות מתקדם של למידת מכונה שמשתמש במודלים שעברו אימון מראש כדי להפיק תובנות מהתמונות שלכם.

בהמשך מפורטות הוראות להפעלה של Google Cloud Vision API.

הפעלה של Gmail API, Google Sheets API ו-Google Cloud Vision API

שוב, פותחים את סרגל הצד של הניווט ומחפשים את האפשרות APIs & שירותים. לוחצים על ספרייה. בקטע חיפוש ממשקי API השדה 'שירותים', הקלד ב-Gmail. בתוצאות החיפוש, בוחרים באפשרות Gmail API ולוחצים על הפעלה.

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

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

פתיחת Google Cloud Shell

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

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

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

לוחצים על הלחצן Launch code Editor (השקת עורך קוד) כדי להפעיל את Cloud Shell 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 Code Editor.

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 Functions כדי לקרוא אימיילים באופן אוטומטי, צריך לאשר את הגישה שלה ל-Gmail. יהיה עליך לרשום לקוח OAuth ב-Google וליצור מזהה לקוח משויך.

רישום לקוח OAuth

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

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

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

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

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

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

בקוד לדוגמה, המאפיין 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 Functions עשויה להימשך כמה דקות. אם מתבקשים, נותנים ל-Cloud SDK הרשאה להתקין פקודות בטא.

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

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

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

לבסוף, פותחים את תפריט הניווט השמאלי ולוחצים על APIs & שירותים > אימות הדומיין כדי להוסיף דומיין מורשה, לוחצים על הוספת דומיין. לדוגמה, אם כתובת ה-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 מורשה. לדוגמה, אם כתובת האתר שלכם נראית כך:

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

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

עכשיו אתה מוכן לאשר ולהגדיר התראות ב-Gmail. ממתינים עד שהשינויים החדשים יושלמו, ואז חוזרים לדף Cloud Functions, בוחרים באפשרות auth_init ברשימת Cloud Functions ועוברים לכרטיסייה 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 Functions עשויה להימשך מספר שניות.

7. רוצה לנסות?

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