יצירת מינוי ל-Google Workspace

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

בדף הזה מוסבר איך ליצור מינוי ל-Google Workspace:

  1. מגדירים את הסביבה.
  2. יוצרים נושא ב-Google Cloud Pub/Sub ונרשמים אליו. המסמך הזה משמש כנקודת קצה לקבלת אירועים מ-Google Workspace.
  3. מפעילים את השיטה create של Google Workspace Events API במשאב Subscription.
  4. בודקים את המינוי ל-Google Workspace כדי לוודא שהנושא ב-Pub/Sub מקבל אירועים שנרשמתם אליהם.
  5. אם רוצים, אפשר להגדיר איך להעביר אירועים לנקודת קצה (endpoint) של האפליקציה, כדי שהאפליקציה תוכל לעבד את האירוע ולבצע פעולה במקרה הצורך.

דרישות מוקדמות

Apps Script

  • כדי להשתמש בפקודות של Google Cloud CLI במדריך הזה:
    1. מתקינים את Google Cloud CLI.
    2. כדי לאתחל את ה-CLI של gcloud, מריצים את הקוד הבא:
      3.   gcloud init
  • פרויקט Apps Script:
    • משתמשים בפרויקט בענן ב-Google במקום בפרויקט ברירת המחדל שנוצר באופן אוטומטי על ידי Apps Script.
    • כל היקפי ההרשאות שהוספתם כדי להגדיר את מסך ההסכמה ל-OAuth, צריכים להופיע גם בקובץ appsscript.json בפרויקט שלכם ב-Apps Script. לדוגמה, אם ציינתם את ההיקף chat.messages, הוסיפו את הפרטים הבאים: 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages"
]
    • מפעילים את השירות המתקדם Google Workspace Events.

Python

  • ‫Python 3.6 ואילך
  • כלי ניהול החבילות pip
  • ספריות הלקוח העדכניות של Google ל-Python. כדי להתקין או לעדכן אותם, מריצים את הפקודה הבאה בממשק שורת הפקודה: 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • כדי להשתמש בפקודות של Google Cloud CLI במדריך הזה:
    1. מתקינים את Google Cloud CLI.
    2. כדי לאתחל את ה-CLI של gcloud, מריצים את הקוד הבא:
      3.   gcloud init

הגדרת הסביבה

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

הפעלת Google Workspace Events API ו-Google Cloud Pub/Sub API

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

מסוף Google Cloud

במסוף Google Cloud, פותחים את פרויקט הענן של האפליקציה ב-Google Cloud ומפעילים את Google Workspace Events API ואת Pub/Sub API:

הפעלת ממשקי ה-API

gcloud

  1. בספריית העבודה, נכנסים לחשבון Google:

    gcloud auth login

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

    gcloud config set project PROJECT_ID

    מחליפים את PROJECT_ID במזהה הפרויקט של פרויקט בענן של האפליקציה.

  3. מפעילים את Google Workspace Events API ואת Google Cloud Pub/Sub API:

    gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

יצירת פרטי כניסה של מזהה לקוח ב-OAuth

בוחרים את סוג האפליקציה כדי לקבל הוראות ספציפיות ליצירת מזהה לקוח ב-OAuth:

אפליקציית אינטרנט

  1. במסוף Google Cloud, פותחים את התפריט > Google Auth platform > Clients.

    מעבר אל "לקוחות"

  2. לוחצים על Create Client.
  3. לוחצים על Application type‏ > Web application.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. מוסיפים מזהי URI מורשים שקשורים לאפליקציה:
    • אפליקציות בצד הלקוח (JavaScript) – בקטע מקורות מורשים של JavaScript, לוחצים על הוספת URI. אחר כך מזינים את ה-URI שבו רוצים להשתמש לבקשות מהדפדפן. השדה הזה מזהה את הדומיינים שמהם האפליקציה יכולה לשלוח בקשות API לשרת OAuth 2.0.
    • אפליקציות בצד השרת (Java,‏ Python ועוד) – בקטע Authorized redirect URIs, לוחצים על Add URI. אחר כך מזינים את ה-URI של נקודת הקצה שאליו שרת OAuth 2.0 יכול לשלוח תגובות.
  6. אופציונלי: אם האפליקציה היא סוכן AI שמבצע פעולות בשם המשתמשים, בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. אם האפליקציה תומכת גם בתהליכי עבודה של סוכני AI וגם בתכונות רגילות למשתמשים, צריך ליצור לקוחות OAuth נפרדים לכל אחד מהם. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את הלקוח.
  7. לוחצים על יצירה.

    פרטי הכניסה החדשים שנוצרו מופיעים בקטע OAuth 2.0 Client IDs.

    שימו לב שסודות לקוח לא משמשים לאפליקציות אינטרנט.

