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