המרת אפליקציית Google Chat אינטראקטיבית לתוסף ל-Google Workspace

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

ההמרה מאפשרת לאפליקציית Google Chat להשתמש במסגרת של תוספים ל-Google Workspace, וכך נפתחות אפשרויות חדשות לשילוב ולתכונות ב-Google Chat וב-Google Workspace. לדוגמה, אתם יכולים להפיץ תוסף אחד ל-Google Workspace דרך Google Workspace Marketplace, שמרחיב את אפליקציות Chat לצד אפליקציות מארחות אחרות של Google Workspace, כמו Gmail, ‏ יומן ו-Docs.

מגבלות

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

שלב 1: מעתיקים את הקוד של אפליקציית Google Chat הקיימת

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

Apps Script

  1. פותחים פרויקט קיים של Google Apps Script באפליקציית Google Chat.
  2. בצד ימין, לוחצים על סקירה כללית .
  3. בצד שמאל, לוחצים על יצירת עותק .
  4. בצד ימין, לוחצים על הגדרות הפרויקט .
  5. בקטע פרויקט ב-Google Cloud, לוחצים על שינוי הפרויקט.
  6. מזינים את מספר הפרויקט שמשויך לפרויקט הקיים של אפליקציית Google Chat.
  7. לוחצים על הגדרת פרויקט.

HTTP

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

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

שלב 2: משנים את הקוד שהועתק

תוספים ל-Google Workspace שמרחיבים את השימוש ב-Google Chat משתמשים במבנים שונים של בקשות ותגובות בהשוואה לאפליקציות ל-Google Chat שנבנו באמצעות אירועי אינטראקציה עם Chat API. צריך לעדכן את הקוד כדי להשתמש בתוסף Google Workspace‏ EventObject במקום ב-Event של Google Chat API לבקשות ולתגובות. אפשר להשתמש במדריך להמרת קוד כדי לשנות את הקוד.

שלב 3: הפעלת ההגדרה של תוסף Google Workspace למשתמשי בדיקה

משתמשים במסוף Google Cloud כדי להגדיר את ההגדרות של התוסף ל-Google Workspace עבור אפליקציית Google Chat:

  1. נכנסים לדף ההגדרות של Google Chat API במסוף Google Cloud.

    מעבר לדף ההגדרות של Google Chat API

  2. בקטע תכונות אינטראקטיביות, מפעילים את האפשרות הפעלת תכונות אינטראקטיביות.

  3. בקטע המרת התוסף לתוסף ל-Google Workspace, לוחצים על המרת התוסף.

  4. מפעילים את האפשרות הפעלת הגדרות של תוספים.

  5. בקטע חשיפה, מוסיפים את כתובות האימייל של המשתמשים לבדיקה.

  6. אם צריך, מעדכנים את הגדרות החיבור עם כתובת ה-URL של נקודת הפריסה או עם מזהה הפריסה של Apps Script של קוד האפליקציה של Google Chat שהעתקתם ושיניתם בשלב 2.

  7. לוחצים על שמירה ובדיקה.

שלב 4: בדיקת האפליקציה שהומרה

בודקים ביסודיות את הפונקציונליות של התוסף ל-Google Workspace באמצעות חשבונות המשתמשים לבדיקה שהוגדרו בשלב 3. בודקים את כל התכונות והאינטראקציות.

שלב 5: משלימים את ההמרה לכל המשתמשים

אחרי שמוודאים שהתוסף המומר ל-Google Workspace פועל בצורה תקינה, אפשר להפוך אותו לזמין לכל המשתמשים.

  1. נכנסים לדף ההגדרות של Google Chat API במסוף Google Cloud.

    מעבר לדף ההגדרות של Google Chat API

  2. בקטע תכונות אינטראקטיביות, לוחצים על המרת התכונה לתוסף. תיפתח חלונית צדדית.

  3. בחלונית הצדדית, לוחצים על המרת התוסף.

  4. מקלידים את מזהה הפרויקט ולוחצים על המרה.

אפליקציית Google Chat היא עכשיו תוסף ל-Google Workspace שמרחיב את היכולות של Google Chat.

אופציונלי: ניקוי או שחרור של משאבים לא בשימוש ב-Google Cloud

אחרי שממירים את אפליקציית Google Chat לתוסף ל-Google Workspace, אפשר להשבית את המשאבים שבהם השתמשה אפליקציית Google Chat שכבר לא בשימוש, כדי להימנע מחיובים בחשבון Google Cloud.

מדריך להמרת קוד

בקטע הזה מפורט המיפוי בין הפורמט של האינטראקציה עם Google Chat API‏ Event לבין הפורמט של התוסף ל-Google Workspace‏ EventObject.

מיפוי בקשות

בטבלה הבאה מוצג מיפוי של השדות ב-Google Chat API‏ Event לשדות התואמים בתוסף ל-Google Workspace‏ EventObject.

