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

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

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

    gcloud init
    

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

    gcloud init
    

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

Google Cloud Console

في Google Cloud Console، افتح مشروع 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 (التي تم إنشاؤها كإضافات في Google Workspace وتوسّع نطاق Chat)، استخدِم عنوان البريد الإلكتروني لحساب الخدمة في صفحة إعدادات Chat API. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat يستخدم Pub/Sub.
         • بالنسبة إلى تطبيقات Chat التي ليست إضافات Google Workspace، استخدِم chat-api-push@system.gserviceaccount.com. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat يستخدم Pub/Sub.
      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)