‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

עורך הקוד של Cloud Shell ייפתח בחלון חדש.

הורדת הקוד

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

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

cd gcf-gmail-codelab

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

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

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

המשתמש מגדיר התראות Push ב-Gmail: בכל פעם שהודעה חדשה מגיעה לתיבת הדואר הנכנס, Gmail ישלח התראה ל-Cloud Pub/Sub.
שירות Cloud Pub/Sub מעביר את ההתראה על ההודעה החדשה אל Google 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 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, מעדכנים את 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 יתעדכן אוטומטית במידע שסיפקתם.