השדה Google Chat API interaction Event השדה EventObject של תוסף ל-Google Workspace הערות
action.actionMethodName לא רלוונטי באינטראקציות עם כרטיסים, אפשר להעביר את שם השיטה כפרמטר ב-commonEventObject.parameters. מידע נוסף זמין במאמר פתיחת תיבת דו-שיח ראשונית.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 הנתונים האלה זמינים במטענים שונים בהתאם לסוג האירוע.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 הנתונים האלה זמינים במטענים שונים בהתאם לסוג האירוע.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 הנתונים האלה זמינים במטענים שונים בהתאם לסוג האירוע.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 הנתונים האלה זמינים במטענים שונים בהתאם לסוג האירוע.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 הנתונים האלה זמינים במטענים שונים בהתאם לסוג האירוע.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 הנתונים האלה זמינים במטענים שונים בהתאם לסוג האירוע.
token לא רלוונטי האימות מתבצע באופן שונה, כפי שמתואר במאמר בקשת אימות לאפליקציות HTTP.
type לא רלוונטי אפשר להסיק את סוג האירוע מהטריגר.
user chat.user

בקשת מיפוי לפי תרחיש לדוגמה

בטבלה הבאה מוצגים ההבדלים במטענים הייעודיים (payloads) של בקשות לתרחישי שימוש נפוצים בין אפליקציות ל-Google Chat שנבנו באמצעות אירועי אינטראקציה עם Chat API לבין תוספים ל-Google Workspace שמרחיבים את Google Chat.

תרחיש לדוגמה מטען ייעודי (payload) של אינטראקציה עם Chat API‏ Event המטען הייעודי (payload) של תוסף ל-Google Workspace‏ EventObject
האפליקציה נוספה למרחב 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
הסרת האפליקציה מהמרחב 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
משתמש מתייג אפליקציה באמצעות @ 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
משתמש מתייג אפליקציה כדי להוסיף אותה למרחב צריך לטפל בהזמנה אחת מ-Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 צריך לטפל בשתי בקשות מ-Google Chat.

הבקשה הראשונה:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

בקשה שנייה:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
פקודה דרך שורת הפקודות 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
פקודה דרך שורת הפקודות להוספת אפליקציה למרחב צריך לטפל בהזמנה אחת מ-Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 צריך לטפל בשתי בקשות מ-Google Chat.

הבקשה הראשונה:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

בקשה שנייה:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
משתמש לוחץ על לחצן בכרטיס או בתיבת דו-שיח 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

באירועים של תיבת דו-שיח, common.formInputs מכיל ערכי ווידג'טים. דוגמה ל-Google Apps Script:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

באירועים של תיבת דו-שיח, commonEventObject.formInputs מכיל ערכי ווידג'טים. דוגמה ל-Google Apps Script:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
משתמש שולח מידע בכרטיס של דף הבית של האפליקציה 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
משתמש מפעיל פקודה לאפליקציה באמצעות פקודה מהירה 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
תצוגה מקדימה של קישור 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
משתמש מעדכן ווידג'ט בהודעה או בתיבת דו-שיח של כרטיס 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

מיפוי התגובות לפי תרחיש שימוש

תוספים ל-Google Workspace שמרחיבים את Google Chat מחזירים פעולות במקום אובייקט Message. בטבלה הבאה מפורטים סוגי התגובות של Google Chat API‏ Message והפעולות המקבילות שלהם בתוספים ל-Google Workspace.

תרחיש לדוגמה תגובה של Google Chat API Message תגובה של תוסף ל-Google Workspace פעולה ב-Chat
יצירת הודעה במרחב שאליו נכנסים 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

הערך actionResponse הוא אופציונלי. מידע נוסף על תגובה לפקודות סלאש

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

מידע נוסף זמין במאמר שליחת הודעה.
עריכת הודעה 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