Android

  1. במסוף Google Cloud, פותחים את התפריט > Google Auth platform > Clients.

    מעבר אל "לקוחות"

  2. לוחצים על Create Client.
  3. לוחצים על Application type‏ > Android.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה שם החבילה, מזינים את שם החבילה מהקובץ AndroidManifest.xml.
  6. בשדה טביעת אצבע לאישור SHA-1, מזינים את טביעת האצבע לאישור SHA-1 שנוצרה.
  7. אופציונלי: אם האפליקציה היא סוכן AI שמבצע פעולות בשם המשתמשים, בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. אם האפליקציה תומכת גם בתהליכי עבודה של סוכני AI וגם בתכונות רגילות למשתמשים, צריך ליצור לקוחות OAuth נפרדים לכל אחד מהם. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את הלקוח.
  8. לוחצים על יצירה.

    פרטי הכניסה החדשים שנוצרו מופיעים בקטע OAuth 2.0 Client IDs.

iOS

  1. במסוף Google Cloud, פותחים את התפריט > Google Auth platform > Clients.

    מעבר אל "לקוחות"

  2. לוחצים על Create Client.
  3. לוחצים על Application type‏ > iOS.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה מזהה חבילה, מזינים את מזהה החבילה כפי שהוא מופיע בקובץ Info.plist של האפליקציה.
  6. אופציונלי: אם האפליקציה מופיעה ב-App Store של אפל, מזינים את המזהה של App Store.
  7. אופציונלי: בשדה מזהה צוות, מזינים את המחרוזת הייחודית בת 10 התווים שנוצרה על ידי אפל והוקצתה לצוות שלכם.
  8. אופציונלי: אם האפליקציה היא סוכן AI שמבצע פעולות בשם המשתמשים, בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. אם האפליקציה תומכת גם בתהליכי עבודה של סוכני AI וגם בתכונות רגילות למשתמשים, צריך ליצור לקוחות OAuth נפרדים לכל אחד מהם. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את הלקוח.
  9. לוחצים על יצירה.

    פרטי הכניסה החדשים שנוצרו מופיעים בקטע OAuth 2.0 Client IDs.

אפליקציית Chrome

  1. במסוף Google Cloud, פותחים את התפריט > Google Auth platform > Clients.

    מעבר אל "לקוחות"

  2. לוחצים על Create Client.
  3. לוחצים על Application type‏ > תוסף ל-Chrome.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה מזהה פריט, מזינים את מחרוזת המזהה הייחודית של האפליקציה, שמורכבת מ-32 תווים. ערך המזהה הזה מופיע בכתובת ה-URL של האפליקציה בחנות האינטרנט של Chrome ובמרכז השליטה למפתחים בחנות האינטרנט של Chrome.
  6. אופציונלי: אם האפליקציה היא סוכן AI שמבצע פעולות בשם המשתמשים, בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. אם האפליקציה תומכת גם בתהליכי עבודה של סוכני AI וגם בתכונות רגילות למשתמשים, צריך ליצור לקוחות OAuth נפרדים לכל אחד מהם. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את הלקוח.
  7. לוחצים על יצירה.

    פרטי הכניסה החדשים שנוצרו מופיעים בקטע OAuth 2.0 Client IDs.

אפליקציה לשולחן העבודה

  1. במסוף Google Cloud, פותחים את התפריט > Google Auth platform > Clients.

    מעבר אל "לקוחות"

  2. לוחצים על Create Client.
  3. לוחצים על Application type‏ > Desktop app.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. אופציונלי: אם האפליקציה היא סוכן AI שמבצע פעולות בשם המשתמשים, בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. אם האפליקציה תומכת גם בתהליכי עבודה של סוכני AI וגם בתכונות רגילות למשתמשים, צריך ליצור לקוחות OAuth נפרדים לכל אחד מהם. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את הלקוח.
  6. לוחצים על יצירה.

    פרטי הכניסה החדשים שנוצרו מופיעים בקטע OAuth 2.0 Client IDs.

