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

توضّح هذه الصفحة كيفية استخدام Google Workspace Events API لإنشاء اشتراك في أحد موارد Google Workspace. يتيح اشتراك Google Workspace لتطبيقك تلقّي معلومات حول أحداث Google Workspace، والتي تمثّل تغييرات في أحد موارد Google Workspace. للتعرّف على الموارد وأنواع الأحداث التي تتيحها "واجهة برمجة تطبيقات أحداث Google Workspace"، راجِع نظرة عامة على "واجهة برمجة تطبيقات أحداث Google Workspace".

تتضمّن هذه الصفحة الخطوات التالية لإنشاء اشتراك في Google Workspace:

  1. إعداد البيئة
  2. إنشاء موضوع Google Cloud Pub/Sub والاشتراك فيه يمكنك استخدام هذا الموضوع كنقطة نهاية لتلقّي أحداث Google Workspace.
  3. استدعِ طريقة create في Google Workspace Events API على المورد Subscription.
  4. اختبِر اشتراكك في Google Workspace للتأكّد من أنّ موضوع Pub/Sub يتلقّى الأحداث التي اشتركت فيها.
  5. يمكنك اختياريًا ضبط طريقة إرسال الأحداث إلى نقطة نهاية لتطبيقك، حتى يتمكّن تطبيقك من معالجة الحدث واتخاذ إجراء إذا لزم الأمر.

المتطلبات الأساسية

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

  • لاستخدام أوامر Google Cloud CLI الواردة في هذا الدليل، اتّبِع الخطوات التالية:
    1. ثبِّت Google Cloud CLI.
    2. لإعداد gcloud CLI، شغِّل الرمز التالي:
      3.   gcloud init
  • مشروع Google Cloud مع تفعيل الفوترة للاشتراك في Chat، يجب أيضًا تفعيل Chat API في مشروعك على Cloud وتعبئة حقول اسم التطبيق وعنوان URL للصورة الرمزية والوصف. لمزيد من التفاصيل، يُرجى الاطّلاع على المقالة إنشاء تطبيق Google Chat.
  • يتطلّب مصادقة المستخدم من خلال شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التي تم ضبطها للتطبيق. عند ضبط شاشة طلب الموافقة، عليك تحديد نطاق لتوفير كل نوع من أنواع الأحداث للاشتراك. لضبط شاشة الموافقة وتحديد النطاقات المطلوبة، يُرجى الاطّلاع على اختيار النطاقات.
  • مشروع "برمجة تطبيقات Google":
    • استخدِم مشروعك على Google Cloud بدلاً من المشروع التلقائي الذي يتم إنشاؤه تلقائيًا بواسطة Apps Script.
    • بالنسبة إلى أي نطاقات أضفتها لضبط شاشة موافقة OAuth، عليك أيضًا إضافة النطاقات إلى ملف appsscript.json في مشروع "برمجة تطبيقات Google". على سبيل المثال: 
      • "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، شغِّل الرمز التالي:
      3.   gcloud init
  • مشروع Google Cloud مع تفعيل الفوترة للاشتراك في Chat، يجب أيضًا تفعيل Chat API في مشروعك على Cloud وتعبئة حقول اسم التطبيق وعنوان URL للصورة الرمزية والوصف. لمزيد من التفاصيل، يُرجى الاطّلاع على المقالة إنشاء تطبيق Google Chat.
  • يتطلّب مصادقة المستخدم من خلال شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التي تم ضبطها للتطبيق. عند ضبط شاشة طلب الموافقة، عليك تحديد نطاق لتوفير كل نوع من أنواع الأحداث للاشتراك. لضبط شاشة الموافقة وتحديد النطاقات المطلوبة، يُرجى الاطّلاع على اختيار النطاقات.

إعداد البيئة

يوضّح القسم التالي كيفية إعداد بيئتك قبل إنشاء اشتراك في Google Workspace.

تفعيل واجهة Google Workspace Events API وواجهة Google Cloud Pub/Sub API

قبل استخدام واجهات Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

Google Cloud Console

في Google Cloud Console، افتح مشروع 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

إنشاء بيانات اعتماد معرّف عميل OAuth

اختَر نوع التطبيق للحصول على تعليمات محدّدة حول كيفية إنشاء معرّف عميل OAuth:

