איך מקשרים אפליקציית Chat לשירותים ולכלים אחרים

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

כדי לאמת משתמשים באמצעות שירות צד שלישי או תהליך OAuth, אפליקציית Chat מבצעת את השלבים הבאים:

  1. זיהוי מקרים שבהם נדרשת הרשאה או הגדרה.
  2. החזרת כרטיס הרשאה בסיסי שמבקש מהמשתמש להיכנס או להגדיר את השירות.
  3. הפניה ל-URI של ההשלמה כדי ש-Google Chat ינסה אוטומטית לבצע שוב את האינטראקציה המקורית אחרי שהמשתמש ישלים את ההרשאה.

ארכיטקטורה של אימות אפליקציות Google Chat בשירות צד שלישי.

דרישות מוקדמות

HTTP

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

Apps Script

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

זיהוי הצורך בהרשאה

יכול להיות שלמשתמשים לא תהיה הרשאה לגשת למשאב מוגן באפליקציה ל-Chat מסיבות שונות, למשל:

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

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

אם אתם מפתחים ב-Apps Script, אתם יכולים להשתמש בספריית OAuth2 for Google Apps Script (או בגרסת OAuth1), שבה הפונקציה hasAccess בודקת אם המשתמש אישר גישה לשירות. לחלופין, כשמשתמשים בבקשות UrlFetchApp.fetch, אפשר להגדיר את הפרמטר muteHttpExceptions לערך true כדי לבדוק את קוד התגובה ואת התוכן באובייקט HttpResponse שמוחזר.

הצגת כרטיס הרשאה בסיסי למשתמשים

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

בתמונה הבאה מוצגת דוגמה לכרטיס ההרשאה הבסיסי של Google:

הנחיה בסיסית למתן הרשאה לחשבון לדוגמה.
איור 1: בקשת הרשאה בסיסית לחשבון לדוגמה. בחלון הקופץ מופיעה ההודעה שהאפליקציה ל-Chat רוצה להציג מידע נוסף, אבל היא צריכה את אישור המשתמש כדי לגשת לחשבון.

כדי להציג למשתמשים כרטיס הרשאה בסיסי, מחזירים אובייקט AuthorizationError:

HTTP

מחזירה את תגובת ה-JSON הבאה:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

מחליפים את מה שכתוב בשדות הבאים:

  • ‫AUTHORIZATION_URL: כתובת URL מסוג HTTPS של אפליקציית האינטרנט שמטפלת באימות, בהרשאה או בהגדרה.
  • ‫RESOURCE_DISPLAY_NAME: השם המוצג של המשאב או השירות המוגנים. השם הזה מוצג למשתמש בהנחיה לאישור. לדוגמה, אם RESOURCE_DISPLAY_NAME הוא Example Account, בהנחיה יצוין שהאפליקציה צריכה אישור כדי לגשת אל Example Account.

השלמת בקשת ההגדרה

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

בטריגרים האלה, אפליקציית Chat מקבלת כתובת URI להפניה אוטומטית להשלמה (configCompleteRedirectUri / completeRedirectUri) במטען הייעודי של האירוע:

  • הודעה: chat.messagePayload.configCompleteRedirectUri
  • התווסף למרחב: chat.addedToSpacePayload.configCompleteRedirectUri
  • פקודה לאפליקציה: chat.appCommandPayload.configCompleteRedirectUri

אתם צריכים לקודד את כתובת ה-URI להפניה ב-<var>AUTHORIZATION_URL</var> ולהפנות אליה את הדפדפן של המשתמש אחרי שתהליך ההרשאה מסתיים. הפניה לכתובת ה-URL הזו מסמנת ל-Google Chat שהבקשה לאישור או להגדרה בוצעה.

כשמשתמש מופנה בהצלחה לכתובת ה-URI להפניה אוטומטית להשלמה שסופקה במטען הייעודי (payload) של האירוע המקורי, Google Chat מבצע את השלבים הבאים:

  1. מוחק את ההודעה הפרטית לבקשת הרשאה שמוצגת למשתמש שיזם את הפעולה.
  2. ההודעה המקורית תהפוך לגלוי לכולם, כך ששאר המשתתפים במרחב יוכלו לראות אותה.
  3. שליחה של אובייקט האירוע המקורי לאפליקציית Chat בפעם השנייה.

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

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

אימות המשתמש ב-Chat מחוץ ל-Chat

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

משתמשים באסימון הזהות שהונפק במהלך הכניסה כדי לקבל את מזהה המשתמש. התביעה sub מכילה את מזהה Google הייחודי של המשתמש, ואפשר לקשר אותה לשם משאב המשתמש (chat.user.name) מ-Google Chat.

כדי לקשר את הטענה sub לשם המשאב users/{user} ב-Google Chat, מוסיפים לפני הערך של הטענה sub את המחרוזת users/. לדוגמה, ערך התביעה sub של 123 תואם ל-users/123 באובייקטים של אירועים שנשלחים לאפליקציית הצ'אט שלכם.

דוגמאות קוד

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

אפליקציות צ'אט שהן לא תוספים: קישור של אפליקציית צ'אט לשירותים ולכלים אחרים

אם אתם מנהלים אפליקציה ל-Chat שהיא לא תוסף ל-Google Workspace, האפליקציה ל-Chat מבקשת הגדרה באמצעות actionResponse מסוג REQUEST_CONFIG וקוראת את configCompleteRedirectUrl מאובייקט Event ברמה העליונה.

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

בקשת הגדרה ממשתמש באפליקציית Chat שלא מוגדרת כתוסף

באפליקציית Chat שהיא לא תוסף, מחזירים למשתמש כתובת URL להגדרה בפורמט הבא:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

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

השלמת בקשת ההגדרה באפליקציית Chat שאינה תוסף

כל אינטראקציה עם MESSAGE, ADDED_TO_SPACE ו-APP_COMMAND Event שאפליקציית Chat שאינה תוסף מקבלת כוללת את השדה ברמה העליונה configCompleteRedirectUrl. מקודדים את כתובת ה-URL הזו בכתובת ה-URL של ההגדרה ומפנים אליה את המשתמש בסיום, כדי ש-Google Chat ימחק את ההנחיה, יהפוך את ההודעה המקורית לציבורית וישלח מחדש את אירוע האינטראקציה המקורי לאפליקציית Chat.

דוגמאות להטמעה אפשר למצוא ב-GitHub בדוגמה לאפליקציית קישוריות ב-Node.js ובדוגמה לאפליקציית אימות MyProfile ב-Python.