טלוויזיות ומכשירים מוגבלים לקליטת נתונים

  1. במסוף Google Cloud, פותחים את התפריט > Google Auth platform > Clients.

    מעבר אל "לקוחות"

  2. לוחצים על Create Client.
  3. לוחצים על Application type‏ > TVs and Limited Input devices.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. אופציונלי: אם האפליקציה היא סוכן AI שמבצע פעולות בשם המשתמשים, בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. אם האפליקציה תומכת גם בתהליכי עבודה של סוכני AI וגם בתכונות רגילות למשתמשים, צריך ליצור לקוחות OAuth נפרדים לכל אחד מהם. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את הלקוח.
  6. לוחצים על יצירה.

    פרטי הכניסה החדשים שנוצרו מופיעים בקטע OAuth 2.0 Client IDs.

Universal Windows Platform (UWP)‎

  1. ב-Google API Console, נכנסים לתפריט > > לקוחות.

    מעבר אל "לקוחות"

  2. לוחצים על Create Client.
  3. לוחצים על Application type‏ > Universal Windows Platform (UWP).
  4. בשדה "שם", מקלידים שם לפרטי הכניסה. השם הזה מוצג רק ב-Google API Console.
  5. בשדה "מזהה החנות", מזינים את הערך הייחודי של מזהה האפליקציה ב-Microsoft Store, שמורכב מ-12 תווים. המזהה הזה מופיע בכתובת ה-URL של האפליקציה ב-Microsoft Store וב-Partner Center.
  6. אופציונלי: אם האפליקציה היא סוכן AI שמבצע פעולות בשם המשתמשים, בוחרים באפשרות שימוש בלקוח הזה לסוכן מבוסס-AI. אם האפליקציה תומכת גם בתהליכי עבודה של סוכני AI וגם בתכונות רגילות למשתמשים, צריך ליצור לקוחות OAuth נפרדים לכל אחד מהם. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את הלקוח.
  7. לוחצים על יצירה.

    פרטי הכניסה החדשים שנוצרו מופיעים בקטע OAuth 2.0 Client IDs.

מורידים את קובץ ה-JSON של סוד הלקוח

קובץ סוד הלקוח הוא ייצוג ב-JSON של פרטי הכניסה של מזהה הלקוח ב-OAuth, שהאפליקציה יכולה להפנות אליהם כשהיא מספקת פרטי כניסה.

  1. ב-Google API Console, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. בקטע OAuth 2.0 Client IDs, לוחצים על מזהה הלקוח שיצרתם.

  3. לוחצים על הורדת קובץ JSON.

  4. שומרים את הקובץ בשם credentials.json.

יצירת נושא Pub/Sub והרשמה אליו

בקטע הזה יוצרים נושא ב-Pub/Sub ומינוי לנושא. נושא ה-Pub/Sub משמש כנקודת הקצה של ההתראות שבה המינוי ל-Google Workspace מקבל אירועים.

מידע נוסף על יצירה וניהול של נושאי Pub/Sub זמין במאמרי העזרה של Pub/Sub.

כדי ליצור נושא Pub/Sub ולהירשם אליו:

Google API Console

  1. ב-Google API Console, נכנסים לדף Pub/Sub:

    כניסה לדף Google Cloud Pub/Sub

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

  2. לוחצים על Create topic ומבצעים את הפעולות הבאות:

    1. נותנים שם לנושא, למשל workspace-events-topic.
    2. משאירים את האפשרות הוספת מינוי שמוגדר כברירת מחדל מסומנת. שירות Pub/Sub נותן למינוי ברירת המחדל הזה שם שדומה לשם הנושא, למשל workspace-events-topic-sub.
    3. אופציונלי: מעדכנים או מגדירים מאפיינים נוספים לנושא.

  3. לוחצים על יצירה. השם המלא של הנושא מופיע בפורמט projects/PROJECT_ID/topics/TOPIC_ID. תצטרכו להשתמש בשם המלא הזה בשלב מאוחר יותר.

  4. כדי לתת גישה לפרסום הודעות Pub/Sub בנושא שלכם:

    1. בדף של הנושא, עוברים לחלונית הצדדית ופותחים את הכרטיסייה Permissions.
    2. לוחצים על Add Principal.
    3. בשדה Add principals, מוסיפים את חשבון השירות של אפליקציית Google Workspace שמעבירה אירועים למינוי:
      1. לאירועים ב-Chat, chat-api-push@system.gserviceaccount.com.
      2. לאירועים ב-Drive, drive-api-event-push@system.gserviceaccount.com.
      3. באירועים ב-Meet, meet-api-event-push@system.gserviceaccount.com.
    4. בתפריט Assign roles, בוחרים באפשרות Pub/Sub Publisher.
    5. לוחצים על שמירה. יכול להיות שיעברו כמה דקות עד שההרשאות של הנושא יעודכנו.