تطبيق الويب

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > تطبيق الويب.
  4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
  5. أضِف معرّفات الموارد المنتظمة (URI) المعتمَدة ذات الصلة بتطبيقك:
    • التطبيقات من جهة العميل (JavaScript): ضمن مصادر JavaScript المسموح بها، انقر على إضافة معرّف الموارد المنتظم (URI). بعد ذلك، أدخِل معرّف URI لاستخدامه في طلبات المتصفّح. يحدّد هذا الحقل النطاقات التي يمكن لتطبيقك إرسال طلبات البيانات من واجهة برمجة التطبيقات إلى خادم OAuth 2.0 منها.
    • التطبيقات من جهة الخادم (Java وPython وغير ذلك): ضمن معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه، انقر على إضافة معرّف URI. بعد ذلك، أدخِل معرّف موارد منتظم (URI) لنقطة نهاية يمكن لخادم OAuth 2.0 إرسال الردود إليها.
  6. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عملاء OAuth 2.0.

    سجِّل معرّف العميل. لا يتم استخدام أسرار العملاء لتطبيقات الويب.

Android

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > Android.
  4. في حقل "الاسم"، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
  5. في حقل "اسم الحزمة"، أدخِل اسم الحزمة من ملف AndroidManifest.xml.
  6. في حقل "الملف المرجعي لشهادة SHA-1"، أدخِل الملف المرجعي لشهادة SHA-1 الذي تم إنشاؤه.
  7. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضِمن "معرّفات عملاء OAuth 2.0".

iOS

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > iOS.
  4. في حقل "الاسم"، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
  5. في حقل "معرّف الحزمة"، أدخِل معرّف الحزمة كما هو مدرَج في ملف Info.plist الخاص بالتطبيق.
  6. اختياري: إذا كان تطبيقك يظهر في Apple App Store، أدخِل رقم تعريف App Store.
  7. اختياري: في حقل "رقم تعريف الفريق"، أدخِل السلسلة الفريدة المكوّنة من 10 أحرف والتي تنشئها Apple وتعيّنها لفريقك.
  8. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضِمن "معرّفات عملاء OAuth 2.0".

تطبيق Chrome

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > إضافة Chrome.
  4. في حقل "الاسم"، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
  5. في حقل "معرّف العنصر"، أدخِل سلسلة المعرّف الفريد المكوّنة من 32 حرفًا لتطبيقك. يمكنك العثور على قيمة رقم التعريف هذا في عنوان URL لتطبيقك في "سوق Chrome الإلكتروني" وفي لوحة بيانات المطوّر في "سوق Chrome الإلكتروني".
  6. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضِمن "معرّفات عملاء OAuth 2.0".

تطبيق لأجهزة الكمبيوتر المكتبي

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > تطبيق على الكمبيوتر.
  4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
  5. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضِمن "معرّفات عملاء OAuth 2.0".

أجهزة التلفزيون والأجهزة التي تتطلّب إدخال بيانات محدودة

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > أجهزة التلفزيون والأجهزة ذات الإدخال المحدود.
  4. في حقل "الاسم"، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
  5. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضِمن "معرّفات عملاء OAuth 2.0".

Universal Windows Platform (منصة Windows العالمية)

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > > العملاء.

    الانتقال إلى "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > نظام التشغيل Windows العالمي (UWP).
  4. في حقل "الاسم"، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
  5. في حقل "معرّف المتجر"، أدخِل قيمة معرّف Microsoft Store الفريد المكوّن من 12 حرفًا لتطبيقك. يمكنك العثور على هذا المعرّف في عنوان URL الخاص بتطبيقك في Microsoft Store وفي Partner Center.
  6. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضِمن "معرّفات عملاء OAuth 2.0".

تنزيل ملف JSON الخاص بسرّ العميل

ملف سر العميل هو تمثيل بتنسيق JSON لبيانات اعتماد معرّف عميل OAuth التي يمكن لتطبيقك الرجوع إليها عند تقديم بيانات الاعتماد.

  1. في Google Cloud Console، انتقِل إلى "القائمة" > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

    الانتقال إلى "بيانات الاعتماد"

  2. ضمن معرّفات العميل لبروتوكول OAuth 2.0، انقر على معرّف العميل الذي أنشأته.

  3. انقر على تنزيل JSON.

  4. احفظ الملف باسم credentials.json.

