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

Apps Script

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

    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 בפרויקט בענן ולהגדיר את השדות App name,‏ Avatar URL ו-Description. פרטים נוספים זמינים במאמר פיתוח אפליקציה ל-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. כדי לאתחל את ה-CLI של gcloud, מריצים את הקוד הבא:

    gcloud init
    

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

מסוף 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. בדף של הנושא, עוברים לחלונית הצדדית ופותחים את הכרטיסייה 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. בתפריט הקצאת תפקידים, בוחרים באפשרות 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-api-push@system.gserviceaccount.com. איך יוצרים אפליקציה ל-Google Chat שמשתמשת ב-Pub/Sub
     • כדי לקבל אירועים מ-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',
      '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)

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)