gcloud

  1. בפרויקט בענן, יוצרים נושא באמצעות הפקודה הבאה:

    gcloud pubsub topics create TOPIC_ID

    מחליפים את TOPIC_ID במזהה ייחודי לנושא, למשל workspace-events-topic.

    הפלט מציג את שם הנושא המלא, בפורמט projects/PROJECT_ID/topics/TOPIC_ID. שימו לב לשם, וודאו שהערך של PROJECT_ID הוא מזהה הפרויקט בענן של האפליקציה. השתמשו בשם הנושא בשלב הבא, וצרו את המינוי ל-Google Workspace בהמשך.

  2. נותנים הרשאת גישה לפרסום הודעות בנושא:

    gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

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

    • ‫TOPIC_NAME: השם המלא של הנושא, שהוא הפלט מהשלב הקודם. בפורמט projects/PROJECT_ID/topics/TOPIC_ID.

    • GOOGLE_WORKSPACE_APPLICATION: האפליקציה של Google Workspace שצריכה להעביר אירועים למינוי:

    יכול להיות שיעברו כמה דקות עד שההרשאות של הנושא יתעדכנו.

  3. יוצרים מינוי Pub/Sub לנושא:

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

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

    • ‫SUBSCRIPTION_NAME: שם המינוי, למשל workspace-events-subscription.
    • ‫TOPIC_NAME: שם הנושא שיצרתם בשלב הקודם.

הרשמה למשאב ב-Google Workspace

בקטע הזה נרשמים למשאב של Google Workspace שרוצים לעקוב אחרי האירועים שלו.

בחירה וזיהוי של משאב היעד

במינוי ל-Google Workspace, משאב היעד הוא המשאב ב-Google Workspace שאתם עוקבים אחרי האירועים שלו. משאב היעד מיוצג בשדה targetResource של המינוי, בפורמט של שם המשאב המלא. לדוגמה, במינוי שעוקב אחרי מרחב משותף ב-Chat‏ (spaces/AAAABBBBBBB), הערך של targetResource הוא //chat.googleapis.com/spaces/AAAABBBBBBB.

זיהוי משאב יעד ל-Chat

משאב היעד פורמט מגבלות
רווח

//chat.googleapis.com/spaces/SPACE

כאשר SPACE הוא המזהה ב שם המשאב של המשאב space ב-Chat API. אפשר לקבל את המזהה מכתובת ה-URL של המרחב המשותף או באמצעות ה-method‏ spaces.list().

 המשתמש או האפליקציה ל-Chat שמאשרים את המינוי חייבים להיות חברים במרחב המשותף באמצעות חשבון Google או חשבון Google Workspace שלהם. תמיכה:
כל המרחבים המשותפים של המשתמש

//chat.googleapis.com/spaces/-

 המינוי מקבל רק אירועים מהמרחבים שבהם המשתמש חבר באמצעות חשבון Google או Google Workspace שלו. תומך רק באימות משתמשים.
משתמש

//cloudidentity.googleapis.com/users/USER

כאשר USER הוא המזהה ב שם המשאב של המשאב user ב-Chat API. פרטים נוספים זמינים במאמר זיהוי וציון של משתמשי Google Chat.

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

//admin.googleapis.com/customers/CUSTOMER

כאשר CUSTOMER הוא מספר הלקוח. אפשר גם להשתמש בכינוי my_customer לדומיין של הלקוח באפליקציית Chat.

