تتبُّع أحداث الاجتماعات باستخدام 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.

إعداد البيئة

يوضّح هذا القسم كيفية إنشاء وضبط البيئة المحلية وproject 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

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

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

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

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

1. في وحدة تحكّم Google Cloud، انتقِل إلى رمز القائمة menu > APIs & Services (واجهات برمجة التطبيقات والخدمات) > OAuth consent screen (شاشة موافقة OAuth).

   الانتقال إلى شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

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

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

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

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

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

2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
3. انقر على نوع التطبيق > تطبيق كمبيوتر مكتبي.
4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. ولا يظهر هذا الاسم إلا في "وحدة تحكّم Google Cloud".
5. انقر على إنشاء. تظهر شاشة "تم إنشاء عميل OAuth"، والتي تعرض معرّف العميل الجديد وسرّه.
6. انقر على موافق. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرِّفات عملاء 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 في directory directory project بعد الموافقة على الطلب.

   python3 main.py
   

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

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

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

على الرغم من أنّ هذا القسم يركّز على 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
   

إنشاء مساحة

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

عدِّل 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 API لسحب الحدثَين عند توفّرهما. تطبع طرق معالِج الأحداث المختلفة معلومات عن الأحداث المقابلة.

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)
   listen_for_events(subscription_name=SUBSCRIPTION_NAME)
   

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

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

   • TOPIC_ID: اسم موضوع Pub/Sub الذي أنشأته في مشروعك على Cloud

   • 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.

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

خطوات إضافية يمكنك تجربتها (اختيارية)

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

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

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

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

لحذف الاشتراك:

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

لحذف المشروع:

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

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