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

יציאה לחופשה עם אפליקציה של Google Chat

1. מבוא

אפליקציות ל-Google Chat מאפשרות לשלב שירותים ומשאבים ישירות ב-Chat, כך שהמשתמשים יכולים לקבל מידע ולבצע פעולות בלי לצאת מהשיחה.

ב-codelab הזה תלמדו איך ליצור אפליקציית Chat – "אפליקציית Chat לניהול נוכחות" – שקובעת הודעות אוטומטיות על חופשה ב-Gmail ומתזמנת פגישות ביומן Google. באמצעות יצירת אפליקציית צ'אט לדיווח נוכחות ב-Google Apps Script, תוכלו לגשת בקלות לשירותים אחרים של Google כמו Drive,‏ Gmail, יומן, Docs,‏ Sheets ועוד.

מה תלמדו

איך מוסיפים פונקציות לטיפול באירועים שמופעלים ב-Chat
איך מנתחים אובייקטים של אירועים שנשלחים מ-Chat
איך משיבים ל-Chat באמצעות תשובות בפורמט כרטיס
איך מגדירים פעולות מותאמות אישית ללחיצות על כפתורים בכרטיסים ומגיבים להן

מה נדרש

גישה לאינטרנט ולדפדפן אינטרנט.
חשבון Google Workspace עם גישה ל-Google Chat.
ידע בסיסי ב-JavaScript – Google Apps Script תומך רק ב-JavaScript.

2. קבלת קוד לדוגמה

כדי לראות את הקוד של כל שלב בדוגמה הזו, אפשר להוריד קובץ ZIP או לשכפל את מאגר GitHub.

התיקיות step-NN שבקטע solutions/attendance-chat-app מכילות את מצב הסיום הרצוי של כל שלב ב-codelab הזה. הן מופיעות שם לצורך השוואה.

הורדת הקוד

כדי להוריד את הקוד של ה-codelab הזה, לוחצים על הלחצן הבא:

מחלצים את קובץ ה-ZIP שהורד. הפעולה הזו תחלץ תיקיית בסיס (apps-script-samples), שמכילה תיקייה אחת לכל שלב ב-Codelab הזה, בתיקייה solutions/attendance-chat-app.

שיבוט המאגר ב-GitHub

כדי לשכפל את מאגר GitHub של ה-codelab הזה, מריצים את הפקודה הבאה:

git clone https://github.com/googleworkspace/apps-script-samples

3. יצירת רכיבי handler לאירועים ב-Google Chat

יצירת פרויקט Apps Script

כדי ליצור פרויקט Apps Script, פועלים לפי השלבים הבאים:

עוברים אל script.new.
לוחצים על פרויקט ללא שם.
משנים את השם של הסקריפט ל-Attendance Chat app ולוחצים על Rename (שינוי שם).

אירועים ב-Google Chat

רוב האינטראקציות של Apps Script עם Chat מבוססות על אירועים. האינטראקציה בין המשתמש, אפליקציית Chat ו-Chat מתרחשת בדרך כלל ברצף הבא:

משתמש יוזם פעולה, כמו הוספת אפליקציית Chat למרחב, התחלת צ'אט ישיר עם אפליקציית Chat או הסרת אפליקציית Chat ממרחב.
הפעולה מעלה אירוע שמיועד לאפליקציית Chat ב-Chat.
‫Chat מפעיל את הגורם המטפל באירועים התואם שמוגדר בסקריפט של אפליקציית Chat.

הצ'אט מעלה 4 אירועים שהאפליקציה יכולה להאזין להם:

‫ADDED_TO_SPACE: האירוע הזה מתרחש כשמשתמש אנושי מוסיף אפליקציית Chat למרחב או לצ'אט ישיר. ב-Apps Script, מגדירים פונקציה onAddToSpace() לטיפול באירוע הזה.
‫REMOVED_FROM_SPACE: האירוע הזה מתרחש כשמשתמש מסיר את האפליקציה ל-Chat ממרחב או מצ'אט ישיר. האירוע הזה לא מפרסם תשובה בחזרה ב-Chat. ב-Apps Script, מגדירים פונקציה לטיפול באירוע הזה.onRemoveFromSpace()
‫MESSAGE: האירוע הזה מתרחש כשמשתמש שולח הודעה לאפליקציית Chat, ישירות בצ'אט אישי או בתיוג ב-@ במרחב. ב-Apps Script, מגדירים פונקציית onMessage() כדי להגיב לאירוע הזה.
‫CARD_CLICKED: האירוע הזה מתרחש כשהמשתמש לוחץ על לחצן שהוקצתה לו פעולה מותאמת אישית. ב-Apps Script, מגדירים פונקציית onCardClick() כדי להגיב לאירוע הזה.