إنشاء موضوع Pub/Sub والاشتراك فيه

في هذا القسم، يمكنك إنشاء موضوع واشتراك في خدمة Pub/Sub. يعمل موضوع Pub/Sub كنقطة نهاية للإشعارات حيث يتلقّى اشتراكك في Google Workspace الأحداث.

لمزيد من المعلومات حول إنشاء مواضيع Pub/Sub وإدارتها، يُرجى الاطّلاع على مستندات Pub/Sub.

لإنشاء موضوع على Pub/Sub والاشتراك فيه، اتّبِع الخطوات التالية:

Google Cloud Console

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

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

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

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

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

الاشتراك في أحد موارد Google Workspace

في هذا القسم، يمكنك الاشتراك في مرجع Google Workspace الذي تريد تتبُّع الأحداث فيه.

اختيار المرجع المستهدف وتحديده

في اشتراك Google Workspace، يكون المورد المستهدف هو مورد Google Workspace الذي تراقب الأحداث فيه. يتم تمثيل المرجع المستهدف في حقل targetResource الخاص بالاشتراك، ويتم تنسيقه باستخدام اسم المرجع الكامل. على سبيل المثال، بالنسبة إلى اشتراك يتتبّع مساحة في Google Chat (spaces/AAAABBBBBBB)، تكون قيمة targetResource هي //chat.googleapis.com/spaces/AAAABBBBBBB.

قبل إنشاء الاشتراك، استخدِم الأقسام التالية للتعرّف على كيفية تحديد المرجع المستهدف وتنسيقه.

تحديد مصدر مستهدَف لتطبيق Chat

المورد المستهدف التنسيق القيود
مسافة

//chat.googleapis.com/spaces/SPACE

حيث SPACE هو المعرّف في اسم المورد الخاص بمورد space في Chat API. يمكنك الحصول على المعرّف من عنوان URL الخاص بالمساحة أو باستخدام طريقة spaces.list().

 يجب أن يكون مستخدم Chat الذي يمنح الإذن بالاشتراك عضوًا في المساحة من خلال حسابه على Google Workspace أو Google.
جميع المساحات الخاصة بمستخدم

//chat.googleapis.com/spaces/-

 لا يتلقّى الاشتراك سوى أحداث المساحات التي يكون المستخدم عضوًا فيها من خلال حسابه على Google Workspace أو حسابه على Google.
المستخدم

//cloudidentity.googleapis.com/users/USER

حيث USER هو المعرّف في اسم المورد الخاص بمورد user في Chat API. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة تحديد مستخدمي Google Chat وتحديدهم.

لا يتلقّى الاشتراك سوى الأحداث المتعلّقة بالمستخدم الذي منح الإذن بالاشتراك. لا يمكن للمستخدم منح إذن بالاشتراك نيابةً عن مستخدمين آخرين.

تحديد مرجع مستهدَف في Drive

المورد المستهدف التنسيق القيود (إذا كان ذلك منطبقًا)
ملف //googleapis.com/drive/v3/files/FILE

حيث FILE هو رقم التعريف في اسم المورد الخاص بمورد files في Drive API. يمكنك الحصول على المعرّف من عنوان URL للملف أو باستخدام طريقة files.list.

 يجب أن يكون لدى المستخدم الذي يمنح الإذن بالاشتراك إذن بالوصول إلى الملف ضمن الاشتراك بالنسبة إلى حدث الاشتراك.
مساحة تخزين سحابي مشتركة //googleapis.com/drive/v3/drives/DRIVE

حيث DRIVE هو رقم التعريف في اسم المورد الخاص بمورد drives في Drive API. يمكنك الحصول على المعرّف من عنوان URL الخاص بمحرك الأقراص أو باستخدام طريقة drives.list.

 لا يتلقّى الاشتراك سوى أحداث العناصر في مساحة التخزين السحابي المشتركة التي يكون المستخدم عضوًا فيها من خلال حسابه على Google Workspace أو حسابه على Google.

تحديد مصدر مستهدف لـ Meet

