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

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

דף זה כולל את השלבים הבאים ליצירת מינוי ל-Google Workspace:

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

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

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 Meet, זהו מרחב משותף שבו המשתמש המאומת הוא הבעלים. במאמר עבודה עם מרחבים משותפים במסמכי התיעוד של Google Meet מוסבר איך יוצרים מרחב משותף.
    • כדי להירשם למשתמש Google Meet, יש צורך במזהה user של Cloud Identity API.
  • פרויקט ב-Google Cloud שהחיוב בו מופעל.

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

הגדרת הסביבה

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

הפעלה של Google Workspace Event API ו-Google Cloud Pub/Sub API

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

מסוף Google Cloud

במסוף Google Cloud, פותחים את הפרויקט ב-Google Cloud של האפליקציה ומפעילים את Google Workspace Event 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 Event API ואת Google Cloud Pub/Sub API:

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

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

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

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

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

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

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

  7. לוחצים על אישור. פרטי הכניסה החדשים שנוצרו מופיעים בקטע מזהי לקוח ב-OAuth 2.0.

Android

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

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

iOS

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

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

אפליקציית Chrome

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
  3. לחץ על סוג האפליקציה > אפליקציית Chrome.
  4. בשדה 'שם', מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה 'מזהה אפליקציה', מזינים את מחרוזת המזהה הייחודית של האפליקציה, באורך 32 תווים. ערך המזהה מופיע בכתובת ה-URL של האפליקציה בחנות האינטרנט של Chrome ובמרכז השליטה למפתחים של חנות האינטרנט של Chrome.
  6. לוחצים על יצירה. מופיע המסך של לקוח OAuth שנוצר, ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  7. לוחצים על אישור. פרטי הכניסה החדשים שנוצרו מופיעים בקטע 'מזהי לקוח ב-OAuth 2.0'.

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

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
  3. לוחצים על סוג האפליקציה > אפליקציה למחשב.
  4. בשדה שם, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. לוחצים על יצירה. מופיע המסך של לקוח OAuth שנוצר, ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  6. לוחצים על אישור. פרטי הכניסה החדשים שנוצרו מופיעים בקטע מזהי לקוח ב-OAuth 2.0.

טלוויזיות והתקני קלט מוגבלים

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
  3. לוחצים על סוג האפליקציה > טלוויזיות והתקני קלט מוגבלים.
  4. בשדה 'שם', מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. לוחצים על יצירה. מופיע המסך של לקוח OAuth שנוצר, ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  6. לוחצים על אישור. פרטי הכניסה החדשים שנוצרו מופיעים בקטע 'מזהי לקוח ב-OAuth 2.0'.

Universal Windows Platform (UWP)‎

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
  3. לוחצים על סוג האפליקציה > Universal Windows Platform (UWP).
  4. בשדה 'שם', מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. בשדה 'מזהה חנות', מזינים את ערך מזהה Microsoft Store הייחודי של האפליקציה שלכם, בן 12 התווים. המזהה הזה נמצא בכתובת ה-URL של האפליקציה ב-Microsoft Store ובמרכז השותפים.
  6. לוחצים על יצירה. מופיע המסך של לקוח OAuth שנוצר, ומוצגים בו מזהה הלקוח וסוד הלקוח החדשים.
  7. לוחצים על אישור. פרטי הכניסה החדשים שנוצרו מופיעים בקטע 'מזהי לקוח ב-OAuth 2.0'.

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

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

  1. במסוף Google Cloud, נכנסים לתפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

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

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

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

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

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

למידע נוסף על יצירה וניהול של נושאי Pub/Sub, ראו את מסמכי התיעוד של Pub/Sub.

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

מסוף Google Cloud

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

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

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

  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. לחץ על הוסף חשבון משתמש.
    3. בשדה Add principals, מוסיפים את חשבון השירות של אפליקציית Google Workspace שמספקת אירועים למינוי:
      1. לאירועים ב-Chat, chat-api-push@system.gserviceaccount.com.
      2. לאירועים ב-Meet, meet-api-event-push@system.gserviceaccount.com.
    4. בתפריט הקצאת תפקידים בוחרים באפשרות 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: שם הנושא שיצרתם בשלב הקודם.

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

בקטע הזה נשתמש בשיטה subscriptions.create() של Google Workspace Event API כדי ליצור משאב של Subscription. עליכם לציין את השדות הבאים:

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

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

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 Workspace Event API מחזיר פעולה ממושכת שהושלמה שמכילה את המופע של המשאב Subscription שיצרתם.

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

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

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

מסוף Google Cloud

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

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

    נכנסים אל Pub/Sub

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

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

  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 תיווצר על ידי האירוע.

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

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

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

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