הרשמה לאירועים באמצעות 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 מספק אירועים.

כך Google Workspace Event API מספק אירועים לאפליקציה דרך מינוי:

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

המבנה של אירועים ב-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.

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

  • 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.