אימות והרשאה הם מנגנונים המשמשים לאימות הזהות ולגישה למשאבים, בהתאמה. במסמך הזה מוסבר איך מתבצעים האימות וההרשאה באפליקציות של 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 API או לממשק Google API אחר במהלך עיבוד התשובה.
כדי לשלוח הודעות אסינכרוניות או לבצע משימות בשם המשתמש, אפליקציות Chat שולחות בקשות RESTful ל-Chat API, שנדרשות להן אימות והרשאה.
תגובות לאינטראקציות של משתמשים לא מחייבות אימות
אפליקציות של Google Chat לא צריכות לעבור אימות כמשתמש או כאפליקציית Chat כדי לקבל אירועי אינטראקציה ולהגיב להם באופן סינכרוני.
אפליקציות Google Chat מקבלות אירועי אינטראקציה בכל פעם שמשתמש יוצר אינטראקציה עם אפליקציית Chat או מפעיל אותה, כולל האירועים הבאים:
- משתמש שולח הודעה לאפליקציית Chat.
- משתמש מוסיף אזכור ( @mention) של אפליקציית 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 באמצעות ה-method
spaces.messages.create, וכוללת את פרטי הכניסה של המשתמש בבקשת ה-HTTP. - Google Chat מאמת את אפליקציית Chat באמצעות חשבון שירות או פרטי כניסה של משתמש.
- מערכת Google 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.
הצגת ממשקי ה-API של הגדרות המשתמש במרחב המשותף: getSpaceNotificationSetting, updateSpaceNotificationSetting |
היקפים מוגבלים
| קוד ההיקף | תיאור |
|---|---|
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 Services: User Data Policy וAdditional Requirements for Specific API Scopes. אפשר גם לעיין במאמר שלבים לאפליקציות שמבקשות היקפי גישה מוגבלים.
אם לאפליקציה שלכם נדרשת גישה לממשקי API אחרים של Google, אפשר להוסיף גם את ההיקפים האלה. למידע נוסף על ההיקפים של Google API, ראו שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
במאמר הגדרת מסך ההסכמה ל-OAuth ובחירת היקפים תוכלו לקרוא מידע נוסף על היקפי ההרשאות של Google Workspace APIs.
סוגי האימות הנדרשים
יש שתי דרכים שבהן אפליקציות 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.
אם שיטה מסוימת תומכת באימות של משתמשים ושל אפליקציות, ה-API של Chat יחזיר תוצאות שונות בהתאם לסוג האימות שבו אתם משתמשים:
- כשמשתמשים באימות לאפליקציה, השיטות מחזירות רק משאבים שאפליקציית Chat יכולה לגשת אליהם.
- באימות משתמש, השיטות מחזירות רק משאבים שלמשתמש יש גישה אליהם.
לדוגמה, קריאה ל-method spaces.list() עם הרשאת אפליקציה מחזירה את רשימת המרחבים המשותפים שאפליקציית Chat משתייכת אליהם.
קריאה ל-spaces.list() עם הרשאת משתמש מחזירה את רשימת המרחבים המשותפים שהמשתמש חבר בהם. בפועל, יכול להיות שתשתמשו בשני סוגי האימות כשאתם קוראים ל-Chat API, בהתאם לתכנון ולתכונות של אפליקציית Chat.
לקריאות אסינכררוניות ל-Chat API
בטבלה הבאה מפורטות השיטות של Chat API והיקפי ההרשאה הנתמכים שלהן:
| שיטה | תמיכה באימות משתמשים | תמיכה באימות אפליקציה | היקפי ההרשאות הנתמכים | |
|---|---|---|---|---|
| מרחבים | ||||
| איך יוצרים מרחב משותף |
עם אימות משתמשים:
|
|||
| הגדרת מרחב משותף | — |
עם אימות משתמשים:
|
||
| ליצירת מרחב |
עם אימות משתמשים:
|
|||
| רשימת המרחבים המשותפים |
עם אימות משתמשים:
|
|||
| חיפוש מרחבים משותפים | — |
עם אימות משתמשים באמצעות הרשאות אדמין:
|
||
| עדכון מרחב משותף |
עם אימות משתמשים:
|
|||
| מחיקת מרחב משותף |
עם אימות משתמשים:
|
|||
| השלמת תהליך הייבוא של מרחב משותף | — |
עם אימות משתמשים:
|
||
| איך מוצאים צ'אט אישי |
עם אימות משתמשים:
|
|||
| חברים | ||||
| יצירת חבר/ה |
עם אימות משתמשים:
|
|||
| קבלת חבר/ה |
עם אימות משתמשים:
|
|||
| הצגת רשימה של החברים |
עם אימות משתמשים:
|
|||
| מחיקת חברים |
עם אימות משתמשים:
|
|||
| עדכון חבר |
עם אימות משתמשים:
|
|||
| הודעות | ||||
| יצירת הודעה |
באמצעות אימות משתמש:
|
|||
| קבלת הודעה |
עם אימות משתמשים:
|
|||
| הצגת רשימה של הודעות | — |
עם אימות משתמשים:
|
||
| עדכון הודעה |
עם אימות משתמשים:
|
|||
| מחיקת הודעה |
עם אימות משתמשים:
|
|||
| תגובות | ||||
| יצירת תגובה | — |
עם אימות משתמשים:
|
||
| הצגת רשימה של תגובות | — |
עם אימות משתמשים:
|
||
| מחיקת תגובה | — |
באמצעות אימות משתמש:
|
||
| סמלי אמוג'י מותאמים אישית | ||||
| יצירת אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| מחיקת אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| קבלת אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| רשימת סמלי אמוג'י מותאמים אישית | — |
באמצעות אימות משתמש:
|
||
| מדיה וקבצים מצורפים | ||||
| העלאת מדיה כקובץ מצורף | — |
באמצעות אימות משתמש:
|
||
| הורדת המדיה |
עם אימות משתמשים:
|
|||
| איך מקבלים קובץ מצורף להודעה | — |
באמצעות אימות אפליקציה:
|
||
| מצבי קריאה של משתמשים | ||||
| קבלת מצב קריאת מרחב של משתמש | — |
באמצעות אימות משתמש:
|
||
| עדכון סטטוס הקריאה של משתמש במרחב משותף | — |
עם אימות משתמשים:
|
||
| קבלת מצב הקריאה של משתמש בשרשור | — |
עם אימות משתמשים:
|
||
| הגדרות המרחב המשותף של המשתמש | ||||
| קבלת הגדרה של התראות במרחב המשותף של המשתמש | — |
עם אימות משתמשים:
|
||
| עדכון הגדרת ההתראות של המשתמש במרחב המשותף | — |
עם אימות משתמשים:
|
||
| אירועים ב-Spaces | ||||
| הצגת אירועים במרחב המשותף | — |
כשמשתמשים באימות משתמשים, צריך להשתמש בהיקף שמבוסס על
סוג האירוע:
|
||
| הצגת רשימה של אירועים במרחב המשותף | — |
כשמשתמשים באימות משתמשים, צריך להשתמש בהיקף לכל
סוג אירוע שכלול בבקשה:
|
||
באירועי אינטראקציה באפליקציית Chat
בטבלה הבאה מפורטות הדרכים הנפוצות שבהן משתמשים מקיימים אינטראקציה עם אפליקציות צ'אט, והאם נדרש אימות או שהוא נתמך:
| תרחיש | לא נדרש אימות | תמיכה באימות משתמשים | תמיכה באימות אפליקציה | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| קבלת הודעות מ: |
|
|||||||||||||||
| איך עונים להודעות: |
|
|||||||||||||||
| שליחת הודעות חדשות: |
|
|||||||||||||||
נושאים קשורים
- בסקירה הכללית על אימות והרשאה תוכלו לקרוא על תהליך האימות וההרשאה ב-Google Workspace.
- בסקירה הכללית על אימות תוכלו לקרוא על תהליך האימות וההרשאה ב-Google Cloud.
- למידע נוסף על חשבונות שירות, ראו חשבונות שירות.
- תוכלו לקרוא מידע נוסף על האופן שבו ממשקי Google API משתמשים ב-OAuth 2.0 במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
- מגדירים אימות והרשאה באמצעות פרטי כניסה של משתמש או באמצעות חשבון שירות.