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

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

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

מגבלות

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

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

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

שלב 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 לבין פורמט EventObject התוסף של Google Workspace.

מיפוי בקשות

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

אפליקציית Chat שהיא לא תוסף (שדה 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
 הנתונים זמינים במטענים ייעודיים (payloads) שונים, בהתאם לסוג האירוע.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 הנתונים זמינים במטענים ייעודיים (payloads) שונים, בהתאם לסוג האירוע.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 הנתונים זמינים במטענים ייעודיים (payloads) שונים, בהתאם לסוג האירוע.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 הנתונים זמינים במטענים ייעודיים (payloads) שונים, בהתאם לסוג האירוע.
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
 הנתונים זמינים במטענים ייעודיים (payloads) שונים, בהתאם לסוג האירוע.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 הנתונים זמינים במטענים ייעודיים (payloads) שונים, בהתאם לסוג האירוע.
token לא רלוונטי האימות מתבצע באופן שונה, כפי שמתואר במאמר אימות בקשות לאפליקציות HTTP.
type לא רלוונטי אפשר להסיק את סוג האירוע מהטריגר.
user chat.user

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

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

תרחיש לדוגמה אפליקציית צ'אט שהיא לא תוסף (מטען ייעודי (Payload) של 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 לאפליקציית Chat שהיא לא תוסף, והפעולות המקבילות שלהן בתוסף ל-Google Workspace.

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

השדה actionResponse הוא אופציונלי. מידע נוסף על שליחת תשובה לפקודה עם לוכסן

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

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

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

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

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

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

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

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

מידע נוסף מופיע במאמר בנושא פתיחת תיבות דו-שיח אינטראקטיביות.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מידע נוסף מופיע במאמר בנושא פתיחת תיבות דו-שיח אינטראקטיביות.



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

מידע נוסף מופיע במאמר בנושא פתיחת תיבות דו-שיח אינטראקטיביות.



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

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

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

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

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

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