בדף הזה מופיעה סקירה כללית על Google Workspace Event API, ומוסבר איך אפשר להשתמש ב-API כדי להירשם לאירועים ב-Google Workspace.
אירועים ב-Google Workspace מייצגים שינויים במשאבי Google Workspace, למשל כשיוצרים, מעדכנים או מוחקים משאבים. האפליקציה יכולה להירשם למשאב של Google Workspace כדי לקבל אירועים רלוונטיים שמעניינים אתכם.
איך האפליקציה מקבלת אירועים
כדי לאפשר לאפליקציה לקבל אירועים של Google Workspace, ניתן להשתמש ב-Google Workspace Event API על מנת ליצור מינויים למשאבי Google Workspace.
בדוגמה הבאה מוצג איך Google Workspace Event API שולח אירועים לאפליקציית Google Chat באמצעות מינוי:
- אפליקציית Chat נרשמת למרחב משותף ב-Chat.
- המרחב המשותף ב-Chat ישתנה. לדוגמה, הודעה חדשה תפורסם במרחב המשותף.
- ב-Chat מוצג אירוע לנושא ב-
Google Cloud Pub/Sub, שמשמש כנקודת הקצה להתראות של המינוי. האירוע מכיל נתונים על השינויים. לדוגמה, באירוע שעוסק בהודעה חדשה, האירוע מכיל פרטים על המשאב
Message
שנוצר. - אפליקציית Chat מעבדת את הודעת Google Cloud Pub/Sub שמכילה את האירוע, ואם צריך, מבצעת פעולה.
מונחים חשובים
הרשימה הבאה מפרטת את המונחים הנפוצים ב-Google Workspace Event API:
- אירוע ב-Google Workspace
שינוי במשאב ב-Google Workspace. האירועים מעוצבים בהתאם למפרט CloudEvents, והם יכולים להיות אירוע מינוי או אירוע במחזור חיים:
- אירוע במינוי
- שינוי במשאב Google Workspace שבמעקב, כמו הודעה חדשה במרחב משותף ב-Google Chat. תוכלו לציין כמה פרטים אתם רוצים לקבל על המשאב שהשתנה. למידע נוסף, ראו מבנה האירועים ב-Google Workspace.
- אירוע במחזור החיים
- אירוע לגבי המינוי שלך ל-Google Workspace. אירועים במחזור החיים מודיעים לכם על בעיות ועל מצב המינוי שלכם, כדי שלא תאבדו אירועים של מינויים. כברירת מחדל, המינוי שלכם תמיד מקבל אירועים במחזור החיים. לפרטים נוספים, ראו אירועים במחזור החיים של מינויים ל-Google Workspace.
- מינוי ל-Google Workspace
ישות בעלת שם שעוקבת אחרי משאב מאפליקציה של Google Workspace. מינוי מיוצג על ידי משאב של
Subscription
. מינוי מוגדר לפי הפרטים הבאים:- משאב היעד
- המשאב ב-Google Workspace שרוצים לעקוב אחריו.
המשאב הזה מיוצג בשדה
targetResource
במינוי ל-Google Workspace. כל מינוי יכול לעקוב רק אחרי משאב אחד. למידע על המשאבים של Google Workspace שנתמכים ב-Google Workspace Event API, ראו אירועים נתמכים ב-Google Workspace. - סוגי אירועים
- סוגי השינויים שאתם רוצים לקבל עליהם התראות בקשר למשאב היעד. לדוגמה, אם נרשמתם למרחב משותף ב-Google Chat, תוכלו לבחור אם לקבל אירועים של המרחב המשותף ושל הצאצאים שלו, כמו חברויות או הודעות.
- נקודת הקצה של ההתראה
- נקודת הקצה שבה המינוי ל-Google Workspace מקבל אירועים. Google Workspace Event API תומך בנושאי Google Cloud Pub/Sub כנקודת קצה להתראות. למידע נוסף על השימוש ב-Google Cloud Pub/Sub, עיינו במשאבי העזרה של Google Cloud Pub/Sub.
- אפשרויות מטען ייעודי (payload)
- נתוני האירועים שרוצים לקבל לגבי המשאבים שהשתנו.
אירועים נתמכים ב-Google Workspace
האירועים שהאפליקציה יכולה לקבל אירועים תלויים במשאב היעד של המינוי. בטבלה הבאה מוצגים האירועים הנתמכים לכל משאב יעד אפשרי.
משאב היעד | אופן הלימוד | אירועים נתמכים | מגבלות (אם רלוונטי) | |
---|---|---|---|---|
Google Chat | ||||
מרחבים משותפים ב-Google Chat | //chat.googleapis.com/spaces/SPACE_ID |
פרטים נוספים זמינים במאמר הרשמה לאירועים של Google Chat. |
המשתמש ב-Google Chat שאישר את המינוי צריך להיות חבר במרחב המשותף דרך חשבון Google Workspace או חשבון Google. | |
משתמשי Google Chat | //cloudidentity.googleapis.com/users/USER_ID |
פרטים נוספים זמינים במאמר הרשמה לאירועים של Google Chat. |
המינוי מקבל רק אירועים לגבי המשתמש שאישר את המינוי. משתמש לא יכול לתת הרשאה למינוי בשם משתמשים אחרים. |
|
Google Meet | ||||
מרחבים משותפים ב-Google Meet | //meet.googleapis.com/spaces/SPACE_ID |
פרטים נוספים זמינים במאמר הרשמה לאירועים של Google Meet. |
||
משתמשי Google Meet | //cloudidentity.googleapis.com/users/USER_ID |
פרטים נוספים זמינים במאמר הרשמה לאירועים של Google Meet. |
המינוי מקבל אירועים של מרחבים משותפים שבהם המשתמש הוא אחד מהבאים:
|
המבנה של אירועים ב-Google Workspace
אירועים ב-Google Workspace תואמים למפרט של CloudEvents, שזו הדרך המקובלת בתחום לתיאור נתוני אירועים. אירועים של Google Workspace כוללים את הפרטים הבאים:
בקטע הבא מוסבר על מבנה המאפיינים והנתונים של אירועים ב-Google Workspace.
מאפייני CloudEvent
אירועים ב-Google Workspace כוללים את מאפייני CloudEvents הנדרשים:
מאפיין | תיאור | דוגמה |
---|---|---|
|
סוג הנתונים שהועברו באירוע. |
|
|
מזהה של CloudEvent. |
|
|
מקור האירוע. באירועים של Google Workspace, זה השם המלא של המשאב של המינוי. |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
גרסת המפרט של CloudEvents שנעשה בה שימוש באירוע הזה. |
|
|
המשאב של Google Workspace שבו התרחש האירוע. |
|
|
חותמת הזמן של האירוע, בפורמט RFC 3339. |
|
|
סוג האירוע ב-Google Workspace. |
|
נתוני אירוע
נתוני אירועים הם מטען ייעודי (payload) שמייצג שינוי במשאב היעד של המינוי, כולל משאבי הצאצא של משאב היעד. במינוי, תוכלו לציין אם אתם רוצים שהמטען הייעודי (payload) יכלול נתונים על המשאב שהשתנה, או רק את שם המשאב שהשתנה.
לדוגמה, אם יש לכם מינוי למרחב משותף ב-Chat, תוכלו לקבל אירועים על הודעות חדשות במרחב המשותף. באירועים שקשורים להודעות חדשות, נתוני האירועים מכילים מטען ייעודי (payload) עם המשאב spaces.message
שנוצר ב-Chat.
כשיוצרים מינוי, אפשר לציין כמה נתוני משאבים ייכללו באירועים שהאפליקציה תקבל:
- Include resource data: (כולל נתוני משאבים): מכיל חלק מהשדות של המשאב שהשתנה או את כל השדות. אם בוחרים לכלול נתוני משאבים, משך המינוי מוגבל ל-4 שעות, או ל-24 שעות אם משתמשים בהענקת גישה ברמת הדומיין.
- החרגת נתוני משאבים: מכיל רק את שם המשאב שהשתנה. משך המינוי הוא עד 7 ימים. כדי לקבל פרטים על האירוע, אפשר לשלוח שאילתה למשאב באמצעות שם המשאב.
האפשרויות האלה לנתוני אירועים מיוצגות בשדה payloadOptions
של המינוי.
אירועים כהודעות של Google Cloud Pub/Sub
המינויים ל-Google Workspace Event API משתמשים בנושאים של Google Cloud Pub/Sub כנקודת הקצה להתראות שמקבלת אירועים של Google Workspace. האירועים מקודדים כהודעות Google Cloud Pub/Sub. האפליקציה יכולה לעבד את הודעת Google Cloud Pub/Sub כדי לבצע פעולה או להגיב לאירוע.
בדוגמה הבאה מוצגת הודעת Google Cloud Pub/Sub שמכילה אירוע לגבי הודעה מעודכנת במרחב משותף ב-Chat:
{
"message":
{
"attributes":
{
"ce-datacontenttype": "application/json",
"ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
"ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
"ce-specversion": "1.0",
"ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
"ce-time": "2023-09-07T21:37:53.274191Z",
"ce-type": "google.workspace.chat.message.v1.updated"
},
"data": "EVENT_DATA",
"messageId": "PUBSUB_MESSAGE_ID",
"orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
"publishTime": "2023-09-07T21:37:53.713Z"
}
}
שימו לב לשדות הבאים:
attributes
: מאפיינים עבור CloudEvent, שכוללים את סוג האירוע. במקרה הזה, האירוע עוסק בהודעה מעודכנת במרחב המשותף.data
: נתוני האירועים עם הפרטים של משאבspaces.message
המעודכן, בפורמט של מחרוזת בקידוד Base64.messageId
: המזהה של הודעת Google Cloud Pub/Sub.
למידע נוסף על אופן ציון של CloudEvents בהודעות של Google Cloud Pub/Sub, ראו קישור של פרוטוקול Google Cloud Pub/Sub ל-CloudEvents.
נושאים קשורים
- הרשמה לאירועים ב-Google Chat
- אירועים במחזור החיים של מינויים ל-Google Workspace
- בחירת היקפי הרשאות של Google Workspace Event API
- יצירת מינוי ל-Google Workspace