تتبُّع أحداث الاجتماعات باستخدام Python وGoogle Meet REST API

يوضّح هذا الدليل التوجيهي كيفية استخدام واجهة Google Meet REST API مع واجهة Google Workspace Events API وGoogle Cloud Pub/Sub لمراقبة الأحداث والتفاعل معها في مساحة اجتماع Meet. تسجّل عيّنة التطبيق وقت بدء المؤتمرات وانتهائها، ووقت انضمام المشاركين أو مغادرتهم، ووقت توفّر أي عناصر تم إنشاؤها في الاجتماع.

بدلاً من الاشتراك في مساحة اجتماع معيّنة، يمكنك الاشتراك في حساب مستخدم Meet لتلقّي إشعارات بشأن أي مساحة اجتماع يملكها المستخدم أو ينظّمها. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة الاشتراك في أحداث Google Meet في مستندات Google Workspace Events API.

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

إذا كنت بحاجة إلى تفعيل أي من المتطلبات الأساسية التالية لمؤسستك، اطلب من مشرف Google Workspace تفعيلها:

• حساب Google Workspace لديه إذن الوصول إلى Google Meet
• إذن بإنشاء مشروع على Google Cloud
• تثبيت Python 3
• تم تثبيت gcloud CLI.

إعداد البيئة

يوضّح هذا القسم كيفية إنشاء بيئتك المحلية وإعدادها، بالإضافة إلى مشروع Google Cloud الخاص بهذا البرنامج التعليمي.

إنشاء دليل عمل وبيئة Python افتراضية

لإنشاء بيئة افتراضية جديدة وتفعيلها، شغِّل الأوامر التالية في الوحدة الطرفية.

mkdir meet-tutorial
cd meet-tutorial
python3 -mvenv env
source env/bin/activate

mkdir meet-tutorial
cd meet-tutorial
python3 -mvenv env
env/bin/activate.bat

mkdir meet-tutorial
cd meet-tutorial
python3 -mvenv env
env/bin/activate.ps1

إنشاء مشروع على Google Cloud

تفعيل الفوترة لمشروع Google Cloud

إعداد المصادقة والتفويض

تتيح المصادقة والتفويض للتطبيق الوصول إلى موارد واجهة برمجة تطبيقات REST في Meet. يجب الحصول على إذن المستخدم لاستدعاء Meet REST API. يوضّح لك هذا القسم كيفية ضبط بيانات اعتماد المستخدم وطلب التفويض.

ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth واختيار النطاقات

تقترح الخطوات التالية معلومات نائبة لإعداد شاشة موافقة OAuth لتطبيقك. قبل نشر التطبيق خارجيًا، عدِّل هذه المعلومات.

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

   الانتقال إلى "الهوية البصرية للعلامة التجارية"

2. إذا سبق لك ضبط Google Auth platform، يمكنك ضبط إعدادات "شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth" التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك الرسالة Google Auth platform لم يتم الإعداد بعد، انقر على البدء:
1. ضمن معلومات التطبيق، في اسم التطبيق، أدخِل Meet REST API Tutorial.
2. في البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
3. انقر على التالي.
4. ضمن الجمهور، اختَر داخلي.
5. انقر على التالي.
6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات فيه بشأن أي تغييرات تطرأ على مشروعك.
7. انقر على التالي.
8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت توافق عليها، ضَع علامة في المربّع بجانب أوافق على سياسة بيانات المستخدمين في خدمات Google API.
9. انقر على متابعة.
10. انقر على إنشاء.
11. إذا اخترت خارجي لنوع المستخدم، أضِف مستخدمين للاختبار:
    1. انقر على الجمهور.
    2. ضمن المستخدمون التجريبيون، انقر على إضافة مستخدمين.
    3. أدخِل عنوان بريدك الإلكتروني وأي مستخدمين آخرين معتمَدين للاختبار، ثم انقر على حفظ.
3. انقر على الوصول إلى البيانات > إضافة نطاقات أو إزالتها. ستظهر لوحة تتضمّن قائمة بالنطاقات لكل واجهة برمجة تطبيقات فعّلتها في مشروعك على Google Cloud.
4. ضمن إضافة النطاقات يدويًا، الصِق النطاقات التالية:
   • https://www.googleapis.com/auth/meetings.space.created
