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

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

• لاستخدام أوامر Google Cloud CLI في هذا الدليل:
  1. ثبِّت Google Cloud CLI.
  2. لـ بدء gcloud CLI، شغِّل الرمز البرمجي التالي:

    gcloud init
    

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

• مشروع "برمجة تطبيقات Google":
  • استخدِم مشروعك على Google Cloud بدلاً من المشروع التلقائي الذي أنشأته برمجة التطبيقات تلقائيًا.
  • بالنسبة إلى أي نطاقات أضفتها لضبط شاشة طلب الموافقة على OAuth، عليك أيضًا إضافة نطاقات إلى ملف appsscript.json في مشروعك على Apps Script. مثلاً:

  "oauthScopes": [
    "https://www.googleapis.com/auth/chat.messages.readonly"
  ]
      

  • فعِّل الخدمة المتقدّمة Google Workspace Events.

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 في مشروعك على Cloud و ضبط حقول اسم التطبيق وعنوان URL للصورة الرمزية والوصف. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة إنشاء تطبيق Google Chat.
• تتطلّب مصادقة المستخدم من خلال شاشة طلب الموافقة على OAuth التي تم ضبطها لتطبيقك. عند ضبط شاشة طلب الموافقة، عليك تحديد نطاق لسماح بكل نوع حدث للاشتراك. لضبط شاشة الموافقة وتحديد النطاقات المطلوبة، يُرجى الاطّلاع على اختيار النطاقات.

Google Cloud Console

في وحدة تحكّم Google Cloud، افتح مشروع Google Cloud لتطبيقك وفعِّل واجهتَي برمجة التطبيقات Google Workspace Events API وPub/Sub API:

تفعيل واجهات برمجة التطبيقات

gcloud

1. في دليل العمل، سجِّل الدخول إلى حسابك على Google:

   gcloud auth login

2. اضبط مشروعك على مشروع Cloud لتطبيقك:

   gcloud config set project PROJECT_ID

   استبدِل PROJECT_ID ب معرّف المشروع لمشروع Cloud الخاص بتطبيقك.

3. فعِّل Google Workspace Events API وGoogle Cloud Pub/Sub API:

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

Google Cloud Console

1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Pub/Sub:

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

   تأكَّد من اختيار مشروع Cloud لتطبيقك.

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. بالنسبة إلى أحداث 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: اسم الموضوع الذي أنشأته في الخطوة السابقة.

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

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

     • True: يتضمّن جميع بيانات الموارد. لتقييد الحقول التي يتم تضمينها، أضِف حقل fieldMask وحدِّد حقلًا واحدًا على الأقل للمورد الذي تم تغييره. لا تتيح سوى اشتراكات موارد Chat تضمين data الموارد.
     • 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('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: قيمة منطقية تحدّد ما إذا كان الاشتراك يحتوي على بيانات المورد في الحمولة:

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

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

   python3 create_subscription.py

Google Cloud Console

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

2. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Pub/Sub:

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

   تأكَّد من اختيار مشروع Cloud لتطبيقك.

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

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/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID.
   • ‫MESSAGE_COUNT: الحد الأقصى لعدد رسائل Pub/Sub التي تريد استرجاعها

   قد يستغرق إنشاء حدث رسالة Pub/Sub بضع دقائق.