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

מסוף 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 במזהה הפרויקט של פרויקט הענן של האפליקציה.

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

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

מסוף Google Cloud

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

   מעבר אל 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. בדף של הנושא, עוברים לחלונית הצדדית ופותחים את הכרטיסייה הרשאות.
   2. לוחצים על Add Principal (הוספת גורם ראשי).
   3. בשדה Add principals, מוסיפים את חשבון השירות של אפליקציית Google Workspace שמעבירה אירועים למינוי שלכם:
      1. לאירועים ב-Chat, chat-api-push@system.gserviceaccount.com.
      2. גרסת Developer Preview:: לאירועים ב-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-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 שאליו נרשמתם, בפורמט של שם המשאב המלא. לדוגמה, כדי להירשם למרחב ב-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('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 שאליו נרשמתם, בפורמט של שם המשאב המלא. לדוגמה, כדי להירשם למרחב ב-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. במסוף Google Cloud, נכנסים לדף Pub/Sub:

   מעבר אל 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/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,
      discoveryServiceUrl='https://workspaceevents.googleapis.com/$discovery/rest?version=v1beta&labels=DEVELOPER_PREVIEW&key=API_KEY',
  )

  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)