5. انقر على إضافة إلى الجدول.
6. انقر على تعديل.
7. بعد اختيار النطاقات التي يتطلّبها تطبيقك، انقر على حفظ.

لمزيد من المعلومات حول ضبط موافقة OAuth، يُرجى الاطّلاع على بدء استخدام Google Auth platform.

إنشاء معرّف عميل

يعمل معرّف العميل كبيانات اعتماد لتطبيقك أثناء عمليات OAuth 2.0. بما أنّ التطبيق يعمل على الجهاز فقط، أنشئ معرّف عميل لتطبيق على الكمبيوتر.

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

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

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

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

تثبيت مكتبات مصادقة Google

ثبِّت مكتبات مصادقة Google:

pip install google-auth google-auth-oauthlib

تنفيذ التفويض

تتطلّب واجهة Meet REST API بيانات اعتماد المستخدم في شكل رمز دخول OAuth 2.0. في هذا القسم، عليك تنفيذ عملية OAuth 2.0 لطلب رمز مميز للوصول ورمز مميز لإعادة التحميل للمستخدم.

1. في دليل العمل، أنشئ الملف main.py وأضِف المحتوى التالي:

   import os
   import json
   
   from google.auth.transport import requests
   from google.oauth2.credentials import Credentials
   from google_auth_oauthlib.flow import InstalledAppFlow
   
   def authorize() -> Credentials:
       """Ensure valid credentials for calling the Meet REST API."""
       CLIENT_SECRET_FILE = "./client_secret.json"
       credentials = None
   
       if os.path.exists('token.json'):
           credentials = Credentials.from_authorized_user_file('token.json')
   
       if credentials is None:
           flow = InstalledAppFlow.from_client_secrets_file(
               CLIENT_SECRET_FILE,
               scopes=[
                   'https://www.googleapis.com/auth/meetings.space.created',
               ])
           flow.run_local_server(port=0)
           credentials = flow.credentials
   
       if credentials and credentials.expired:
           credentials.refresh(requests.Request())
   
       if credentials is not None:
           with open("token.json", "w") as f:
               f.write(credentials.to_json())
   
       return credentials
   
   USER_CREDENTIALS = authorize()
   

2. لتشغيل الرمز، يجب توفُّر كلّ من معرّف العميل والسرّ اللذين تم إنشاؤهما سابقًا. انسخ ملف سرّ العميل الذي تم تنزيله إلى دليل العمل الخاص بالمشروع وأعِد تسميته إلى client_secret.json.

3. إذا أردت اختبار طريقة عمل التفويض، نفِّذ الأمر التالي. يطلب التطبيق الحصول على إذن ويُنشئ ملف token.json في دليل عمل المشروع بعد الموافقة على الطلب.

   python3 main.py

إضافة واجهة برمجة تطبيقات REST في Meet

بعد إكمال رمز التفويض، حان الوقت لتفعيل واجهة برمجة تطبيقات REST الخاصة بـ Meet واستدعائها.

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

على الرغم من أنّ هذا القسم يركّز على واجهة Meet REST API، إلا أنّ هذا البرنامج التعليمي يستخدم أيضًا Google Cloud Pub/Sub وGoogle Workspace Events API.

تثبيت مكتبة برامج واجهة Meet REST API

اتّبِع الخطوات التالية لتثبيت مكتبة برامج Meet REST API:

1. نفِّذ الأمر التالي:

   pip install google-apps-meet

2. عدِّل ملف main.py لاستيراد العميل:

   from google.apps import meet_v2 as meet
   

إنشاء مساحة

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

تعديل main.py وإضافة ما يلي:

def create_space() -> meet.Space:
    """Create a meeting space."""
    client = meet.SpacesServiceClient(credentials=USER_CREDENTIALS)
    request = meet.CreateSpaceRequest()
    return client.create_space(request=request)

الاشتراك في الأحداث

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

ضبط إعدادات Google Cloud Pub/Sub

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

