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

Apps Script

• כדי להשתמש בפקודות Google Cloud CLI במדריך הזה:
  1. מתקינים את Google Cloud CLI.
  2. כדי להפעיל את ה-CLI של gcloud, מריצים את הקוד הבא:

    gcloud init
    

• פרויקט ב-Google Cloud עם חיוב מופעל. כדי להירשם למינוי ל-Chat, צריך גם להפעיל את Chat API בפרויקט ב-Cloud ולהגדיר את השדות שם האפליקציה, כתובת ה-URL של הדמות ותיאור. פרטים נוספים זמינים במאמר פיתוח אפליקציה ל-Google Chat.
• נדרש אימות משתמש באמצעות מסך ההסכמה של OAuth שהוגדר לאפליקציה. כשמגדירים את מסך ההסכמה, צריך לציין היקף כדי לתמוך בכל סוג אירוע עבור המינוי. במאמר בחירת היקפים מוסבר איך מגדירים את מסך ההסכמה ומזהים את ההיקפים הנדרשים.

• פרויקט Apps Script:
  • משתמשים בפרויקט Google Cloud במקום בפרויקט ברירת המחדל שנוצר באופן אוטומטי על ידי Apps Script.
  • לכל היקפי ההרשאות שהוספתם כדי להגדיר את מסך ההסכמה של OAuth, עליכם להוסיף את ההיקפים גם לקובץ appsscript.json בפרויקט Apps Script. לדוגמה:

  "oauthScopes": [
    "https://www.googleapis.com/auth/chat.messages.readonly"
  ]
      

  • מפעילים את השירות המתקדם 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, מריצים את הקוד הבא:

    gcloud init
    

• פרויקט ב-Google Cloud עם חיוב מופעל. כדי להירשם למינוי ל-Chat, צריך גם להפעיל את Chat API בפרויקט ב-Cloud ולהגדיר את השדות שם האפליקציה, כתובת ה-URL של הדמות ותיאור. פרטים נוספים זמינים במאמר פיתוח אפליקציה ל-Google Chat.
• נדרש אימות משתמש באמצעות מסך ההסכמה של OAuth שהוגדר לאפליקציה. כשמגדירים את מסך ההסכמה, צריך לציין היקף כדי לתמוך בכל סוג אירוע במינוי. במאמר בחירת היקפים מוסבר איך מגדירים את מסך ההסכמה ומזהים את ההיקפים הנדרשים.

מסוף Google Cloud

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

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

gcloud

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

   gcloud auth login

2. מגדירים את הפרויקט כפרויקט Cloud של האפליקציה:

   gcloud config set project PROJECT_ID

   מחליפים את PROJECT_ID במזהה הפרויקט של הפרויקט ב-Cloud של האפליקציה.

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

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

מסוף Google Cloud

1. נכנסים לדף Pub/Sub במסוף Google Cloud:

   כניסה אל Google Cloud Pub/Sub

   מוודאים שבחרתם את הפרויקט ב-Cloud של האפליקציה.

2. לוחצים על add_box 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. באירועים ב-Meet, meet-api-event-push@system.gserviceaccount.com.
   4. בתפריט Assign roles (הקצאת תפקידים), בוחרים באפשרות Pub/Sub Publisher.
   5. לוחצים על שמירה. עדכון ההרשאות לנושא עשוי להימשך כמה דקות.

gcloud

1. כדי ליצור נושא בפרויקט ב-Cloud, מריצים את הפקודה הבאה:

   gcloud pubsub topics create TOPIC_ID

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

   הפלט מציג את שם הנושא המלא, בפורמט projects/PROJECT_ID/topics/TOPIC_ID. שימו לב לשם, וודאו שהערך של PROJECT_ID הוא מזהה הפרויקט ב-Cloud של האפליקציה. שם הנושא ישמש אתכם בשלב הבא, וגם ליצירת המינוי ל-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 שאמורה לשלוח אירועים למינוי שלכם:

     • כדי לקבל אירועים מ-Chat, משתמשים ב-chat-api-push@system.gserviceaccount.com.
     • כדי לקבל אירועים מ-Meet, משתמשים ב-meet-api-event-push@system.gserviceaccount.com.

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

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

    gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

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

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

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 שנרשמתם אליו, בפורמט של שם המשאב המלא. לדוגמה, כדי להירשם למרחב משותף ב-Google Chat עם מזהה המרחב AAAABBBB, צריך להשתמש ב-//chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES: סוג אירוע אחד או יותר שרוצים להירשם אליו במשאב היעד. הפורמט הוא מערך של מחרוזות, כמו 'google.workspace.chat.message.v1.created'.
   • TOPIC_NAME: השם המלא של נושא ה-Pub/Sub שיצרתם בפרויקט ב-Cloud. בפורמט 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('client_secrets.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 שאליו רוצים להירשם, בפורמט של שם המשאב המלא. לדוגמה, כדי להירשם למרחב משותף ב-Google Chat עם מזהה המרחב AAAABBBB, צריך להשתמש ב-//chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES: סוג אירוע אחד או יותר שרוצים להירשם אליהם במשאב היעד. הפורמט הוא מערך של מחרוזות, כמו 'google.workspace.chat.message.v1.created'.
   • TOPIC_NAME: השם המלא של נושא ה-Pub/Sub שיצרתם בפרויקט ב-Cloud. בפורמט projects/PROJECT_ID/topics/TOPIC_ID.

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

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

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

   python3 create_subscription.py

מסוף Google Cloud

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

2. נכנסים לדף Pub/Sub במסוף Google Cloud:

   כניסה לדף Pub/Sub

   מוודאים שבחרתם את הפרויקט ב-Cloud של האפליקציה.

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/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID.
   • MESSAGE_COUNT: המספר המקסימלי של הודעות Pub/Sub שרוצים למשוך.

   יצירת הודעה ב-Pub/Sub עשויה להימשך כמה דקות.