אימות והרשאה הם מנגנונים המשמשים לאימות הזהות ולגישה למשאבים, בהתאמה. במאמר הזה מוסבר איך פועלים האימות וההרשאות באפליקציות ל-Chat ובבקשות API ל-Chat.
סקירה כללית על התהליך
בתרשים הבא מוצגים השלבים הכלליים של אימות והרשאה ב-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 כדי שהמשתמש יוכל להחליט אם להעניק לאפליקציה גישה לנתונים המבוקשים. אימות באמצעות חשבון שירות לא מחייב הסכמה מהמשתמש.
שליחת בקשה שאושרה למשאבים: אם המשתמש מסכים להיקפי ההרשאות, ה-App Bundle משלב בבקשה את פרטי הכניסה ואת ההיקפים שאושרו על ידי המשתמשים. הבקשה נשלחת לשרת ההרשאות של Google כדי לקבל אסימון גישה.
Google מחזירה אסימון גישה: אסימון הגישה מכיל רשימה של ההיקפים שהוענקו. אם רשימת ההיקפים שמוחזרת מוגבלת יותר מההיקפים הנדרשים, האפליקציה תשבית את כל התכונות שמוגבלות על ידי האסימון.
גישה למשאבים המבוקשים: האפליקציה משתמשת באסימון הגישה מ-Google כדי להפעיל את Chat API ולגשת למשאבים של Chat API.
קבלת אסימון רענון (אופציונלי): אם האפליקציה שלכם צריכה לגשת ל-Google Chat API מעבר לתוחלת החיים של אסימון גישה יחיד, היא יכולה לקבל אסימון רענון. למידע נוסף, תוכלו לקרוא את המאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
בקשת משאבים נוספים: אם האפליקציה צריכה גישה נוספת, היא מבקשת מהמשתמש להקצות היקפי הרשאות חדשים, וכתוצאה מכך נוצרת בקשה חדשה לקבלת אסימון גישה (שלבים 3-6).
מתי צריך לבצע אימות באפליקציות ל-Chat
אפליקציות צ'אט יכולות לשלוח הודעות בתגובה לאינטראקציה של משתמש, או באופן אסינכרוני. הם יכולים גם להשלים משימות בשם המשתמש, כמו ליצור מרחב משותף ב-Chat או לקבל רשימה של אנשים במרחב משותף ב-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 באמצעות השיטה
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. אפשר גם לעיין במאמר שלבים לאפליקציות שמבקשות היקפי גישה מוגבלים.
אם האפליקציה שלכם זקוקה לגישה לממשקי 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 יכולה לקרוא ל-methods של 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 והיקפי ההרשאות הנתמכים שלהן:
| שיטה | תמיכה באימות משתמשים | תמיכה באימות אפליקציות | היקפי ההרשאות הנתמכים | |
|---|---|---|---|---|
| מרחבים משותפים | ||||
| איך יוצרים מרחבים משותפים |
עם אימות משתמשים:
|
|||
| הגדרת מרחב משותף | — |
עם אימות משתמשים:
|
||
| ליצירת מרחב |
עם אימות משתמשים:
|
|||
| רשימת המרחבים המשותפים |
עם אימות משתמשים:
|
|||
| חיפוש מרחבים משותפים | — |
עם אימות משתמשים באמצעות הרשאות אדמין:
|
||
| איך משנים את המרחב המשותף |
באמצעות אימות משתמש:
|
|||
| איך מוחקים מרחבים משותפים |
עם אימות משתמשים:
|
|||
| השלמת תהליך הייבוא של מרחב משותף | — |
עם אימות משתמשים:
|
||
| איך מוצאים צ'אט אישי |
עם אימות משתמשים:
|
|||
| חברים | ||||
| איך יוצרים חברי מועדון |
באמצעות אימות משתמש:
|
|||
| קבלת חבר/ה |
באמצעות אימות משתמש:
|
|||
| הצגת רשימה של החברים |
באמצעות אימות משתמש:
|
|||
| מחיקת חברים |
עם אימות משתמשים:
|
|||
| עדכון חברי מועדון |
עם אימות משתמשים:
|
|||
| הודעות | ||||
| יצירת הודעה |
באמצעות אימות משתמש:
|
|||
| קבלת הודעה |
באמצעות אימות משתמש:
|
|||
| הצגת רשימה של הודעות | — |
באמצעות אימות משתמש:
|
||
| עדכון הודעה |
באמצעות אימות משתמש:
|
|||
| מחיקת הודעה |
באמצעות אימות משתמש:
|
|||
| תגובות | ||||
| יצירת תגובה | — |
עם אימות משתמשים:
|
||
| הצגת רשימה של תגובות | — |
עם אימות משתמשים:
|
||
| מחיקת תגובה באמוג'י | — |
באמצעות אימות משתמש:
|
||
| סמלי אמוג'י מותאמים אישית | ||||
| יצירת אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| איך מוחקים אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| קבלת אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| רשימת סמלי אמוג'י בהתאמה אישית | — |
עם אימות משתמשים:
|
||
| מדיה וקבצים מצורפים | ||||
| העלאת מדיה כקובץ מצורף | — |
עם אימות משתמשים:
|
||
| הורדת המדיה |
באמצעות אימות משתמש:
|
|||
| איך מקבלים קובץ מצורף להודעה | — |
באמצעות אימות אפליקציה:
|
||
| מצבי קריאה של משתמשים | ||||
| קבלת מצב קריאת מרחב של משתמש | — |
עם אימות משתמשים:
|
||
| עדכון מצב הקריאה של מרחב משתמש | — |
עם אימות משתמשים:
|
||
| קבלת מצב הקריאה של משתמש בשרשור | — |
באמצעות אימות משתמש:
|
||
| הגדרות המרחב המשותף של המשתמש | ||||
| איך בודקים מהי הגדרת ההתראות של המשתמש במרחב המשותף | — |
עם אימות משתמשים:
|
||
| עדכון הגדרת ההתראות של המשתמש במרחב המשותף | — |
באמצעות אימות משתמש:
|
||
| אירועים במרחב המשותף | ||||
| הצגת אירועים במרחב המשותף | — |
באימות משתמשים, צריך להשתמש בהיקף שמבוסס על סוג האירוע:
|
||
| רשימת האירועים במרחב המשותף | — |
כשמשתמשים באימות משתמש, צריך להשתמש בהיקף לכל
סוג אירוע שכלול בבקשה:
|
||
באירועי אינטראקציה של אפליקציית Chat
בטבלה הבאה מפורטות הדרכים הנפוצות שבהן משתמשים יכולים לקיים אינטראקציה עם אפליקציות צ'אט, והאם נדרש או נתמך אימות:
| תרחיש | לא נדרש אימות | תמיכה באימות משתמשים | תמיכה באימות אפליקציות | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| קבלת הודעות מ: |
|
|||||||||||||||
| איך עונים להודעות: |
|
|||||||||||||||
| שליחת הודעות חדשות: |
|
|||||||||||||||
נושאים קשורים
- בסקירה הכללית על אימות והרשאה תוכלו לקרוא על תהליך האימות וההרשאה ב-Google Workspace.
- בסקירה הכללית על אימות תוכלו לקרוא על תהליך האימות וההרשאה ב-Google Cloud.
- למידע נוסף על חשבונות שירות, ראו חשבונות שירות.
- מידע נוסף על האופן שבו Google APIs משתמשים ב-OAuth 2.0 זמין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
- מגדירים אימות והרשאה באמצעות פרטי כניסה של משתמש או באמצעות חשבון שירות.