دوِّن اسم الموضوع وتأكَّد من أنّ قيمة {project} هي معرّف مشروع Cloud لتطبيقك. ستستخدم اسم الموضوع لإنشاء اشتراك Google Workspace لاحقًا.

إنشاء حساب خدمة

استخدام حساب الخدمة

بعد إنشاء حساب الخدمة، امنح نفسك إذنًا بانتحال هوية حساب الخدمة.

تثبيت مكتبة برامج Pub/Sub

1. استخدِم pip لتثبيت مكتبة البرامج الخاصة بخدمة Pub/Sub:

   pip install google-cloud-pubsub

2. بعد ذلك، عدِّل main.py لاستيراد العميل:

   from google.cloud import pubsub_v1
   

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

أضِف الرمز التالي إلى main.py لتحديد طريقة للاشتراك في أحداث Meet. يشترك هذا الرمز في جميع الأحداث الخاصة بمساحة اجتماع. عند الاشتراك، يتم نشر الأحداث في موضوع Pub/Sub.

def subscribe_to_space(space_name: str = None, topic_name: str = None):
    """Subscribe to events for a meeting space."""
    session = requests.AuthorizedSession(USER_CREDENTIALS)
    body = {
        'targetResource': f"//meet.googleapis.com/{space_name}",
        "eventTypes": [
            "google.workspace.meet.conference.v2.started",
            "google.workspace.meet.conference.v2.ended",
            "google.workspace.meet.participant.v2.joined",
            "google.workspace.meet.participant.v2.left",
            "google.workspace.meet.recording.v2.fileGenerated",
            "google.workspace.meet.transcript.v2.fileGenerated",
        ],
        "payloadOptions": {
            "includeResource": False,
        },
        "notificationEndpoint": {
            "pubsubTopic": topic_name
        },
        "ttl": "86400s",
    }
    response = session.post("https://workspaceevents.googleapis.com/v1/subscriptions", json=body)
    return response

بعد ذلك، أضِف الرمز البرمجي المناسب لجلب الأحداث ومعالجتها.

الاستماع إلى الأحداث والتعامل معها

واصِل تعديل main.py وأضِف نموذج الرمز التالي. ينفّذ هذا الرمز الجانب المتلقّي ويستخدم واجهة برمجة التطبيقات Google Cloud Pub/Sub لسحب الأحداث عند توفّرها. تطبع طرق المعالجة المختلفة معلومات حول الأحداث ذات الصلة.

def format_participant(participant: meet.Participant) -> str:
    """Formats a participant for display on the console."""
    if participant.anonymous_user:
        return f"{participant.anonymous_user.display_name} (Anonymous)"

    if participant.signedin_user:
        return f"{participant.signedin_user.display_name} (ID: {participant.signedin_user.user})"

    if participant.phone_user:
        return f"{participant.phone_user.display_name} (Phone)"

    return "Unknown participant"


def fetch_participant_from_session(session_name: str) -> meet.Participant:
    """Fetches the participant for a session."""
    client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
    # Use the parent path of the session to fetch the participant details
    parsed_session_path = client.parse_participant_session_path(session_name)
    participant_resource_name = client.participant_path(
        parsed_session_path["conference_record"],
        parsed_session_path["participant"])
    return client.get_participant(name=participant_resource_name)


def on_conference_started(message: pubsub_v1.subscriber.message.Message):
    """Display information about a conference when started."""
    payload = json.loads(message.data)
    resource_name = payload.get("conferenceRecord").get("name")
    client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
    conference = client.get_conference_record(name=resource_name)
    print(f"Conference (ID {conference.name}) started at {conference.start_time.rfc3339()}")


def on_conference_ended(message: pubsub_v1.subscriber.message.Message):
    """Display information about a conference when ended."""
    payload = json.loads(message.data)
    resource_name = payload.get("conferenceRecord").get("name")
    client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
    conference = client.get_conference_record(name=resource_name)
    print(f"Conference (ID {conference.name}) ended at {conference.end_time.rfc3339()}")


