הרשמה לאירועים באמצעות Google Workspace Events API

בדף הזה יש סקירה כללית של 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 מעביר אירועים.
איור 1. דוגמה לאופן שבו Google Workspace Event API מעביר אירועים לאפליקציית Chat.

בדוגמה הבאה, Google Workspace Event API מעביר אירועים לאפליקציית Google Chat באמצעות מינוי:

  1. אפליקציית Chat נרשם למרחב משותף ב-Chat.
  2. המרחב המשותף ב-Chat ישתנה. לדוגמה, תפורסם הודעה חדשה במרחב.
  3. ב-Chat יישלח אירוע לנושא ב- Google Cloud Pub/Sub, שמשמש כנקודת הקצה להתראות של המינוי. האירוע מכיל נתונים על השינויים. לדוגמה, לאירוע של הודעה חדשה, האירוע מכיל פרטים על המשאב Message שנוצר.
  4. אפליקציית 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 שנתמכים ב-Google Workspace Event API.
סוגי אירועים
סוגי השינויים שרוצים לקבל עליהם התראות לגבי משאב היעד. לדוגמה, אם נרשמתם למרחב משותף ב-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

כדי להירשם לכל המרחבים המשותפים שבהם המשתמשים חברים:

//chat.googleapis.com/spaces/-
  • הודעות
  • מועדוני חברים
  • תגובות
  • מרחב

פרטים נוספים זמינים במאמר הרשמה לאירועים ב-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 שמשויך למרחב המשותף בפגישה.

המבנה של אירועים ב-Google Workspace

האירועים ב-Google Workspace תואמים למפרט של CloudEvents, שהוא שיטה סטנדרטית בתחום לתיאור נתוני אירועים. אירועי Google Workspace כוללים את הפרטים הבאים:

בקטע הבא מוסבר המבנה של המאפיינים והנתונים של אירועים ב-Google Workspace.

מאפייני CloudEvent

האירועים ב-Google Workspace כוללים את מאפייני CloudEvents הנדרשים:

מאפיין תיאור דוגמה

datacontenttype

סוג הנתונים שהועברו באירוע.

application/json

id

מזהה של CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

מקור האירוע. לאירועים של Google Workspace, זהו השם המלא של מקור המידע במינוי. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

גרסת המפרט של CloudEvents שמשמשת לאירוע הזה.

1.0

subject

המשאב ב-Google Workspace שבו התרחש האירוע.

//chat.googleapis.com/spaces/AAAABBBBBBB

time

חותמת הזמן שבה האירוע התרחש, בפורמט RFC 3339.

2023-09-07T21:37:36.260127Z

type

סוג האירוע ב-Google Workspace.

google.workspace.chat.message.v1.created

נתוני אירוע

נתוני אירועים הם מטען ייעודי (payload) שמייצג שינוי במשאב היעד של המינוי, כולל משאבי הצאצא של משאב היעד. במינוי, אפשר לציין אם רוצים שהמטען הייעודי (Payload) יכלול נתונים על המשאב שהשתנה או רק את השם של המשאב שהשתנה.

לדוגמה, אם יש לכם מינוי למרחב משותף ב-Chat, אתם יכולים לקבל אירועים על הודעות חדשות במרחב המשותף. באירועים שקשורים להודעות חדשות, נתוני האירועים מכילים מטען ייעודי (payload) עם המשאב spaces.message של Chat שנוצר.

כשיוצרים מינוי, אפשר לציין כמה נתוני משאבים כלולים באירועים שהאפליקציה מקבלת:

  • הכללת נתוני המשאבים: מכילה חלק מהשדות של המשאב שהשתנה או את כל השדות. אם בוחרים לכלול נתוני משאבים, משך המינוי מוגבל ל-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.