אימות והרשאה של אפליקציות צ'אט ובקשות מ-Google Chat API

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

סקירה כללית על התהליך

בתרשים הבא מוצגים השלבים הכלליים של האימות וההרשאה ל-Google Chat:

שלבים כלליים לאימות ולהרשאה ב-Google Chat
איור 1. שלבים כלליים לאימות ולהרשאה ב-Google Chat.

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

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

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

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

  5. שליחת בקשה מאושרת למשאבים: אם המשתמש מסכים להיקפי ההרשאות, הבקשה ב-App Bundle היא את פרטי הכניסה וההיקפים שאושרו על ידי המשתמשים. הבקשה נשלחת לשרת ההרשאות של Google כדי לקבל אסימון גישה.

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

  7. גישה למשאבים שהתבקשו: האפליקציה שלכם משתמשת באסימון הגישה של Google כדי להפעיל את Chat API ולגשת למשאבים של Chat API.

  8. קבלת אסימון רענון (אופציונלי): אם לאפליקציה שלכם נדרשת גישה ל-Google Chat API אחרי משך החיים של אסימון גישה יחיד, יכול להיות שתהיה לה אסימון רענון. למידע נוסף, תוכלו לקרוא את המאמר שימוש ב-OAuth 2.0 כדי לגשת ל-Google APIs.

  9. בקשת משאבים נוספים: אם לאפליקציה שלכם נדרשת גישה נוספת, היא מבקשת מהמשתמש להעניק היקפי הרשאות חדשים, וכתוצאה מכך מתקבלת בקשה חדשה לקבלת אסימון גישה (שלבים 3-6).

מתי אפליקציות צ'אט מחייבות אימות?

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

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

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

תגובות לאינטראקציות של משתמשים לא מחייבות אימות

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

אפליקציות Google Chat מקבלות אירועי אינטראקציה בכל פעם שמשתמש יוצר אינטראקציה עם אפליקציית Chat, כולל:

  • משתמש שולח הודעה לאפליקציית Chat.
  • משתמש מזכיר אפליקציית Chat באמצעות @.
  • המשתמש מפעיל את אחת הפקודות של הלוכסן באפליקציית Chat.

בתרשים הבא מוצג רצף של תגובות לבקשות בין משתמשים ב-Chat לבין אפליקציית Chat:

לא נדרשת הרשאה לאירועי אינטראקציה באפליקציות ב-Chat
איור 2.אירועי אינטראקציה עם אפליקציות צ'אט לא מחייבים אימות.

  1. המשתמש שולח הודעה לאפליקציית Chat ב-Google Chat.
  2. ההודעה תועבר מ-Google Chat לאפליקציה.
  3. האפליקציה מקבלת את ההודעה, מעבדת אותה ומחזירה תשובה ל-Google Chat.
  4. התשובה ב-Google Chat תעובד ב-Google Chat או במרחב המשותף.

הרצף הזה חוזר על עצמו לכל אירוע אינטראקציה באפליקציית Chat.

הודעות אסינכרוניות מחייבות אימות

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

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

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

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

נדרש אימות להודעות אסינכרוניות
איור 3. הודעות אסינכרוניות מחייבות אימות.

  1. אפליקציית Chat יוצרת הודעה על ידי קריאה ל-Chat API באמצעות ה-method spaces.messages.create, וכוללת את פרטי הכניסה של המשתמש בבקשת ה-HTTP.
  2. אפליקציית Google Chat מאמתת את אפליקציית Chat באמצעות חשבון שירות או פרטי כניסה של משתמש.
  3. ההודעות מהאפליקציה מעובדים ב-Google Chat במרחב משותף מסוים ב-Chat.

היקפי ההרשאות של Chat API

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

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

היקפים לא רגישים

קוד ההיקף תיאור
https://www.googleapis.com/auth/chat.bot

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

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

היקפים רגישים