def on_participant_joined(message: pubsub_v1.subscriber.message.Message):
    """Display information about a participant when they join a meeting."""
    payload = json.loads(message.data)
    resource_name = payload.get("participantSession").get("name")
    client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
    session = client.get_participant_session(name=resource_name)
    participant = fetch_participant_from_session(resource_name)
    display_name = format_participant(participant)
    print(f"{display_name} joined at {session.start_time.rfc3339()}")


def on_participant_left(message: pubsub_v1.subscriber.message.Message):
    """Display information about a participant when they leave a meeting."""
    payload = json.loads(message.data)
    resource_name = payload.get("participantSession").get("name")
    client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
    session = client.get_participant_session(name=resource_name)
    participant = fetch_participant_from_session(resource_name)
    display_name = format_participant(participant)
    print(f"{display_name} left at {session.end_time.rfc3339()}")


def on_recording_ready(message: pubsub_v1.subscriber.message.Message):
    """Display information about a recorded meeting when artifact is ready."""
    payload = json.loads(message.data)
    resource_name = payload.get("recording").get("name")
    client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
    recording = client.get_recording(name=resource_name)
    print(f"Recording available at {recording.drive_destination.export_uri}")


def on_transcript_ready(message: pubsub_v1.subscriber.message.Message):
    """Display information about a meeting transcript when artifact is ready."""
    payload = json.loads(message.data)
    resource_name = payload.get("transcript").get("name")
    client = meet.ConferenceRecordsServiceClient(credentials=USER_CREDENTIALS)
    transcript = client.get_transcript(name=resource_name)
    print(f"Transcript available at {transcript.docs_destination.export_uri}")


def on_message(message: pubsub_v1.subscriber.message.Message) -> None:
    """Handles an incoming event from the Google Cloud Pub/Sub API."""
    event_type = message.attributes.get("ce-type")
    handler = {
        "google.workspace.meet.conference.v2.started": on_conference_started,
        "google.workspace.meet.conference.v2.ended": on_conference_ended,
        "google.workspace.meet.participant.v2.joined": on_participant_joined,
        "google.workspace.meet.participant.v2.left": on_participant_left,
        "google.workspace.meet.recording.v2.fileGenerated": on_recording_ready,
        "google.workspace.meet.transcript.v2.fileGenerated": on_transcript_ready,
    }.get(event_type)

    try:
        if handler is not None:
            handler(message)
        message.ack()
    except Exception as error:
        print("Unable to process event")
        print(error)


def listen_for_events(subscription_name: str = None):
    """Subscribe to events on the subscription."""
    subscriber = pubsub_v1.SubscriberClient()
    with subscriber:
        future = subscriber.subscribe(subscription_name, callback=on_message)
        print("Listening for events")
        try:
            future.result()
        except KeyboardInterrupt:
            future.cancel()
    print("Done")

إكمال الرمز

أضِف الرمز التالي إلى main.py لاستدعاء الطرق لإنشاء المساحة والاشتراك في الأحداث والاستماع إليها. عدِّل الثابتَين TOPIC_NAME وSUBSCRIPTION_NAME باستخدام اسم الموضوع واسم الاشتراك اللذين سبق أن أنشأتهما.

1. أضِف الرمز إلى main.py:

   space = create_space()
   print(f"Join the meeting at {space.meeting_uri}")
   
   TOPIC_NAME = "projects/PROJECT_ID/topics/TOPIC_ID"
   SUBSCRIPTION_NAME = "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID"
   
   subscription = subscribe_to_space(topic_name=TOPIC_NAME, space_name=space.name)
   if (subscription.status_code) == 200:
       listen_for_events(subscription_name=SUBSCRIPTION_NAME)
   else:
       print(f"Subscription to Meet events failed, response data: {subscription.content}")
   

   غيِّر القيم في السلسلة على الشكل التالي:

   • PROJECT_ID: معرّف مشروع Cloud الفريد لتطبيقك، مثل my-sample-project-191923

   • استبدِل TOPIC_ID باسم موضوع Pub/Sub الذي أنشأته في مشروعك على السحابة الإلكترونية.

   • SUBSCRIPTION_ID: تمثّل هذه السمة اسم اشتراكك، مثل workspace-events-sub.

2. شغِّل البرنامج:

   python3 main.py

