إنشاء اشتراك Google Workspace

برمجة التطبيقات

• لاستخدام أوامر Google Cloud CLI في هذا الدليل:
  1. ثبِّت Google Cloud CLI.
  2. لإعداد واجهة سطر الأوامر في gcloud، نفِّذ الرمز التالي:

    gcloud init
    

• مشروع "برمجة تطبيقات Google":
  • استخدِم مشروعك على السحابة الإلكترونية على Google Cloud بدلاً من المشروع التلقائي الذي يتم إنشاؤه تلقائيًا من خلال "برمجة تطبيقات Google".
  • بالنسبة إلى جميع النطاقات التي أضفتها لضبط شاشة طلب الموافقة عبر OAuth، يجب أيضًا إضافة النطاقات إلى ملف appsscript.json في مشروع "برمجة تطبيقات Google". على سبيل المثال، إذا حدّدت نطاق 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

• الإصدار 3.6 من Python أو إصدار أحدث
• أداة إدارة حزم pip
• أحدث مكتبات برامج Google للغة Python لتثبيتها أو تحديثها، شغِّل الأمر التالي في واجهة سطر الأوامر:

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
    

• لاستخدام أوامر Google Cloud CLI في هذا الدليل:
  1. ثبِّت Google Cloud CLI.
  2. لإعداد واجهة سطر الأوامر في gcloud، نفِّذ الرمز التالي:

    gcloud init
    

• مشروع على Google Cloud مع تفعيل الفوترة بالنسبة إلى الاشتراكات في Chat، يجب أيضًا تفعيل Chat API في مشروعك على السحابة الإلكترونية وضبط حقول اسم التطبيق وعنوان URL للصورة الرمزية والوصف. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat.
• يتطلّب ذلك المصادقة ونطاق تفويض مناسب لكل نوع حدث في الاشتراك:
  • يتطلّب ذلك عادةً مصادقة المستخدم من خلال شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التي تم ضبطها للتطبيق. عند ضبط شاشة طلب الموافقة، يجب تحديد نطاق لإتاحة كل نوع حدث للاشتراك. لضبط شاشة طلب الموافقة وتحديد النطاقات المطلوبة، يُرجى الاطّلاع على مقالة اختيار النطاقات.
  • للاشتراك في حدث Chat كتطبيق Chat، يجب إجراء مصادقة التطبيق بموافقة المشرف لمرة واحدة.

Google Cloud Console

في وحدة تحكّم Google Cloud، افتح مشروع Google Cloud لتطبيقك وفعِّل Google Workspace Events API وPub/Sub 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

1. في Google API Console، انتقِل إلى صفحة Pub/Sub:

   الانتقال إلى Google Cloud Pub/Sub

   تأكَّد من اختيار مشروع على السحابة الإلكترونية لتطبيقك.

2. انقر على add_box إنشاء موضوع واتّبِع الخطوات التالية:

   1. أدخِل اسمًا لموضوعك، مثل workspace-events-topic.
   2. اترك الخيار إضافة اشتراك تلقائي محدّدًا. يُطلق Pub/Sub على هذا الاشتراك التلقائي اسمًا مشابهًا لاسم موضوعك، مثل workspace-events-topic-sub.
   3. اختياري: يمكنك تعديل أو ضبط سمات إضافية لموضوعك.

3. انقر على إنشاء. يتم تنسيق اسم الموضوع الكامل على النحو التالي: projects/PROJECT_ID/topics/TOPIC_ID. استخدِم هذا الاسم الكامل في خطوة لاحقة.

4. امنح الإذن بنشر رسائل Pub/Sub في موضوعك:

   1. في صفحة الموضوع، انتقِل إلى اللوحة الجانبية وافتح علامة التبويب الأذونات.
   2. انقر على إضافة مستخدم أساسي.
   3. في حقل إضافة مستخدمين رئيسيين، أضِف حساب الخدمة لتطبيق 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 التي ليست إضافات، استخدِم 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: اسم الموضوع الذي أنشأته في الخطوة السابقة

برمجة التطبيقات

1. في مشروع "برمجة تطبيقات Google"، أنشئ ملف نص برمجي جديدًا باسم 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: قيمة منطقية تحدّد ما إذا كان الاشتراك يتضمّن بيانات الموارد في الحمولة:

     • True: يتضمّن جميع بيانات الموارد. لتحديد الحقول التي يتم تضمينها، أضِف الحقل fieldMask وحدِّد حقلًا واحدًا على الأقل للمورد الذي تم تغييره. يمكن فقط للاشتراكات في موارد Chat تضمين بيانات الموارد.
     • False: لا يشمل بيانات الموارد.

2. لإنشاء اشتراك Google Workspace، شغِّل الدالة createSubscription في مشروع "برمجة تطبيقات Google".

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: قيمة منطقية تحدّد ما إذا كان الاشتراك يتضمّن بيانات الموارد في الحمولة:

     • True: يتضمّن جميع بيانات الموارد. لتحديد الحقول التي يتم تضمينها، أضِف الحقل fieldMask وحدِّد حقلًا واحدًا على الأقل للمورد الذي تم تغييره. يمكن فقط للاشتراكات في موارد Chat تضمين بيانات الموارد.
     • False: لا يشمل بيانات الموارد.

2. لإنشاء اشتراك Google Workspace، شغِّل الأمر التالي في وحدة الطرفية:

   python3 create_subscription.py

وحدة تحكّم Google API

1. تفعيل نوع واحد أو أكثر من الأحداث في المورد المستهدَف لاشتراكك في Google Workspace على سبيل المثال، إذا اشتركت في الرسائل الجديدة في مساحة Chat، يمكنك نشر رسالة في المساحة.

2. في Google API Console، انتقِل إلى صفحة Pub/Sub:

   الانتقال إلى Pub/Sub

   تأكَّد من اختيار مشروع على السحابة الإلكترونية لتطبيقك.

3. في قائمة Pub/Sub، انقر على الاشتراكات.

4. في الجدول، ابحث عن اشتراك Pub/Sub لموضوعك وانقر على اسم الاشتراك.

5. انقر على علامة التبويب الرسائل.

6. انقر على سحب. قد يستغرق الحدث بضع دقائق لإنشاء رسالة 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)