קוד ההיקף תיאור
https://www.googleapis.com/auth/chat.spaces יצירת שיחות ומרחבים משותפים, והצגה או עדכון של מטא-נתונים (כולל הגדרות ההיסטוריה) ב-Chat.
https://www.googleapis.com/auth/chat.spaces.create ליצור שיחות חדשות ב-Chat.
https://www.googleapis.com/auth/chat.spaces.readonly הצגת הצ'אט והמרחבים המשותפים ב-Chat.
https://www.googleapis.com/auth/chat.memberships לראות, להוסיף ולהסיר משתתפים בשיחות ב-Chat.
https://www.googleapis.com/auth/chat.memberships.app להוסיף את האפליקציה עצמה לשיחות ב-Google Chat ולהסיר אותה.
https://www.googleapis.com/auth/chat.memberships.readonly לראות את המשתתפים בשיחות ב-Chat.
https://www.googleapis.com/auth/chat.messages.create כותבים ושולחים הודעות ב-Chat.
https://www.googleapis.com/auth/chat.messages.reactions ראיית תגובות להודעות ב-Chat, הוספה ומחיקה שלהן.
https://www.googleapis.com/auth/chat.messages.reactions.create תגובות להודעות ב-Chat.
https://www.googleapis.com/auth/chat.messages.reactions.readonly הצגת התגובות להודעות ב-Chat.
https://www.googleapis.com/auth/chat.users.readstate הצגה ושינוי של מועד הקריאה האחרון בשיחות ב-Chat.
https://www.googleapis.com/auth/chat.users.readstate.readonly הצגת מועד הקריאה האחרון בשיחות ב-Chat.

היקפים מוגבלים

קוד ההיקף תיאור
https://www.googleapis.com/auth/chat.delete מחיקת שיחות ומרחבים משותפים והסרת הגישה לקבצים משויכים ב-Chat.
https://www.googleapis.com/auth/chat.import ייבוא מרחבים משותפים, הודעות ומינויים אל Chat. מידע נוסף זמין במאמר מתן הרשאה לאפליקציות ל-Chat לייבא נתונים
https://www.googleapis.com/auth/chat.messages גישה להודעות, כתיבה, שליחה, עדכון ומחיקה שלהן, וגם הוספה, הצגה ומחיקה של תגובות להודעות.
https://www.googleapis.com/auth/chat.messages.readonly לראות את ההודעות והתגובות ב-Chat.

היקפי ההרשאות בטבלאות הקודמות מציינים את מידת הרגישות, בהתאם להגדרות הבאות:

אם לאפליקציה נדרשת גישה לממשקי Google API אחרים, ניתן להוסיף גם את ההיקפים האלה. למידע נוסף על ההיקפים של Google API, תוכלו לקרוא את המאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

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

סוגי האימות הנדרש

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

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

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

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

כשאתם מחליטים באיזה סוג של פרטי כניסה להשתמש עבור בקשת API מסוימת, חשוב לזכור שחלק משיטות ה-API תומכות רק בסוג מסוים של פרטי כניסה. אם שיטת API תומכת בשני פרטי הכניסה, סוג פרטי הכניסה שבהם נעשה שימוש בשיחה ישפיע על התוצאה שתוחזר:

  • באמצעות הרשאת אפליקציות, השיטות מחזירות רק משאבים שיש לאפליקציה גישה אליהם.
  • כשמשתמשים בהרשאות משתמש, השיטות מחזירות רק משאבים שלמשתמש יש גישה אליהם בממשק המשתמש של Chat.

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

לקריאות אסינכרוניות של Chat API

בטבלה הבאה מפורטות השיטות של Chat API והיקפי ההרשאות הנתמכים שלהן:

שיטה יש תמיכה באימות משתמשים תמיכה באימות אפליקציות היקפי הרשאות נתמכים
מרחבים משותפים  
איך יוצרים מרחב משותף עם אימות משתמש:
  • chat.spaces.create
  • chat.spaces
  • chat.import
איך מגדירים מרחבים משותפים עם אימות משתמש:
  • chat.spaces.create
  • chat.spaces
