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

בדף הזה מוצגת סקירה כללית של Google Workspace Events API, ואיך אפשר להשתמש ב-API כדי להירשם לאירועים ב-Google Workspace.

אירועים ב-Google Workspace מייצגים שינויים במשאבים של Google Workspace, כמו יצירה, עדכון או מחיקה של משאבים. אפשר להירשם לאפליקציה למשאב של Google Workspace כדי לקבל אירועים רלוונטיים שמעניינים אתכם.

איך האפליקציה מקבלת אירועים

כדי לאפשר לאפליקציה לקבל אירועים של Google Workspace, עליכם להשתמש ב-Google Workspace Events API כדי ליצור מינויים למשאבים של Google Workspace.

איור של האופן שבו האירועים נוצרים ב-Google Workspace Events API.

כך ה-Google Workspace Events API מציג אירועים באפליקציה דרך מינוי:

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

מונחים חשובים

רשימה של מונחים נפוצים ב-Google Workspace Events 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 Events API.
סוגי אירועים
סוגי השינויים שרוצים לקבל עליהם התראות במשאב היעד. לדוגמה, אם נרשמתם למרחב משותף ב-Google Chat, אתם יכולים לבחור אם לקבל אירועים של המרחב המשותף ושל המשאבים הצאצאים, כמו חברויות והודעות.
נקודת קצה של התראה
נקודת הקצה (endpoint) שהמינוי ל-Google Workspace מקבל אירועים. ב-Google Workspace Events API יש תמיכה בנושאי Google Cloud Pub/Sub כנקודת קצה להתראות. למידע נוסף על השימוש ב-Google Cloud Pub/Sub, עיינו במשאבי העזרה של Google Cloud Pub/Sub.
אפשרויות של מטען ייעודי (payload)
נתוני האירועים שרוצים לקבל לגבי משאבים שהשתנו.

המשאבים הנתמכים של Google Workspace

Google Workspace Events API תומך במינויים למשאבי היעד הבאים של Google Workspace. תוכלו להירשם לכל משאב יעד כדי לקבל אירועים שקשורים לילדים או למשאבים קשורים:

משאב יעד אופן הלימוד מקורות מידע נתמכים לאירועים מגבלות (אם רלוונטי)
מרחבים משותפים ב-Google Chat //chat.googleapis.com/spaces/SPACE_ID
  • הודעות
  • חברי מועדון
  • תגובות
  • מרחב

לפרטים נוספים, אפשר לקרוא את המאמר הרשמה לאירועים של Google Chat.		 המשתמש שאישר את המינוי ב-Google Chat צריך להיות חבר במרחב המשותף דרך חשבון Google Workspace או חשבון Google שלו.
מרחבים משותפים ב-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) שמייצג שינוי במשאב היעד של המינוי, כולל משאבי צאצא של משאב היעד. במינוי, אפשר לציין אם המטען הייעודי יכלול נתונים על המשאב שהשתנה, או רק את השם של המשאב שהשתנה.

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

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

  • Include resource data: מכיל חלק מהשדות של המשאב שהשתנה, או את כל השדות שלו. אם תבחרו לכלול נתוני משאבים, משך המינוי שלכם מוגבל ל-4 שעות, או ל-24 שעות אם אתם משתמשים בהענקת גישה ברמת הדומיין.
  • החרגת נתוני משאבים: מכילה רק את השם של המשאב שהשתנה. משך המינוי יכול להימשך עד 7 ימים. כדי לקבל פרטים על האירוע, אפשר להריץ שאילתה על המשאב באמצעות שם המשאב.

האפשרויות האלה לנתוני אירועים מיוצגות בשדה payloadOptions של המינוי.

קבלת אירועים כהודעות Google Cloud Pub/Sub

המינויים ל-Google Workspace Events 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",
            "previoussyncwatermark": "2023-09-07T21:37:37.823023Z",
            "syncwatermark": "2023-09-07T21:37:53.274191Z"
        },
        "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 Protocol Binding for CloudEvents.