המינוי מקבל אירועים מכל המרחבים והמשתמשים שמנוהלים על ידי הדומיין של הלקוח. תומך רק באימות אפליקציה באישור אדמין.

זיהוי משאב יעד ב-Drive

משאב היעד פורמט מגבלות (אם רלוונטי)
קובץ //drive.googleapis.com/files/FILE

כאשר FILE הוא המזהה ב שם המשאב של המשאב files ב-Drive API. אפשר לקבל את המזהה מכתובת ה-URL של הקובץ או באמצעות ה-method‏ files.list.

למשתמש שמאשר את המינוי צריכה להיות הרשאה בקובץ במינוי שקשור לאירוע ההרשמה.
אחסון שיתופי //drive.googleapis.com/drives/DRIVE

כאשר DRIVE הוא המזהה ב שם המשאב של המשאב drives ב-Drive API. אפשר לקבל את המזהה מכתובת ה-URL של האחסון השיתופי או באמצעות ה-method‏ drives.list.

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

זיהוי משאב יעד ל-Meet

משאב היעד פורמט מגבלות (אם רלוונטי)
מרחב לפגישות //meet.googleapis.com/spaces/SPACE

כאשר SPACE הוא המזהה ב שם המשאב של המשאב spaces ב-Meet API בארכיטקטורת REST. פרטים נוספים מופיעים במאמר איך Meet מזהה מרחב פגישה.
משתמש //cloudidentity.googleapis.com/users/USER

כאשר USER הוא המזהה בשדה signedinUser.user של המשאב participants ב-Meet API בארכיטקטורת REST. למידע נוסף, קראו את המאמר עבודה עם משתתפים.

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

יצירת מינוי ל-Google Workspace

כדי ליצור מינוי, משתמשים ב-method‏ subscriptions.create של Google Workspace Events API כדי ליצור משאב Subscription. מציינים את השדות הבאים:

  • ‫targetResource: חשבון Google Workspace שזיהיתם בקטע הקודם, בפורמט של שם המשאב המלא שלו.
  • ‫eventTypes: מערך של סוגי אירועים אחד או יותר שרוצים לקבל לגבי המשאב. לדוגמה, אם האפליקציה רק צריכה לדעת על הודעות חדשות שפורסמו במרחב משותף ב-Chat, היא יכולה להירשם רק לאירועים שקשורים ליצירת הודעות.
  • ‫notificationEndpoint: נקודת קצה של התראות שאליה המינוי ל-Google Workspace שולח אירועים. משתמשים בנושא Pub/Sub שיצרתם בקטע הקודם.
  • ‫payloadOptions: אפשרויות לקביעת כמות נתוני המשאבים שייכללו במטען הייעודי (payload) של האירוע. ההגדרה הזו משפיעה על מועד התפוגה של המינוי. מידע נוסף על נתוני אירועים

כדי ליצור מינוי ל-Google Workspace:

Apps Script

  1. בפרויקט Apps Script, יוצרים קובץ סקריפט חדש בשם createSubscription ומוסיפים את הקוד הבא:

    function createSubscription() {
  // The Google Workspace resource to monitor for events.
  const targetResource = 'TARGET_RESOURCE';

  // The types of events to receive.
  const eventTypes = [EVENT_TYPES];

  // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  const pubsubTopic = 'TOPIC_NAME';

  // Whether to include resource data or not.
  const resourceData = RESOURCE_DATA;

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.create({
    targetResource: targetResource,
    eventTypes: eventTypes,
    notificationEndpoint: {
      pubsubTopic: pubsubTopic,
    },
    payloadOptions: {
      includeResource: resourceData
    }
  });
  console.log(response);
}

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

    • ‫TARGET_RESOURCE: המשאב ב-Google Workspace שאליו נרשמים, בפורמט של שם המשאב המלא. לדוגמה, כדי להירשם למרחב ב-Chat עם מזהה המרחב AAAABBBB, משתמשים ב-//chat.googleapis.com/spaces/AAAABBBB.
    • ‫EVENT_TYPES: סוג אירוע אחד או יותר שרוצים להירשם אליו במשאב היעד. הפורמט צריך להיות מערך של מחרוזות, כמו 'google.workspace.chat.message.v1.created'.
    • ‫TOPIC_NAME: השם המלא של נושא Pub/Sub שיצרתם בפרויקט בענן. בפורמט projects/PROJECT_ID/topics/TOPIC_ID.

    • ‫RESOURCE_DATA: ערך בוליאני שמציין אם המינוי כולל נתוני משאבים במטען הייעודי (payload):

      • ‫True: כולל את כל נתוני המשאבים. כדי להגביל את השדות שייכללו, מוסיפים את השדה fieldMask ומציינים לפחות שדה אחד למשאב שהשתנה. רק מינויים למשאבים ב-Chat תומכים בהכללת נתוני משאבים.
      • ‫False: לא כולל נתוני משאבים.

  2. כדי ליצור את המינוי ל-Google Workspace, מריצים את הפונקציה createSubscription בפרויקט Apps Script.