المورد المستهدف التنسيق القيود (إذا كان ذلك منطبقًا)
مساحة الاجتماع //meet.googleapis.com/spaces/SPACE

حيث SPACE هو المعرّف في اسم المورد الخاص بمورد space في واجهة برمجة تطبيقات Meet REST. لمزيد من التفاصيل، يُرجى الاطّلاع على كيفية تحديد Meet لمساحة اجتماع.
المستخدم //cloudidentity.googleapis.com/users/USER

حيث USER هو المعرّف في حقل signedinUser.user الخاص بمورد participant في واجهة برمجة تطبيقات Meet REST. لمزيد من التفاصيل، يُرجى الاطّلاع على التعاون مع المشاركين.

يتلقّى الاشتراك أحداثًا حول مساحات الاجتماعات التي يكون فيها المستخدم أحد ما يلي:

  • مالك مساحة الاجتماعات
  • مشارك في مساحة الاجتماع
  • منظّم حدث "تقويم Google" المرتبط بمساحة الاجتماع

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

لإنشاء اشتراك، يمكنك استخدام طريقة subscriptions.create في Google Workspace Events API لإنشاء مورد Subscription. حدِّد الحقول التالية:

  • targetResource: هو حساب Google Workspace تم تحديده في القسم السابق، وتمت تهيئته باستخدام الاسم الكامل للمورد.
  • eventTypes: مصفوفة من نوع حدث واحد أو أكثر تريد تلقّيه بشأن المورد. على سبيل المثال، إذا كان تطبيقك يحتاج فقط إلى معرفة الرسائل الجديدة المنشورة في مساحة Chat، يمكن لتطبيقك الاشتراك في الأحداث المتعلقة بالرسائل التي تم إنشاؤها.
  • notificationEndpoint: نقطة نهاية للإشعارات يتلقّى فيها اشتراكك في Google Workspace الأحداث. استخدِم موضوع Pub/Sub الذي أنشأته في القسم السابق.
  • ‫payloadOptions: خيارات لتحديد مقدار بيانات الموارد التي سيتم تضمينها في حمولة الحدث. يؤثر هذا الضبط في وقت انتهاء صلاحية اشتراكك. لمزيد من المعلومات، اطّلِع على بيانات الأحداث.

لإنشاء اشتراك في Google Workspace، اتّبِع الخطوات التالية:

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

  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 الذي تشترك فيه، بتنسيق اسم المرجع الكامل. على سبيل المثال، للاشتراك في مساحة Google 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 الذي تشترك فيه، بتنسيق اسم المرجع الكامل. على سبيل المثال، للاشتراك في مساحة Google 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 Workspace Events API عملية طويلة الأمد مكتملة تحتوي على مثيل لمورد Subscription الذي أنشأته.

اختبار اشتراكك في Google Workspace

لاختبار تلقّي أحداث Google Workspace، يمكنك بدء حدث واسترداد الرسائل إلى اشتراك Pub/Sub.

لاختبار اشتراكك في Google Workspace، اتّبِع الخطوات التالية:

Google Cloud Console

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

  2. في Google Cloud Console، انتقِل إلى صفحة 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/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
    • استبدِل MESSAGE_COUNT بالحدّ الأقصى لعدد رسائل Pub/Sub التي تريد سحبها.

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

لكل حدث تم تشغيله في Google Workspace، يتم تسليم رسالة إلى اشتراكك في Pub/Sub تتضمّن الحدث. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة تلقّي الأحداث كرسائل Google Cloud Pub/Sub.

ضبط طريقة تلقّي تطبيقك للأحداث

الاشتراك في Pub/Sub الذي أنشأته يستند إلى عملية السحب. بعد اختبار اشتراكك في Pub/Sub، يمكنك تعديل نوع التسليم لتغيير طريقة تلقّي تطبيقك للأحداث. على سبيل المثال، يمكنك ضبط اشتراك Pub/Sub على نوع تسليم بالدفع، كي يتمكّن تطبيقك من تلقّي الأحداث مباشرةً إلى نقطة نهاية التطبيق.

لمعرفة المزيد حول إعداد اشتراك في Pub/Sub، يمكنك الاطّلاع على مستندات Pub/Sub.