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

Apps Script

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

    gcloud init
    

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

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

  • מפעילים את השירות המתקדם Google Workspace Events.

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

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. כדי לאתחל את gcloud CLI, מריצים את הקוד הבא:

    gcloud init
    

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

מסוף 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

Google API Console

1. ב-Google API Console, עוברים לדף Pub/Sub:

   מעבר אל Google Cloud Pub/Sub

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

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. בדף של הנושא, עוברים לחלונית הצדדית ופותחים את הכרטיסייה הרשאות.
   2. לוחצים על Add Principal (הוספת גורם ראשי).
   3. בשדה Add principals, מוסיפים את חשבון השירות של אפליקציית Google Workspace שמעבירה אירועים למינוי שלכם:
      1. לאירועים ב-Chat:
         • אם אפליקציית Chat היא תוסף ל-Google Workspace שמרחיב את Chat, צריך להשתמש באימייל של חשבון השירות בדף ההגדרה של Chat API. מידע נוסף זמין במאמר יצירת אפליקציה ל-Google Chat שמשתמשת ב-Pub/Sub.
         • אם אפליקציית Chat שלכם משתמשת באירועי אינטראקציה של Chat API, צריך להשתמש ב-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. בתפריט הקצאת תפקידים, בוחרים באפשרות 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 שצריכה להעביר אירועים למינוי שלכם:

     • כדי לקבל אירועים מ-Chat, צריך להשתמש באחד מחשבונות השירות הבאים:
       • אם אפליקציית Chat היא תוסף ל-Google Workspace שמרחיב את Chat, צריך להשתמש באימייל של חשבון השירות בדף ההגדרה של Chat API. מידע נוסף זמין במאמר איך יוצרים אפליקציה ל-Google Chat שמשתמשת ב-Pub/Sub.
       • אם אפליקציית Chat שלכם משתמשת באירועי אינטראקציה של Chat API, צריך להשתמש ב-chat-api-push@system.gserviceaccount.com.
     • תצוגה מקדימה למפתחים: כדי לקבל אירועים מ-Drive, צריך להשתמש ב-drive-api-event-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 שאליו נרשמתם, בפורמט של שם המשאב המלא. לדוגמה, כדי להירשם למרחב ב-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 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.

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',
      '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)