إذا لم يسبق لك تشغيل البرنامج، سيطلب منك تقديم إذن بالتخويل في المرة الأولى. امنح التطبيق إذن الوصول إلى واجهة برمجة تطبيقات Meet REST. بعد تشغيل البرنامج بنجاح، من المفترض أن تظهر لك نتيجة مشابهة لما يلي:

Join the meeting at https://meet.google.com/abc-mnop-xyz

الانضمام إلى الاجتماع

لإنشاء أحداث للتطبيق، انضم إلى المؤتمر باستخدام عنوان URL الذي يعرضه التطبيق. بعد الانضمام، يمكنك تجربة الإجراءات التالية لتفعيل الأحداث:

• مغادرة الاجتماع والانضمام إليه مجددًا
• دعوة الآخرين أو الاتصال باستخدام هاتفك
• فعِّل التسجيلات والنصوص.

يؤدي كل نشاط من هذه الأنشطة إلى إنشاء حدث يتلقّاه التطبيق ويسجّله في Google Cloud Console.

استخدِم ctrl-c لإيقاف البرنامج مؤقتًا عند الانتهاء.

خطوات اختيارية يمكنك تجربتها

تسجّل التطبيقات تفاصيل أساسية عن الأحداث. لمواصلة استكشاف واجهة برمجة تطبيقات REST في Meet، جرِّب تعديل التطبيق لتنفيذ الإجراءات الإضافية التالية.

• استخدِم People API لاسترداد معلومات إضافية عن المشاركين الذين سجّلوا الدخول.

  def subscribe_to_user(user_name: str = None, topic_name: str = None) -> requests_lib.Response:
      """Subscribe to events for a user."""
      session = requests.AuthorizedSession(USER_CREDENTIALS)
      body = {
          "targetResource": f"//cloudidentity.googleapis.com/users/{user_name}",
          "eventTypes": [
              "google.workspace.meet.conference.v2.started",
              "google.workspace.meet.conference.v2.ended",
              "google.workspace.meet.participant.v2.joined",
              "google.workspace.meet.participant.v2.left",
              "google.workspace.meet.recording.v2.fileGenerated",
              "google.workspace.meet.transcript.v2.fileGenerated",
          ],
          "payloadOptions": {
              "includeResource": False,
          },
          "notificationEndpoint": {"pubsubTopic": topic_name},
          "ttl": "86400s",
      }
      response = session.post(
          "https://workspaceevents.googleapis.com/v1/subscriptions", json=body
      )
      return response
  
  service = build("people", "v1", credentials=USER_CREDENTIALS)
  response = (
      service.people()
      .get(resourceName="people/me", personFields="names,emailAddresses")
      .execute()
  )
  resource_name = response.get("resourceName")
  if resource_name.startswith("people/"):
      resource_name = resource_name[len("people/") :]
  
  subscription = subscribe_to_user(topic_name=TOPIC_NAME, user_name=resource_name)
  

  احرص على إضافة "https://www.googleapis.com/auth/userinfo.profile" في طريقة التفويض في نماذج بيانات الاعتماد أعلاه.

• استخدِم Google Drive API لتنزيل التسجيلات والنصوص.

• بدلاً من تنزيل النصوص من Google Drive، يمكنك استردادها باستخدام طُرق النص المنظَّم في واجهة Meet REST API.

• الحصول على مساحة بدلاً من إنشائها

  def get_space(meeting_code: str) -> meet.Space:
      """Get a meeting space."""
      client = meet.SpacesServiceClient(credentials=USER_CREDENTIALS)
      return client.get_space(name="spaces/" + meeting_code)
  

  احرص على إضافة "https://www.googleapis.com/auth/meetings.space.readonly" في طريقة التفويض في نماذج بيانات الاعتماد أعلاه.

اختياري: التنظيف

لتجنُّب تحمّل رسوم في حسابك على وحدة تحكّم Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بتنظيف أي موارد ومشاريع تم إنشاؤها.

لإلغاء الاشتراك، اتّبِع الخطوات التالية:

لحذف الموضوع، اتّبِع الخطوات التالية:

لحذف المشروع، اتّبِع الخطوات التالية:

مواضيع ذات صلة

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