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

אפשרויות של מטען ייעודי (payload)

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

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

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

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

• הרשמה לאירועים ב-Google Chat
• הרשמה לאירועים ב-Google Drive
• הרשמה לאירועים ב-Google Meet

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

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

• מאפיינים של CloudEvent.
• נתונים על משאב Google Workspace שהשתנה כתוצאה מהאירוע

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

מאפייני CloudEvent

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

נתוני אירוע

נתוני האירוע הם מטען ייעודי (Payload) שמייצג שינוי במשאב היעד של המינוי, כולל משאבי צאצא של משאב היעד. במינוי, אפשר לציין אם רוצים שהמטען הייעודי (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"
        },
        "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.

נושאים קשורים

• בחירת היקפי ההרשאות של Google Workspace Events API
• יצירת מינוי ל-Google Workspace