מחליפים את התוכן של הקובץ Code.gs בקוד הבא שמגדיר את ה-handlers לאירועים ADDED_TO_SPACE ו-REMOVE_FROM_SPACE. (בהמשך ה-codelab הזה תוסיפו handlers לאירועים MESSAGE ו-CARD_CLICKED).

Code.gs

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onAddToSpace(event) {
  console.info(event);
  var message = 'Thank you for adding me to ';
  if (event.space.type === 'DM') {
    message += 'a DM, ' + event.user.displayName + '!';
  } else {
    message += event.space.displayName;
  }
  return { text: message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 * @param {object} event the event object from Google Chat
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onRemoveFromSpace(event) {
  console.info(event);
  console.log('Chat app removed from ', event.space.name);
}

4. פרסום ובדיקה של אפליקציית Chat

עדכון קובץ המניפסט של הסקריפט

כדי לפרסם את האפליקציה ב-Chat, צריך לעדכן את קובץ המניפסט של הסקריפט.

לוחצים על Project Settings (הגדרות הפרויקט) .
מסמנים את התיבה הצגת קובץ המניפסט 'appsscript.json' בעורך.
לוחצים על עריכה .
לוחצים על הקובץ appsscript.json.
מוסיפים את השורה "chat": {} לקובץ המניפסט.

קובץ המניפסט צריך להיות דומה לדוגמה הבאה.

appsscript.json

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "chat": {}
}

יצירת פרויקט של Google Cloud

כדי להריץ ולבדוק את אפליקציית Chat, צריך ליצור פרויקט ב-Google Cloud, להפעיל ולהגדיר את Chat API ולפרסם את אפליקציית Chat בארגון Google Workspace.

ב-Google Cloud Console, עוברים אל תפריט > IAM & Admin > Create a Project.
בשדה Project Name (שם הפרויקט), מזינים שם תיאורי.
אם מוצגת בקשה, בוחרים את הארגון ואת החשבון לחיוב.
לוחצים על יצירה.
כשהפרויקט ייווצר, תופיע הודעה בפינה השמאלית העליונה של הדף. לוחצים על הערך Create Project: <Project name> כדי לפתוח את הפרויקט.
לוחצים על סמל התפריט > APIs & Services > Credentials.
לוחצים על מסך הסכמה ל-OAuth.
בשדה שם האפליקציה, מזינים Attendance Chat app.
אם תתבקשו, הזינו את כתובת האימייל של התמיכה במשתמשים ואת פרטי הקשר של המפתח.
לוחצים על שמירה והמשך.
לוחצים על סמל ההגדרות והכלים > הגדרות הפרויקט.
מעתיקים את מספר הפרויקט.
חוזרים אל עורך סקריפט של Apps ולוחצים על Project Settings (הגדרות הפרויקט).
בקטע פרויקט Google Cloud Platform (GCP)‎, לוחצים על שינוי הפרויקט.
לוחצים על מספר פרויקט GCP ומזינים את מספר הפרויקט.
לוחצים על הגדרת פרויקט.

פרסום האפליקציה ב-Chat

כדי לפרסם את אפליקציית Chat ב-Google Chat:

בעורך Apps Script, לוחצים על פריסה > פריסה חדשה.
לצד Select type (בחירת סוג), לוחצים על Enable deployment types (הפעלה של סוגי פריסה) .
בוחרים באפשרות Add-on (תוסף) ולוחצים על Deploy (פריסה).
מעתיקים את מזהה הפריסה ולוחצים על סיום.
במסוף Google Cloud, לוחצים על סמל התפריט > APIs & services > Library.
מחפשים את Google Chat API. בוחרים את ה-API מרשימת התוצאות.
בדף Google Chat API, לוחצים על Enable (הפעלה).
אחרי שמפעילים את ה-API, לוחצים על הגדרה. מתעלמים מהודעות שמבקשות ליצור פרטי כניסה.
בדף Configuration, מבצעים את הפעולות הבאות:

בשדה שם האפליקציה, מזינים Attendance Chat app.
בשדה כתובת URL של אווטאר, מזינים https://goo.gl/kv2ENA.
בשדה Description (תיאור), מזינים Apps Script codelab Chat app (אפליקציית Chat של Apps Script codelab).
בקטע פונקציונליות, בוחרים באפשרות קבלת הודעות בצ'אט.
בקטע Connection settings (הגדרות חיבור), בוחרים באפשרות Apps Script project (פרויקט Apps Script) ומדביקים את מזהה הפריסה של הסקריפט בתיבת הטקסט.
בקטע הרשאות, בוחרים באפשרות אנשים וקבוצות ספציפיים בדומיין. בתיבת הטקסט שמתחת לתפריט הנפתח, מזינים את כתובת האימייל שמשויכת לארגון שלכם ב-Google Workspace.
לוחצים על שמירה.

אחרי ששומרים את השינויים, צריך לוודא שבסטטוס בדף Google Chat API מופיע סטטוס האפליקציה כפעילה – זמינה למשתמשים.

בדיקת אפליקציית Chat

כדי לבדוק את האפליקציה ב-Google Chat:

פותחים את Google Chat.
שולחים הודעה ישירה חדשה לאפליקציית Chat בלחיצה על סמל התחלת הצ'אט > חיפוש אפליקציות.
בדף 'חיפוש אפליקציות', מחפשים את אפליקציית Attendance Chat.
לצד אפליקציית הצ'אט של נוכחות, לוחצים על הוספה > צ'אט.

כשנפתח הצ'אט הישיר, אמורה להופיע הודעה מאפליקציית Chat שבה כתוב תודה על הוספת האפליקציה לצ'אט הישיר, כמו שמוצג בתמונה הבאה.

5. הגדרת תגובה בפורמט כרטיס

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

תשובות בכרטיס

‫Google Chat תומך בשימוש בכרטיסים לתשובות. כרטיסים הם מאגרים חזותיים שמאפשרים לקבץ יחד קבוצות של ווידג'טים של ממשק משתמש. בכרטיסים אפשר להציג כותרות, פסקאות טקסט, קבוצות של לחצנים, תמונות וטקסט של צמדי מפתח/ערך. האפליקציה יכולה להגדיר כרטיס אחד או יותר בתגובת ה-JSON שלה ל-Google Chat, ואז המערכת מתרגמת את התגובה לרכיבי ממשק המשתמש המתאימים.

בתמונה הבאה מוצג כרטיס תגובה עם שלושה קטעים, שכולל כותרת, ווידג'ט של צמד מפתח/ערך, ווידג'ט של תמונה ולחצן טקסט.

כדי להשיב להודעות של משתמשים באמצעות כרטיס, מוסיפים את הקוד הבא לקובץ Code.gs של אפליקציית Chat.

Code.gs

const DEFAULT_IMAGE_URL = 'https://goo.gl/bMqzYS';
const HEADER = {
  header: {
    title : 'Attendance Chat app',
    subtitle : 'Log your vacation time',
    imageUrl : DEFAULT_IMAGE_URL
  }
};

/**
 * Creates a card-formatted response.
 * @param {object} widgets the UI components to send
 * @return {object} JSON-formatted response
 */
function createCardResponse(widgets) {
  return {
    cards: [HEADER, {
      sections: [{
        widgets: widgets
      }]
    }]
  };
}

/**
 * Responds to a MESSAGE event triggered
 * in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return JSON-formatted response
 */
function onMessage(event) {
  const userMessage = event.message.text;

  const widgets = [{
    "textParagraph": {
      "text": "You said: " + userMessage
    }
  }];

  return createCardResponse(widgets);
}

הפונקציה onMessage(), שנוספה בשלב הזה, קוראת את ההודעה המקורית של המשתמש ויוצרת תגובה כווידג'ט פשוט של TextParagragh. הפונקציה onMessage() קוראת לפונקציה createCardResponse(), שמציבה את הווידג'ט TextParagraph בקטע של כרטיס יחיד. אפליקציית Chat מחזירה את אובייקט ה-JavaScript שנבנה עם תגובת הכרטיס בחזרה אל Google Chat.

בדיקת אפליקציית Chat

כדי לבדוק את האפליקציה הזו, חוזרים לצ'אט הישיר עם האפליקציה ב-Google Chat ומקלידים הודעה (כל הודעה תתאים).

שימו לב שפונקציית הטיפול באירועים onMessage() מנתחת את אובייקט האירוע שמועבר אליה על ידי Google Chat כדי לחלץ את ההודעה המקורית של המשתמש. אפשר גם לקבל סוגים אחרים של מידע על האירוע, כולל שם המשתמש שיזם את האירוע, כתובת האימייל שלו, שם המרחב שבו התרחש האירוע ועוד.

מידע נוסף על המבנה של אובייקטים של אירועים שנשלחים מ-Google Chat זמין במאמר בנושא פורמטים של אירועים.

6. תגובה לקליקים על כפתורים בכרטיסים

בשלב הקודם, אפליקציית Chat הגיבה להודעה ממשתמש – אירוע MESSAGE – בכרטיס פשוט שהכיל ווידג'ט TextParagragh. בשלב הזה יוצרים תגובה שכוללת לחצנים, וכל לחצן מוגדר עם פעולה מותאמת אישית.

כרטיסים אינטראקטיביים

תשובות בכרטיסים יכולות להכיל אחד משני סוגי לחצנים: ווידג'טים של לחצני טקסט, שמציגים לחצנים עם טקסט בלבד, ווידג'טים של לחצני תמונה, שמציגים לחצן עם סמל פשוט או תמונה ללא טקסט. ווידג'טים מסוג TextButton ו-ImageButton תומכים באחת משתי התנהגויות onClick (כפי שמוגדר בתגובת ה-JSON שנשלחת בחזרה ל-Google Chat): openLink או action. כפי שהשם מרמז, openLink פותח קישור שצוין בכרטיסייה חדשה בדפדפן.

אובייקט action מציין פעולה מותאמת אישית שהלחצן יבצע. אפשר לציין כמה ערכים שרירותיים באובייקט הפעולה, כולל actionMethodName ייחודי וקבוצה של צמדי פרמטרים של מפתח / ערך.

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

מחליפים את הפונקציה onMessage() בקובץ Code.gs בקוד הבא. הקוד הזה יוצר 2 לחצנים, הגדרת סטטוס 'בחופשה' ב-Gmail וחסימת יום ביומן, בכרטיס שנשלח ל-Google Chat.

Code.gs

const REASON = {
  SICK: 'Out sick',
  OTHER: 'Out of office'
};
/**
 * Responds to a MESSAGE event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 */
function onMessage(event) {
  console.info(event);
  const reason = REASON.OTHER;
  const name = event.user.displayName;
  const userMessage = event.message.text;

  // If the user said that they were 'sick', adjust the image in the
  // header sent in response.
  if (userMessage.indexOf('sick') > -1) {
    // Hospital material icon
    HEADER.header.imageUrl = 'https://goo.gl/mnZ37b';
    reason = REASON.SICK;
  } else if (userMessage.indexOf('vacation') > -1) {
    // Spa material icon
    HEADER.header.imageUrl = 'https://goo.gl/EbgHuc';
  }

  const widgets = [{
    textParagraph: {
      text: 'Hello, ' + name + '.<br/>Are you taking time off today?'
    }
  }, {
    buttons: [{
      textButton: {
        text: 'Set vacation in Gmail',
        onClick: {
          action: {
            actionMethodName: 'turnOnAutoResponder',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }, {
      textButton: {
        text: 'Block out day in Calendar',
        onClick: {
          action: {
            actionMethodName: 'blockOutCalendar',
            parameters: [{
              key: 'reason',
              value: reason
            }]
          }
        }
      }
    }]
  }];
  return createCardResponse(widgets);
}

כדי לטפל באירוע CARD_CLICKED, צריך להוסיף את הפונקציה onCardClick() לסקריפט של אפליקציית Chat. מוסיפים את הקוד הבא שמגדיר את הפונקציה onCardClick() Code.gs.

Code.gs

/**
 * Responds to a CARD_CLICKED event triggered in Google Chat.
 * @param {object} event the event object from Google Chat
 * @return {object} JSON-formatted response
 * @see https://developers.google.com/workspace/chat/receive-respond-interactions
 */
function onCardClick(event) {
  console.info(event);
  let message = '';
  const reason = event.action.parameters[0].value;
  if (event.action.actionMethodName == 'turnOnAutoResponder') {
    turnOnAutoResponder(reason);
    message = 'Turned on vacation settings.';
  } else if (event.action.actionMethodName == 'blockOutCalendar') {
    blockOutCalendar(reason);
    message = 'Blocked out your calendar for the day.';
  } else {
    message = "I'm sorry; I'm not sure which button you clicked.";
  }
  return { text: message };
}

בתגובה לקליקים של משתמשים, אפליקציית Chat מבצעת עכשיו אחד משני דברים: היא מגדירה את הודעת החופשה של המשתמש ב-Gmail להודעה 'לא בעבודה', או שהיא מתזמנת פגישה לכל היום ביומן של המשתמש. כדי לבצע את המשימות האלה, האפליקציה קוראת לשירות המתקדם של Gmail ולשירות היומן.

מוסיפים את הקוד הבא לסקריפט כדי לשלב את אפליקציית Chat עם Gmail והיומן.

Code.gs

const ONE_DAY_MILLIS = 24 * 60 * 60 * 1000;
/**
 * Turns on the user's vacation response for today in Gmail.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function turnOnAutoResponder(reason) {
  let currentTime = (new Date()).getTime();
  Gmail.Users.Settings.updateVacation({
    enableAutoReply: true,
    responseSubject: reason,
    responseBodyHtml: "I'm out of the office today; will be back on the next business day.<br><br><i>Created by Attendance Chat app!</i>",
    restrictToContacts: true,
    restrictToDomain: true,
    startTime: currentTime,
    endTime: currentTime + ONE_DAY_MILLIS
  }, 'me');
}

/**
 * Places an all-day meeting on the user's Calendar.
 * @param {string} reason the reason for vacation, either REASON.SICK or REASON.OTHER
 */
function blockOutCalendar(reason) {
  CalendarApp.createAllDayEvent(reason, new Date(), new Date(Date.now() + ONE_DAY_MILLIS));
}

לבסוף, צריך להפעיל את השירות המתקדם של Gmail בפרויקט. כדי להפעיל את Gmail API:

בסביבת העריכה של Apps Script, לצד Services (שירותים), לוחצים על סמל הוספת שירות .
בוחרים באפשרות Gmail API.
לוחצים על Google Cloud Platform API Dashboard (מרכז הבקרה של ה-API של Google Cloud Platform) כדי לפתוח את מסוף Google Cloud.
לוחצים על Enable APIs and Services.
מחפשים את Gmail API ולוחצים על Gmail API.
בדף Gmail API, לוחצים על Enable (הפעלה).

בדיקת אפליקציית Chat

כדי לבדוק את הגרסה הזו של אפליקציית Chat, פותחים את הצ'אט הישיר שהתחלתם בשלבים הקודמים ב-Google Chat ומקלידים I'm going on vacation (אצא לחופשה). האפליקציה אמורה להגיב בכרטיס שדומה לתמונה שלמטה.

הערה: אם תתבקשו לתת גישה לאפליקציה, יכול להיות שתצטרכו להקליד את ההודעה שוב.

7. מעולה!

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

מה נכלל

יצירה ופרסום של אפליקציה ל-Google Chat באמצעות Apps Script
השיב להודעות משתמשים בתשובה פשוטה
הייתה אינטראקציה עם שירותים אחרים של Google Workspace בשם המשתמש דרך אפליקציית Chat

יציאה לחופשה עם אפליקציה של Google Chat קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

1. מבוא

מה תלמדו

מה נדרש

2. קבלת קוד לדוגמה

הורדת הקוד

שיבוט המאגר ב-GitHub

3. יצירת רכיבי handler לאירועים ב-Google Chat

יצירת פרויקט Apps Script

אירועים ב-Google Chat

Code.gs

4. פרסום ובדיקה של אפליקציית Chat

עדכון קובץ המניפסט של הסקריפט

appsscript.json

יצירת פרויקט של Google Cloud

פרסום האפליקציה ב-Chat

בדיקת אפליקציית Chat

5. הגדרת תגובה בפורמט כרטיס

תשובות בכרטיס

Code.gs

בדיקת אפליקציית Chat

6. תגובה לקליקים על כפתורים בכרטיסים

כרטיסים אינטראקטיביים

Code.gs

Code.gs

Code.gs

בדיקת אפליקציית Chat

7. מעולה!

מה נכלל

מידע נוסף

יציאה לחופשה עם אפליקציה של Google Chat