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

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

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

אירועים נתמכים ב-Google Workspace

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

משאב היעד אירועים נתמכים
מרחבים משותפים ב-Google Chat
  • הודעות
  • מועדון החברים
  • תגובות
  • רווח
משתמשי Google Chat
  • מועדון החברים
מרחבי פגישות ב-Google Meet
  • כנסים
  • סשנים של משתתפים
  • הקלטות
  • תמלילים
משתמשי Google Meet
  • כנסים
  • סשנים של משתתפים
  • הקלטות
  • תמלילים

מידע נוסף זמין במדריכים הבאים:

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

נתוני אירוע

נתוני האירוע הם מטען ייעודי שמייצג שינוי במשאב היעד של המינוי, כולל משאבים צאצאים של משאב היעד. במינוי, תוכלו לציין אם תרצו שנתוני העומס יכללו נתונים על המשאב שהשתנה, או רק את שם המשאב שהשתנה.

לדוגמה, אם יש לכם מינוי למרחב משותף ב-Chat, תוכלו לקבל התראות על הודעות חדשות במרחב המשותף. באירועים לגבי הודעות חדשות, נתוני האירוע מכילים עומס שימושי עם המשאב 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"
        },
        "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.