איך מזמינים מרחב משותף עם אימות משתמש:
  • chat.spaces.readonly
  • chat.spaces
באמצעות אימות אפליקציות:
  • chat.bot
הצגת רשימה של מרחבים משותפים עם אימות משתמש:
  • chat.spaces.readonly
  • chat.spaces
באמצעות אימות אפליקציות:
  • chat.bot
איך מעדכנים מרחבים משותפים עם אימות משתמש:
  • chat.spaces
  • chat.import
איך מוחקים מרחבים משותפים עם אימות משתמש:
  • chat.delete
  • chat.import
השלמת תהליך הייבוא של מרחבים משותפים עם אימות משתמש:
  • chat.import
איך מחפשים צ'אטים אישיים עם אימות משתמש:
  • chat.spaces.readonly
  • chat.spaces
באמצעות אימות אפליקציות:
  • chat.bot
חברים  
איך יוצרים חבר מועדון עם אימות משתמש:
  • chat.memberships
  • chat.memberships.app
  • chat.import
איך מצרפים מינוי? עם אימות משתמש:
  • chat.memberships.readonly
  • chat.memberships
באמצעות אימות אפליקציות:
  • chat.bot
חברים ברשימה עם אימות משתמש:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
באמצעות אימות אפליקציות:
  • chat.bot
מחיקת חברי קבוצה עם אימות משתמש:
  • chat.memberships
  • chat.memberships.app
  • chat.import
הודעות  
איך יוצרים הודעה עם אימות משתמש:
  • chat.messages.create
  • chat.messages
  • chat.import
באמצעות אימות אפליקציות:
  • chat.bot
קבלת הודעה עם אימות משתמש:
  • chat.messages.readonly
  • chat.messages
באמצעות אימות אפליקציות:
  • chat.bot
הצגת רשימה של הודעות עם אימות משתמש:
  • chat.messages.readonly
  • chat.messages
  • chat.import
איך מעדכנים הודעות עם אימות משתמש:
  • chat.messages
  • chat.import
באמצעות אימות אפליקציות:
  • chat.bot
איך מוחקים הודעות? עם אימות משתמש:
  • chat.messages
  • chat.import
באמצעות אימות אפליקציות:
  • chat.bot
תגובות  
יצירת תגובה עם אימות משתמש:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
הצגת רשימה של תגובות עם אימות משתמש:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
איך מוחקים תגובה? עם אימות משתמש:
  • chat.messages.reactions
  • chat.messages
  • chat.import
מדיה וקבצים מצורפים  
העלאת מדיה כקובץ מצורף עם אימות משתמש:
  • chat.messages.create
  • chat.messages
  • chat.import
הורדת מדיה עם אימות משתמש:
  • chat.messages.readonly
  • chat.messages
באמצעות אימות אפליקציות:
  • chat.bot
איך מקבלים קובץ של הודעה? באמצעות אימות אפליקציות:
  • chat.bot
מצבי קריאה של משתמשים
בדיקת מצב הקריאה במרחב המשותף של משתמש עם אימות משתמש:
  • chat.users.readstate
  • chat.users.readstate.readonly
עדכון מצב הקריאה של המשתמש במרחב המשותף עם אימות משתמש:
  • chat.users.readstate
איך בודקים את מצב הקריאה של המשתמש בשרשור עם אימות משתמש:
  • chat.users.readstate
  • chat.users.readstate.readonly

לאירועי אינטראקציה באפליקציית Chat

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

תרחיש לא נדרש אימות יש תמיכה באימות משתמשים תמיכה באימות אפליקציות
קבלת הודעות מ:
אירועי אינטראקציה עם אפליקציות צ'אט
קריאה חוזרת (callback) של Apps Script
Google Cloud Pub/Sub
מענה להודעות:
באופן סינכרוני, באמצעות אירוע אינטראקציה באפליקציית Chat
באופן סינכרוני, שימוש בערך החזרה של קריאה חוזרת (callback) של Apps Script
שליחת הודעות חדשות:
עם webhooks נכנסים