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

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

ההמרה מאפשרת לאפליקציית Google Chat להשתמש במסגרת של תוספים ל-Google Workspace, וכך נפתחות אפשרויות חדשות לשילוב ולתכונות ב-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 באפליקציית 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 לבקשות ולתגובות. אפשר להיעזר במדריך להמרת קוד כדי לשנות את הקוד.

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

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

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

    כניסה לדף ההגדרות של Google Chat API

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

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

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

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

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

שלב 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 Cloud על המשאבים שבהם השתמשה אפליקציית Google Chat שכבר לא נמצאת בשימוש, כדאי להשבית אותם.

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

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

בקשת מיפוי

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

השדה 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.

תרחיש לדוגמה ‫Chat API interaction Event Payload המטען הייעודי (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, נדרש טיפול מיוחד באינטראקציות עם כרטיסים בהודעות שנוצרו לפני ההמרה. תוספים ל-Google Workspace משתמשים בכתובת URL מלאה של HTTP עבור action.function של כרטיס, בעוד שאפליקציות ל-Google 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 Workspace, צריך לעדכן את הלוגיקה לאימות הבקשות שמגיעות מ-Google.

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

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

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

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

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