אימות והרשאה הם מנגנונים שמשמשים לאימות הזהות ולגישה למשאבים, בהתאמה. במאמר הזה מוסבר איך עובדים האימות וההרשאה באפליקציות ל-Chat ובבקשות מ-Chat API.
סקירה כללית של התהליך
התרשים הבא מציג את השלבים הכלליים של אימות והרשאה ב-Google Chat:
מגדירים פרויקט ב-Google Cloud, מפעילים את Chat API ומגדירים את אפליקציית Chat: במהלך הפיתוח, יוצרים פרויקט ב-Google Cloud. בפרויקט ב-Google Cloud, מפעילים את Chat API, מגדירים את אפליקציית Chat ומגדירים אימות. מידע נוסף זמין במאמרים בנושא פיתוח ב-Google Workspace ויצירת אפליקציה ל-Chat.
שליחת קריאה ל-Chat API: כשהאפליקציה שולחת קריאה ל-Chat API, היא שולחת פרטי אימות ל-Chat API. אם האפליקציה מאומתת באמצעות חשבון שירות, פרטי הכניסה נשלחים כחלק מקוד האפליקציה. אם האפליקציה שלכם דורשת קריאה ל-Chat API באמצעות אימות משתמש שעדיין לא אושר, המשתמש יתבקש להיכנס לחשבון.
בקשת משאבים: האפליקציה מבקשת גישה עם היקפי הרשאות שאתם מציינים במהלך הגדרת האימות.
בקשת הסכמה: אם האפליקציה עוברת אימות בתור משתמש, Google מציגה מסך הסכמה של OAuth כדי שהמשתמש יוכל להחליט אם להעניק לאפליקציה גישה לנתונים המבוקשים. אימות באמצעות חשבון שירות לא דורש הסכמת משתמש.
שליחת בקשה מאושרת למשאבים: אם המשתמש מסכים להיקפי ההרשאות, האפליקציה מאגדת את פרטי הכניסה ואת היקפי ההרשאות שאושרו על ידי המשתמש בבקשה אחת. הבקשה נשלחת לשרת ההרשאות של Google כדי לקבל אסימון גישה.
Google מחזירה אסימון גישה: אסימון הגישה מכיל רשימה של היקפי הרשאות שהוענקו. אם רשימת ההיקפים שמוחזרת מגבילה יותר מההיקפים המבוקשים, האפליקציה משביתה את כל התכונות שמוגבלות על ידי האסימון.
גישה למשאבים המבוקשים: האפליקציה משתמשת בטוקן הגישה מ-Google כדי להפעיל את Chat API ולגשת למשאבים של Chat API.
קבלת אסימון לרענון (אופציונלי): אם האפליקציה שלכם צריכה לגשת ל-Google Chat API מעבר לתוחלת החיים של אסימון גישה יחיד, היא יכולה לקבל אסימון לרענון. למידע נוסף, תוכלו לקרוא את המאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
בקשת משאבים נוספים: אם האפליקציה צריכה גישה נוספת, היא מבקשת מהמשתמש להעניק לה היקפי גישה חדשים, וכתוצאה מכך מוגשת בקשה חדשה לקבלת אסימון גישה (שלבים 3-6).
מתי אפליקציות ל-Chat דורשות אימות
אפליקציות ל-Chat יכולות לשלוח הודעות בתגובה לאינטראקציה של משתמש, או באופן אסינכרוני. הן גם יכולות להשלים משימות בשם המשתמש, כמו יצירת מרחב ב-Chat או קבלת רשימה של אנשים במרחב ב-Chat.
אפליקציות ל-Chat לא דורשות אימות כדי להגיב לאינטראקציה של משתמש, אלא אם אפליקציית ה-Chat קוראת ל-Chat API או ל-Google API אחר בזמן עיבוד התשובה.
כדי לשלוח הודעות אסינכרוניות או לבצע משימות בשם משתמש, אפליקציות ל-Chat שולחות בקשות RESTful ל-Chat API, שדורשות אימות והרשאה.
לא נדרש אימות כדי להגיב לאינטראקציות של משתמשים
אפליקציות ל-Google Chat לא צריכות לעבור אימות כמשתמש או כאפליקציית Chat כדי לקבל אירועי אינטראקציה ולהגיב להם באופן סינכרוני.
אפליקציות ל-Google Chat מקבלות אירועי אינטראקציה בכל פעם שמשתמש יוצר אינטראקציה עם אפליקציית Chat או מפעיל אותה, כולל הפעולות הבאות:
- משתמש שולח הודעה לאפליקציה ב-Chat.
- משתמש עושה אזכור @של אפליקציית Chat.
- משתמש מפעיל אחת מהפקודות של אפליקציית Chat.
בתרשים הבא מוצג רצף של בקשה ותגובה בין משתמש ב-Chat לבין אפליקציית Chat:
- המשתמש שולח הודעה לאפליקציית Chat ב-Google Chat.
- ההודעה מועברת מ-Google Chat לאפליקציה.
- האפליקציה מקבלת את ההודעה, מעבדת אותה ומחזירה תשובה ל-Google Chat.
- Google Chat מציג את התשובה למשתמש או במרחב.
הרצף הזה חוזר על עצמו לכל אירוע של אינטראקציה עם אפליקציית Chat.
הודעות אסינכרוניות דורשות אימות
הודעות אסינכרוניות מתרחשות כשאפליקציה ל-Chat שולחת בקשה ל-Chat API, שדורשת אימות והרשאה.
באמצעות Chat API, אפליקציות ל-Chat יכולות לפרסם הודעות ב-Google Chat או להשלים משימות ולגשת לנתונים בשם המשתמש. לדוגמה, אחרי שאפליקציה ל-Chat מזהה הפסקת פעולה של שרת, היא יכולה להפעיל את Chat API כדי:
- ליצור מרחב ב-Chat שמוקדש לחקירה ולתיקון של ההשבתה.
- להוסיף אנשים למרחב ב-Chat.
- פרסמו הודעה במרחב ב-Chat כדי לספק פרטים על ההשבתה.
התרשים הבא מציג רצף של הודעות אסינכרוניות בין אפליקציית Chat לבין מרחב ב-Chat:
- אפליקציית Chat יוצרת הודעה על ידי קריאה ל-Chat API באמצעות
spaces.messages.createmethod, וכוללת את פרטי הכניסה של המשתמש בבקשת ה-HTTP. - מערכת Google Chat מאמתת את אפליקציית Chat באמצעות חשבון שירות או פרטי כניסה של משתמש.
- ההודעה של האפליקציה מוצגת במרחב ספציפי ב-Chat.
היקפי הגישה של Chat API
מגדירים את מסך ההסכמה של OAuth ובוחרים היקפי הרשאה כדי להגדיר איזה מידע יוצג למשתמשים ולבודקי האפליקציה, ורושמים את האפליקציה כדי שתוכלו לפרסם אותה בהמשך.
כדי להגדיר את רמת הגישה שניתנת לאפליקציה, צריך לזהות ולהצהיר על היקפי הרשאות. היקף הרשאות הוא מחרוזת URI של OAuth 2.0 שמכילה את שם האפליקציה של Google Workspace, את סוג הנתונים שהיא ניגשת אליהם ואת רמת הגישה.
היקפי הרשאות לא רגישים
| קוד היקף | תיאור |
|---|---|
https://www.googleapis.com/auth/chat.bot
|
מאפשר לאפליקציות של 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.admin.spaces.readonly
|
לראות את הצ'אט ואת המרחבים בבעלות הדומיין של האדמין ב-Chat. |
https://www.googleapis.com/auth/chat.admin.spaces
|
לצפות בצ'אטים ובמרחבים משותפים שנמצאים בדומיין של האדמין ב-Chat או לערוך אותם. |
https://www.googleapis.com/auth/chat.admin.memberships.readonly
|
לגשת לרשימות של המשתתפים והמנהלים בשיחות ב-Chat שבבעלות הדומיין של האדמין. |
https://www.googleapis.com/auth/chat.admin.memberships
|
לגשת לרשימות של המשתתפים והמנהלים בשיחות שבבעלות הדומיין של האדמין ב-Chat, להוסיף משתמשים ומנהלים לשיחות, לעדכן את התפקידים שלהם ולהסיר אותם משיחות. |
https://www.googleapis.com/auth/chat.app.spaces
|
יצירת שיחות ומרחבים, וקריאה או עריכה של מטא-נתונים (כולל הגדרות ההיסטוריה והגדרות הגישה) ב-Chat. נדרש אישור של אדמין. היקף ההרשאות הזה תומך רק באימות אפליקציות באמצעות חשבונות שירות. אי אפשר לבצע אימות באמצעות פרטי כניסה של משתמשים או באמצעות מתן הרשאות גישה ברמת הדומיין באמצעות ההיקף הזה. |
https://www.googleapis.com/auth/chat.app.spaces.create
|
יצירת שיחות ומרחבים חדשים ב-Chat. נדרש אישור של אדמין. היקף ההרשאות הזה תומך רק באימות אפליקציות באמצעות חשבונות שירות. אי אפשר לבצע אימות באמצעות פרטי כניסה של משתמשים או באמצעות מתן הרשאות גישה ברמת הדומיין באמצעות ההיקף הזה. |
https://www.googleapis.com/auth/chat.app.memberships
|
קריאה, הוספה, עדכון והסרה של חברים בשיחות ובמרחבים ב-Chat. נדרש אישור של אדמין. היקף ההרשאות הזה תומך רק באימות אפליקציות באמצעות חשבונות שירות. אי אפשר לבצע אימות באמצעות פרטי כניסה של משתמשים או באמצעות מתן הרשאות גישה ברמת הדומיין באמצעות ההיקף הזה. |
https://www.googleapis.com/auth/chat.customemojis
|
הצגה, יצירה ומחיקה של אמוג'י בהתאמה אישית ב-Chat. |
https://www.googleapis.com/auth/chat.customemojis.readonly
|
קריאת אמוג'י מותאם אישית ב-Chat. |
https://www.googleapis.com/auth/chat.users.spacesettings
|
הצגה ועדכון של הגדרות המרחב של משתמשים ב-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. |
https://www.googleapis.com/auth/chat.admin.delete
|
מחיקת השיחות והמרחבים שבבעלות הדומיין של האדמין והסרת הגישה לקבצים המשויכים ב-Chat. |
https://www.googleapis.com/auth/chat.app.delete
|
מחיקה של שיחות ומרחבים והסרת הגישה לקבצים משויכים ב-Chat. נדרש אישור של אדמין. היקף ההרשאות הזה תומך רק באימות אפליקציות באמצעות חשבונות שירות. אי אפשר לבצע אימות באמצעות פרטי כניסה של משתמשים או באמצעות מתן הרשאות גישה ברמת הדומיין באמצעות ההיקף הזה. |
ההיקפים בטבלאות הקודמות מציינים את הרגישות שלהם, בהתאם להגדרות הבאות:
לא רגיש – היקפי ההרשאות האלה מספקים את תחום הגישה הקטן ביותר להרשאה ודורשים רק אימות בסיסי של האפליקציה. מידע על הדרישה הזו מופיע במאמר איך מתכוננים לאימות.
רגיש – היקפי ההרשאות האלה מספקים לאפליקציה גישה לנתונים ספציפיים של משתמש ב-Google אחרי שהמשתמש נתן הרשאה. כדי להשתמש באפליקציה, צריך לעבור אימות נוסף. מידע על הדרישה הזו זמין במאמר שלבים לאפליקציות שמבקשות היקפים רגישים.
מוגבלת – היקפי ההרשאות האלה מספקים גישה רחבה לנתוני משתמשים ב-Google, ונדרש לעבור את תהליך האימות של היקף הרשאות מוגבל. מידע על הדרישה הזו זמין במאמרים שירותי Google API: מדיניות בנושא נתוני משתמשים ודרישות נוספות לגבי היקפי הרשאות ספציפיים של API. אפשר לעיין גם בשלבים לאפליקציות שמבקשות היקפי גישה מוגבלים.
אם האפליקציה שלכם דורשת גישה לממשקי Google API אחרים, תוכלו להוסיף גם את היקפי ההרשאות האלה. למידע נוסף על היקפי ההרשאות של Google API, אפשר לעיין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
מידע נוסף על היקפי הרשאות ל-Google Workspace APIs זמין במאמר הגדרת מסך הסכמה ל-OAuth ובחירת היקפי הרשאות.
סוגי האימות הנדרשים
יש שתי דרכים שבהן אפליקציות ל-Chat יכולות לבצע אימות והרשאה באמצעות Chat API:
- אימות משתמשים
- אימות משתמשים מאפשר לאפליקציית Chat לגשת לנתוני משתמשים ולהשלים פעולות בשם המשתמשים. היקפי הרשאות OAuth מציינים את הנתונים והפעולות המורשים. אלא אם אפליקציית Chat הותקנה על ידי האדמין או שניתנה לה הענקת הרשאות ברמת הדומיין, בפעם הראשונה שאפליקציית Chat מבצעת פעולה בשם משתמש, המשתמש צריך לאשר את אפליקציית Chat באמצעות מסך ההסכמה של OAuth.
- אימות אפליקציות
אימות אפליקציות מאפשר לאפליקציית Chat להשתמש בפרטי הכניסה של חשבון שירות, לגשת לנתונים ולהשלים פעולות בשם עצמה. מכיוון שאפליקציית Chat משתמשת בפרטי הכניסה שלה כדי לגשת למשאבים ולעבוד איתם, משתמשי הקצה לא צריכים לאשר את קריאות ה-API של אפליקציית Chat, ואי אפשר להוסיף לתצוגת ההסכמה של OAuth היקפי הרשאות של OAuth שתומכים בהרשאת אפליקציות.
יש שני סוגים של היקפי הרשאות OAuth שתומכים באימות אפליקציות:
-
https://www.googleapis.com/auth/chat.bot: אפליקציית Chat יכולה לקרוא לשיטות של Google Chat API שתומכות בהיקף ההרשאות הזה כדי ליצור, לעדכן, לקבל, לרשום או למחוק משאבים שיש לה גישה אליהם, כמו הודעות במרחבים שמשתמשי קצה מוסיפים אליהם את אפליקציית Chat. אפליקציית Chat יכולה להעניק לעצמה את היקף ההרשאה הזה, ולא נדרשת הרשאה ממנהל או ממשתמש קצה. https://www.googleapis.com/auth/chat.app.*(תצוגה מקדימה למפתחים): כדי להשתמש בהיקפי הגישה האלה, נדרש אישור חד-פעמי של אדמין. כדי לקבל אישור מהאדמין, צריך להכין את חשבון השירות של אפליקציית Chat לקבלת אישור מהאדמין על ידי יצירת לקוח OAuth שתואם ל-Google Workspace Marketplace והגדרת האפליקציה ב-Google Workspace Marketplace SDK. ההיקפים האלה מאפשרים לאפליקציית Chat שלכם לקרוא לשיטות ספציפיות של Google Chat API. לדוגמה, ההרשאהchat.app.spaces.createמאפשרת לאפליקציות ליצור מרחבים ב-Chat.
-
אם שיטה מסוימת תומכת באימות משתמשים ובאימות אפליקציות, Chat API מחזיר תוצאות שונות בהתאם לסוג האימות שבו משתמשים:
- באימות אפליקציות, השיטות מחזירות רק משאבים שאפליקציית Chat יכולה לגשת אליהם.
- באימות משתמשים, השיטות מחזירות רק משאבים שהמשתמש יכול לגשת אליהם.
לדוגמה, הפעלת השיטה spaces.list() עם הרשאת גישה לאפליקציה מחזירה את רשימת המרחבים שהאפליקציה ל-Chat היא חברה בהם.
התקשרות אל spaces.list() עם הרשאת משתמש מחזירה את רשימת המרחבים שהמשתמש חבר בהם. בפועל, יכול להיות שתשתמשו בשני סוגי האימות כשאתם קוראים ל-Chat API, בהתאם לעיצוב ולתכונות של אפליקציית Chat שלכם.
לקריאות אסינכרוניות ל-Chat API
בטבלה הבאה מפורטות השיטות של Chat API והיקפי ההרשאה הנתמכים שלהן:
| שיטה | אימות משתמשים נתמך | אימות אפליקציה נתמך | היקפי ההרשאה הנתמכים | |
|---|---|---|---|---|
| מרחבים | ||||
| איך יוצרים מרחבים |
עם אימות משתמשים:
|
|||
| הגדרת מרחב | — |
עם אימות משתמשים:
|
||
| איך יוצרים מרחבים |
עם אימות משתמשים:
|
|||
| רשימת מרחבים |
עם אימות משתמשים:
|
|||
| חיפוש מרחבים | — |
עם אימות משתמשים באמצעות הרשאות אדמין:
|
||
| עדכון המרחב |
עם אימות משתמשים:
|
|||
| מחיקת מרחב |
עם אימות משתמשים:
|
|||
| השלמת תהליך הייבוא של מרחב | — |
עם אימות משתמשים:
|
||
| איך מוצאים צ'אטים ישירים |
עם אימות משתמשים:
|
|||
| חברים | ||||
| יצירת חבר |
עם אימות משתמשים:
|
|||
| הצטרפות למועדון החברים |
עם אימות משתמשים:
|
|||
| חברים ברשימה |
עם אימות משתמשים:
|
|||
| מחיקת חברים |
עם אימות משתמשים:
|
|||
| עדכון של משתמשים במרחב |
עם אימות משתמשים:
|
|||
| הודעות | ||||
| יצירת הודעה |
עם אימות משתמשים:
|
|||
| קבלת הודעה |
עם אימות משתמשים:
|
|||
| הצגת רשימת הודעות | — |
עם אימות משתמשים:
|
||
| עדכון הודעה |
עם אימות משתמשים:
|
|||
| איך מוחקים הודעות |
עם אימות משתמשים:
|
|||
| תגובות | ||||
| יצירת תגובה | — |
עם אימות משתמשים:
|
||
| רשימת התגובות באמוג'י | — |
עם אימות משתמשים:
|
||
| איך מוחקים תגובות | — |
עם אימות משתמשים:
|
||
| סמלי אמוג'י מותאמים אישית | ||||
| איך יוצרים אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| מחיקת אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| איך מקבלים אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| הצגת רשימה של סמלי אמוג'י מותאמים אישית | — |
עם אימות משתמשים:
|
||
| מדיה וקבצים מצורפים | ||||
| העלאת מדיה כקובץ מצורף | — |
עם אימות משתמשים:
|
||
| הורדת מדיה |
עם אימות משתמשים:
|
|||
| איך מורידים קובץ מצורף להודעה | — |
עם אימות אפליקציות:
|
||
| מצבי קריאה של משתמשים | ||||
| קבלת מצב הקריאה של משתמש במרחב | — |
עם אימות משתמשים:
|
||
| עדכון סטטוס הקריאה של משתמש במרחב | — |
עם אימות משתמשים:
|
||
| קבלת מצב הקריאה של שרשור של משתמש | — |
עם אימות משתמשים:
|
||
| הגדרות המרחב של המשתמש | ||||
| קבלת הגדרת ההתראות של משתמש במרחב | — |
עם אימות משתמשים:
|
||
| איך מעדכנים את הגדרת ההתראות של משתמש במרחב | — |
עם אימות משתמשים:
|
||
| אירועים ב-Spaces | ||||
| קבלת אירועים במרחב | — |
באימות משתמשים,
חובה להשתמש בהיקף שמבוסס על
סוג האירוע:
|
||
| הצגת רשימה של אירועים במרחב | — |
באימות משתמשים, צריך להשתמש בהיקף לכל
סוג אירוע שכלול בבקשה:
|
||
לאירועי אינטראקציה עם אפליקציות ל-Chat
בטבלה הבאה מפורטות דרכים נפוצות שבהן משתמשים מקיימים אינטראקציה עם אפליקציות ל-Chat, ומוסבר אם נדרש אימות או אם הוא נתמך:
| תרחיש | לא נדרש אימות | אימות משתמשים נתמך | אימות אפליקציה נתמך | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| קבלת הודעות מ: |
|
|||||||||||||||
| איך עונים להודעות |
|
|||||||||||||||
| שליחת הודעות חדשות: |
|
|||||||||||||||
נושאים קשורים
- במאמר הזה מוסבר על אימות והרשאה ב-Google Workspace.
- בסקירה הכללית על אימות תוכלו לקרוא על אימות והרשאה ב-Google Cloud.
- מידע נוסף על חשבונות שירות זמין במאמר חשבונות שירות.
- מידע נוסף על השימוש ב-OAuth 2.0 ב-Google APIs מופיע במאמר שימוש ב-OAuth 2.0 כדי לגשת אל Google APIs.
- מגדירים אימות והרשאה באמצעות פרטי כניסה של משתמש או חשבון שירות.