Python

  1. בספריית העבודה, יוצרים קובץ בשם create_subscription.py ומוסיפים את הקוד הבא:

    """Create subscription."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [SCOPES]

# Authenticate with Google Workspace and get user authentication.
flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
CREDENTIALS = flow.run_local_server()

# The Google Workspace resource to monitor for events.
TARGET_RESOURCE = 'TARGET_RESOURCE'

# The types of events to receive.
EVENT_TYPES = [EVENT_TYPES]

# The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API using the service endpoint.
service = build(
    'workspaceevents',
    'v1',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}
response = service.subscriptions().create(body=BODY).execute()
print(response)

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

    • ‫SCOPES: היקף הרשאות אחד או יותר של OAuth שתומך בכל סוג אירוע במינוי. בפורמט של מערך מחרוזות. כדי לציין כמה היקפים, צריך להפריד ביניהם באמצעות פסיקים. לדוגמה, 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
    • ‫TARGET_RESOURCE: המשאב ב-Google Workspace שאליו נרשמים, בפורמט של שם המשאב המלא. לדוגמה, כדי להירשם למרחב ב-Chat עם מזהה המרחב AAAABBBB, משתמשים ב-//chat.googleapis.com/spaces/AAAABBBB.
    • ‫EVENT_TYPES: סוג אירוע אחד או יותר שרוצים להירשם אליו במשאב היעד. הפורמט צריך להיות מערך של מחרוזות, כמו 'google.workspace.chat.message.v1.created'.
    • ‫TOPIC_NAME: השם המלא של נושא Pub/Sub שיצרתם בפרויקט בענן. בפורמט projects/PROJECT_ID/topics/TOPIC_ID.

    • ‫RESOURCE_DATA: ערך בוליאני שמציין אם המינוי כולל נתוני משאבים במטען הייעודי (payload):

      • ‫True: כולל את כל נתוני המשאבים. כדי להגביל את השדות שייכללו, מוסיפים את השדה fieldMask ומציינים לפחות שדה אחד למשאב שהשתנה. רק מינויים למשאבים ב-Chat תומכים בהכללת נתוני משאבים.
      • ‫False: לא כולל נתוני משאבים.

  2. כדי ליצור את המינוי ל-Google Workspace, מריצים את הפקודה הבאה בטרמינל:

    python3 create_subscription.py

‫Google Workspace Events API מחזיר פעולה ארוכת-טווח שהושלמה, שמכילה את המופע של המשאב Subscription שיצרתם.

בדיקת המינוי ל-Google Workspace

כדי לבדוק אם אתם מקבלים אירועים מ-Google Workspace, אתם יכולים להפעיל אירוע ולשלוף הודעות למינוי ל-Pub/Sub.

כדי לבדוק את המינוי ל-Google Workspace:

Google API Console

  1. מפעילים סוג אחד או יותר של אירועים במשאב היעד של המינוי ל-Google Workspace. לדוגמה, אם נרשמתם להודעות חדשות במרחב ב-Chat, פרסמו הודעה במרחב.

  2. ב-Google API Console, נכנסים לדף Pub/Sub:

    כניסה ל-Pub/Sub

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

  3. בתפריט Pub/Sub, לוחצים על Subscriptions.

  4. בטבלה, מאתרים את המינוי ל-Pub/Sub של הנושא ולוחצים על שם המינוי.

  5. לוחצים על הכרטיסייה הודעות.

  6. לוחצים על Pull. יכול להיות שיעברו כמה דקות עד שאירוע ייצור הודעת Pub/Sub.

gcloud

  1. מפעילים סוג אחד או יותר של אירועים במשאב היעד של המינוי ל-Google Workspace. לדוגמה, אם נרשמתם להודעות חדשות במרחב ב-Chat, פרסמו הודעה במרחב.

  2. מריצים את הפקודה הבאה:

    gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

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

    • ‫PUBSUB_SUBSCRIPTION_NAME: השם המלא של המינוי ל-Pub/Sub, בפורמט projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID.
    • ‫MESSAGE_COUNT: המספר המקסימלי של הודעות Pub/Sub שרוצים לשלוף.

    יכול להיות שיחלפו כמה דקות עד שאירוע ייצור הודעת Pub/Sub.

לכל אירוע ב-Google Workspace שהפעלתם, נשלחת הודעה למינוי שלכם ב-Pub/Sub שמכילה את האירוע. למידע נוסף, קראו את המאמר קבלת אירועים כהודעות Google Cloud Pub/Sub.

הגדרת האופן שבו האפליקציה מקבלת אירועים

המינוי ל-Pub/Sub שיצרתם מבוסס על שליפה. אחרי שבדקתם את המינוי ל-Pub/Sub, אתם יכולים לעדכן את סוג המסירה כדי לשנות את האופן שבו האפליקציה מקבלת אירועים. לדוגמה, אתם יכולים להגדיר את המינוי ל-Pub/Sub לסוג של מסירת דחיפה, כדי שהאפליקציה תוכל לקבל אירועים ישירות לנקודת קצה של האפליקציה.

מידע נוסף על הגדרת מינוי ל-Pub/Sub זמין במסמכי התיעוד של Pub/Sub.

איך נרשמים לאירועים במרחבים משותפים ב-Google Chat באמצעות אפליקציה ל-Chat

אתם יכולים להירשם לאירועים ב-Chat כאפליקציה ל-Chat ממרחב שבו האפליקציה ל-Chat חברה. אפליקציות צ'אט לא יכולות להירשם לאירועים של משתמשים.

כתיבת סקריפט שקורא ל-Google Workspace Events API

כך יוצרים מינוי לאירועים במרחב משותף ב-Chat באמצעות אימות אפליקציה ואישור אדמין:

  1. אם צריך, מפתחים אפליקציה ל-Chat.

  2. להירשם למשאב ב-Chat, אבל:

    1. במקום אימות משתמש, בצעו אימות כאפליקציה ל-Chat עם אישור חד-פעמי של אדמין.

    2. מציינים את היקפי ההרשאות שמאפשרים לאפליקציית Chat להירשם לאירועים ב-Chat. היקפי ההרשאות האלה תמיד מתחילים ב-chat.app, וכוללים את ההיקפים הבאים:

      • https://www.googleapis.com/auth/chat.app.memberships: הרשמה לאירועים של חברים במרחב משותף ב-Chat.
      • https://www.googleapis.com/auth/chat.app.memberships.readonly: הרשמה לאירועים של חברים במרחב משותף ב-Chat.
      • ‫https://www.googleapis.com/auth/chat.app.messages.readonly: הרשמה לאירועים של הודעות ותגובות במרחב משותף ב-Chat.
      • ‫https://www.googleapis.com/auth/chat.app.spaces: הרשמה לאירועים במרחב משותף ב-Chat.
      • https://www.googleapis.com/auth/chat.app.spaces.readonly: הרשמה לאירועים במרחבים משותפים ב-Chat.

דוגמת הקוד הבאה מציגה הרשמה לאירועי הודעות במרחב משותף ספציפי ב-Chat:

Python 

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  TOPIC = 'TOPIC_NAME'

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1',
      credentials=CREDENTIALS,
  )

  BODY = {
      'target_resource': TARGET_RESOURCE,
      'event_types': EVENT_TYPES,
      'notification_endpoint': {'pubsub_topic': TOPIC},
      'payload_options': {'include_resource': RESOURCE_DATA},
  }
  response = service.subscriptions().create(body=BODY).execute()
  print(response)

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

  • SPACE_ID: שם המרחב המשותף, שאפשר לקבל באמצעות ה-method‏ spaces.list ב-Chat API או מכתובת ה-URL של המרחב המשותף.
  • ‫TOPIC_NAME: השם המלא של נושא Pub/Sub שיצרתם בפרויקט בענן. בפורמט projects/PROJECT_ID/topics/TOPIC_ID.

  • ‫RESOURCE_DATA: ערך בוליאני שמציין אם המינוי כולל נתוני משאבים במטען הייעודי (payload):

    • ‫True: כולל את כל נתוני המשאבים. כדי להגביל את השדות שייכללו, מוסיפים את השדה fieldMask ומציינים לפחות שדה אחד למשאב שהשתנה. רק מינויים למשאבים ב-Chat תומכים בהכללת נתוני משאבים.
    • ‫False: לא כולל נתוני משאבים.

הרשמה לכל האירועים ב-Chat בארגון ב-Google Workspace כאפליקציה ל-Google Chat

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

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

דרישות ומגבלות

  • אימות: אימות כאפליקציה ל-Chat עם אישור חד-פעמי של אדמין
  • SKU: לארגון ב-Google Workspace צריך להיות לפחות רישיון אחד למק"ט של Enterprise. חשוב לדעת שהדרישה הזו לא נאכפת באופן מחמיר בשלב של תוכנית התצוגה המקדימה למפתחים, אבל היא תיאכף בעתיד (הודעה על כך תימסר בנפרד).
  • ייחודיות: אפליקציה ל-Chat יכולה ליצור רק מינוי אחד ללקוח בארגון נתון ב-Google Workspace. לארגון ב-Google Workspace יכולים להיות עד חמישה מינויים של לקוחות בסך הכול (שנוצרו על ידי אפליקציות שונות ל-Chat).
  • היקפי הרשאות: נדרש אחד או יותר מהיקפי ההרשאות הבאים, בהתאם לסוגי האירועים שרוצים לקבל:
    • ‫https://www.googleapis.com/auth/chat.app.all.spaces.readonly: כדי לקבל אירועים לגבי מרחבים משותפים.
    • ‫https://www.googleapis.com/auth/chat.app.all.memberships.readonly: כדי לקבל אירועים לגבי חברויות.
    • ‫https://www.googleapis.com/auth/chat.app.all.messages.readonly: כדי לקבל אירועים שקשורים להודעות ולתגובות.
    • https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly ( תצוגה מקדימה למפתחים): לקבלת אירועים בנוגע למצבי קריאה של משתמשים.

יצירת מינוי ללקוח

כדי ליצור מינוי של לקוח, צריך להפעיל את ה-method‏ subscriptions.create.

דוגמת הקוד הבאה ב-Python יוצרת מינוי של לקוח:

Python 

"""Create a customer subscription."""

from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
# Replace with the scopes needed for the event types you want to receive.
SCOPES = ['https://www.googleapis.com/auth/chat.app.all.messages.readonly']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Monitor all events for the Google Workspace organization.
TARGET_RESOURCE = '//admin.googleapis.com/customers/CUSTOMER_ID'

# The types of events to receive.
EVENT_TYPES = [
    'google.workspace.chat.message.v1.created',
    'google.workspace.chat.message.v1.updated',
    'google.workspace.chat.message.v1.deleted',
]

# The endpoint to deliver events to.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API.
# Note: Use the v1beta endpoint for Developer Preview features.
service = build(
    'workspaceevents',
    'v1beta',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}

response = service.subscriptions().create(body=BODY).execute()
print(response)

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

  • ‫CUSTOMER_ID: מספר הלקוח. אפשר גם להשתמש בכינוי my_customer לארגון ב-Google Workspace של האפליקציה ל-Chat.
  • ‫TOPIC_NAME: השם המלא של נושא Pub/Sub שיצרתם בפרויקט בענן. בפורמט projects/PROJECT_ID/topics/TOPIC_ID.
  • ‫RESOURCE_DATA: ערך בוליאני שמציין אם המינוי כולל נתוני משאבים במטען הייעודי (payload):
    • ‫True: כולל את כל נתוני המשאבים. כדי להגביל את השדות שייכללו, מוסיפים את השדה fieldMask ומציינים לפחות שדה אחד למשאב שהשתנה. רק מינויים למשאבים ב-Chat תומכים בהכללת נתוני משאבים.
    • ‫False: לא כולל נתוני משאבים.