מידע נוסף זמין במאמר בנושא עדכון הודעה (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

מידע נוסף זמין במאמר בנושא עדכון הודעה (תוספים).
תצוגה מקדימה של קישור 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

מידע נוסף זמין במאמר בנושא תצוגה מקדימה של קישור (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

מידע נוסף זמין במאמר בנושא תצוגה מקדימה של קישור(תוספים).
פתיחת תיבת דו-שיח ראשונית 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

מידע נוסף זמין במאמר בנושא פתיחת תיבת דו-שיח (Chat).

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
הכרטיס שדוחפים יכול להכיל ווידג'טים עם onClick פעולות. בתוספים ל-Google Workspace עם HTTP, מגדירים את הפעולות האלה כדי לקרוא לנקודת קצה של פונקציה: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

מידע נוסף זמין במאמר פתיחת תיבת דו-שיח (תוספים).
סגירה של תיבת דו-שיח 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

מידע נוסף זמין במאמר סגירת תיבת דו-שיח (Chat).

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

מידע נוסף זמין במאמר סגירת תיבת דו-שיח (תוספים).
התחברות למערכת חיצונית (בקשת הגדרה) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

מידע נוסף זמין במאמר בנושא חיבור למערכת חיצונית.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

מידע נוסף על חיבור תוסף ל-Google Workspace לשירות של צד שלישי
השלמה אוטומטית של פריטים בווידג'טים אינטראקטיביים 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

מידע נוסף זמין במאמר הוספת תפריט עם אפשרויות בחירה מרובות.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

מידע נוסף זמין במאמר איסוף ועיבוד מידע ממשתמשי Google Chat.

טיפול באינטראקציות עם כרטיסים בהודעות שנוצרו לפני ההמרה

כשממירים אפליקציית Google Chat ב-HTTP לתוסף ל-Google Workspace, נדרש טיפול מיוחד באינטראקציות עם כרטיסים בהודעות שנוצרו לפני ההמרה. תוספים משתמשים בכתובת URL מלאה ב-HTTP עבור action.function של כרטיס, בעוד שאפליקציות Chat שנבנו באמצעות אירועי אינטראקציה של Google Chat API משתמשות בשם פונקציה. בטבלה הבאה מפורטים ההבדלים האלה.

אפליקציית Google Chat שנבנתה באמצעות אירועי אינטראקציה עם Google Chat API תוסף ל-Google Workspace שמרחיב את Google Chat
הגדרה מגדירים נקודת קצה אחת לכל האירועים במסוף Google Cloud. כשמטמיעים אינטראקציות עם כרטיסים, action של כרטיס מכיל רק את שם הפונקציה להפעלה. נקודת הקצה (endpoint) הנפוצה של HTTP מופעלת לאירועים של לחיצה על כרטיס.

מידע נוסף זמין במאמר בנושא פתיחת תיבת דו-שיח (Chat).



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 אפשר להגדיר נקודות קצה לכל אירוע במסוף Google Cloud, אבל זה לא כולל אירועי קליקים על כרטיסים. כשמטמיעים אינטראקציות עם כרטיסים, התג action של הכרטיס צריך להכיל את כתובת ה-URL המלאה של נקודת הקצה של ה-HTTP שרוצים להפעיל. אפשר להגדיר נקודת קצה ייחודית של HTTP לכל לחצן, או להשתמש בנקודת קצה משותפת ולהעביר את הפעולה כפרמטר ב-action.parameters.

מידע נוסף זמין במאמר פתיחת תיבת דו-שיח (תוספים).



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

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

כתובת ה-URL הזו משמשת רק לאינטראקציות בהודעות שנוצרו לפני שהמרתם את האפליקציה. כשמשתמש מקיים אינטראקציה עם אחת מההודעות האלה, הערך המקורי action.function מועבר כפרמטר שנקרא __action_method_name__.

דוגמה: קליק על כרטיס

אם הגדרתם את כתובת ה-URL של האינטראקציה עם הכרטיס כ-https://.../card-interaction-handler, ומשתמש לוחץ על כרטיס בהודעה היסטורית עם הפעולה הבאה:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

אירוע מועבר אל כתובת ה-URL של האינטראקציה עם הכרטיס שהגדרתם בפורמט הבא:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

דוגמה: תפריט עם אפשרות לבחירה מרובה

אם משתמש מקיים אינטראקציה עם תפריט בחירה מרובה שמחובר למקור נתונים חיצוני:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

אירוע מועבר אל כתובת ה-URL של האינטראקציה עם הכרטיס שהגדרתם בפורמט הבא:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

אם מפעילים את האפשרות Use common HTTP endpoint url for all triggers (שימוש בכתובת URL משותפת של נקודת קצה HTTP לכל הטריגרים) לטריגרים מסוג HTTP, כתובת ה-URL המשותפת משמשת גם לאירועים מסוג Button Clicked (המשתמש לחץ על לחצן).

אימות בקשות לתוספים של Google Workspace ל-HTTP שמרחיבים את Chat

באפליקציות של Google Chat שמבוססות על HTTP, צריך לעדכן את הלוגיקה לאימות הבקשות שמגיעות מ-Google כשממירים אותן לתוסף ל-Google Workspace.

ההבדלים העיקריים באימות הבקשות הם:

סוג אפליקציה קהל נתמך כתובת האימייל של חשבון השירות
אפליקציית Google Chat שנבנתה באמצעות אירועי אינטראקציה עם Google Chat API מספר הפרויקט chat@system.gserviceaccount.com
תוסף ל-Google Workspace שמרחיב את Google Chat נקודת קצה (endpoint) של HTTP בלבד כתובת האימייל בחשבון שירות לכל פרויקט

כתובת האימייל הייחודית של חשבון השירות של תוסף Google Workspace מופיעה בקטע Convert to Google Workspace add-ons בדף ההגדרות של Google Chat API במסוף Google Cloud.

כדי לאמת בקשות בתוסף המשודרג של Google Workspace:

  1. אם משתמשים בפונקציות Cloud Run, מקצים את התפקיד roles/cloudfunctions.invoker לחשבון השירות של התוסף. מידע נוסף זמין במאמר בנושא הרשאת גישה באמצעות IAM.
  2. כדי לאמת את החתימה של אסימון ה-Bearer, צריך לעדכן את קוד האימות של האסימון כך שישתמש בכתובת האימייל בחשבון השירות של תוסף Google Workspace. איך מאמתים בקשות מ-Google