إنشاء مكالمات فيديو تابعة لجهة خارجية

ملاحظة: تم تصميم هذه الوظيفة خصيصًا لمقدّمي خدمات المؤتمرات، وكانت متاحة في الأصل باسم مكوّنات إضافية لمكالمات الفيديو في "تقويم Google".

لكل حلّ مؤتمرات محدّد في بيان مشروع النص البرمجي، يكون onCreateFunction مرتبطًا به. تستدعي إضافة Google Workspace هذه الدالة لإنشاء اجتماع فيديو عندما يحاول المستخدم اختيار حل اجتماع الفيديو هذا لحدث ما.

نفِّذ كل onCreateFunction موضح في بيان الإضافة. يجب أن تؤدي هذه الوظائف ما يلي:

1. استرداد أي معلومات عن أحداث "تقويم Google"، مثل رقم تعريف الحدث أو قائمة الضيوف، التي يحتاجها نظام المؤتمرات التابع لجهة خارجية لإنشاء المؤتمر
2. اربط حسابك بخدمة اجتماعات تابعة لجهة خارجية وأنشئ اجتماعًا جديدًا باستخدام معلومات حدث التقويم.
3. إذا تعذّر إنشاء المؤتمر، استخدِم معلومات الخطأ لإنشاء وعرض عنصر ConferenceData يتضمّن ConferenceError. بخلاف ذلك، أكمِل الخطوات التالية.
4. ابدأ مزامنة المؤتمر.
5. استخدِم المعلومات التي تعرضها خدمة مكالمة الفيديو التابعة لجهة خارجية لإنشاء وعرض عنصر ConferenceData جديد.

استرداد معلومات الحدث

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

عند استدعاء كل onCreateFunction تحدّده، يتم تمرير وسيطة إليه تحتوي على أرقام تعريف التقويم والحدث. استخدِم أرقام التعريف هذه لاسترداد معلومات الحدث الكاملة باستخدام خدمة "تقويم Google" المتقدّمة.

من الممكن أن يضيف "تقويم Google" تفاصيل عن مكالمة فيديو إلى حدث قبل إنشائه. في مثل هذه الحالات، يمرِّر "تقويم Google" onCreateFunction صالحًا eventId، ولكن قد تؤدي الطلبات اللاحقة إلى Calendar.Events.get إلى حدوث خطأ يشير إلى أنّ الحدث غير متوفّر. في هذه الحالات، أنشئ مؤتمرًا تابعًا لجهة خارجية باستخدام بيانات نائبة، وسيتم استبدال هذه البيانات في المرة التالية التي تتم فيها مزامنة الحدث.

إنشاء مكالمة جماعية تابعة لجهة خارجية

بعد أن يسترد onCreateFunction بيانات الحدث اللازمة، يجب أن يتصل بنظام مكالمات الفيديو التابع لجهة خارجية لإنشاء المؤتمر. ويتم ذلك عادةً من خلال إرسال طلبات بيانات من واجهة برمجة التطبيقات متوافقة مع نظام المؤتمرات التابع لجهة خارجية. راجِع وثائق منصة لمكالمات فيديو التابعة لجهة خارجية لتحديد طلبات واجهة برمجة التطبيقات التي يمكنك استخدامها لإنشاء مؤتمرات.

في "برمجة تطبيقات Google"، أسهل طريقة للتعامل مع طلبات واجهة برمجة التطبيقات الخارجية هي استخدام مكتبات المصدر المفتوح OAuth2 لبرمجة تطبيقات Google أو OAuth1 لبرمجة تطبيقات Google. يمكنك أيضًا الربط بواجهات برمجة التطبيقات الخارجية باستخدام خدمة UrlFetch، ولكن يتطلّب ذلك منك التعامل مع تفاصيل التفويض بشكل صريح.

بعد طلب إنشاء مؤتمر، قد تحتاج إلى تقديم طلبات إضافية لاسترداد تفاصيل المؤتمر الجديد.

بدء مزامنة المؤتمرات

بعد أن تنشئ الإضافة اجتماعًا بنجاح على نظام تابع لجهة خارجية، يجب اتّخاذ بضع خطوات لتفعيل المزامنة كي تظهر التغييرات التي يتم إجراؤها على حدث "تقويم Google" في الاجتماع.

راجِع مقالة مزامنة التغييرات في "تقويم Google" للحصول على تفاصيل حول إعداد المزامنة بعد إنشاء مكالمة الفيديو.

إنشاء ردّ على بيانات المؤتمر

باستخدام معلومات الاجتماع التي تعرضها الخدمة الخارجية، يجب أن ينشئ onCreateFunction ثم يعرض كائن ConferenceData، ويصف قسم بيانات الاجتماع محتوى هذا الكائن. يستخدم "تقويم Google" هذه المعلومات لتوجيه المستخدمين إلى الاجتماع عند بدئه.

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

معالجة الأخطاء

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

عند إنشاء عنصر ConferenceData للإبلاغ عن خطأ، ليس عليك تضمين أي مكوّنات ConferenceData باستثناء العنصر ConferenceError. يمكن أن يتضمّن ConferenceErrors ConferenceErrorType ورسالة خطأ، وفي حال حدوث مشاكل في المصادقة، يمكن أن يتضمّن عنوان URL يتيح للمستخدمين تسجيل الدخول إلى نظام اجتماعات الفيديو التابع لجهة خارجية.

لا تحتاج الإضافة إلى محاولة إعداد مزامنة الاجتماعات إذا تعذّر إنشاء الاجتماع.

مثال

يوضّح المثال التالي عملية تنفيذ onCreateFunction. يمكن أن يكون اسم الدالة أي شيء، ولكن عليك تحديدها في بيان مشروع الإضافة.

تتصل الدالة create3rdPartyConference بالنظام التابع لجهة خارجية لإنشاء مكالمة الفيديو، وتنشئ الدالة getAuthenticationUrl عنوان URL مخصّص للمصادقة على النظام التابع لجهة خارجية. ولا يتم تنفيذها بالكامل هنا.

لا تظهر الدالة initializeSyncing هنا، فهي تعالج العمل الأوّلي المطلوب للمزامنة. راجِع مقالة مزامنة تغييرات التقويم للحصول على التفاصيل.

/**
 *  Creates a conference, then builds and returns a ConferenceData object
 *  with the corresponding conference information. This method is called
 *  when a user selects a conference solution defined by the add-on that
 *  uses this function as its 'onCreateFunction' in the add-on manifest.
 *
 *  @param {Object} arg The default argument passed to a 'onCreateFunction';
 *      it carries information about the Google Calendar event.
 *  @return {ConferenceData}
 */
function createConference(arg) {
  const eventData = arg.eventData;
  const calendarId = eventData.calendarId;
  const eventId = eventData.eventId;

  // Retrieve the Calendar event information using the Calendar
  // Advanced service.
  var calendarEvent;
  try {
    calendarEvent = Calendar.Events.get(calendarId, eventId);
  } catch (err) {
    // The calendar event does not exist just yet; just proceed with the
    // given event ID and allow the event details to sync later.
    console.log(err);
    calendarEvent = {
      id: eventId,
    };
  }

  // Create a conference on the third-party service and return the
  // conference data or errors in a custom JSON object.
  var conferenceInfo = create3rdPartyConference(calendarEvent);

  // Build and return a ConferenceData object, either with conference or
  // error information.
  var dataBuilder = ConferenceDataService.newConferenceDataBuilder();

  if (!conferenceInfo.error) {
    // No error, so build the ConferenceData object from the
    // returned conference info.

    var phoneEntryPoint = ConferenceDataService.newEntryPoint()
        .setEntryPointType(ConferenceDataService.EntryPointType.PHONE)
        .setUri('tel:+' + conferenceInfo.phoneNumber)
        .setPin(conferenceInfo.phonePin);

    var adminEmailParameter = ConferenceDataService.newConferenceParameter()
        .setKey('adminEmail')
        .setValue(conferenceInfo.adminEmail);

    dataBuilder.setConferenceId(conferenceInfo.id)
        .addEntryPoint(phoneEntryPoint)
        .addConferenceParameter(adminEmailParameter)
        .setNotes(conferenceInfo.conferenceLegalNotice);

    if (conferenceInfo.videoUri) {
      var videoEntryPoint = ConferenceDataService.newEntryPoint()
          .setEntryPointType(ConferenceDataService.EntryPointType.VIDEO)
          .setUri(conferenceInfo.videoUri)
          .setPasscode(conferenceInfo.videoPasscode);
      dataBuilder.addEntryPoint(videoEntryPoint);
    }

    // Since the conference creation request succeeded, make sure that
    // syncing has been enabled.
    initializeSyncing(calendarId, eventId, conferenceInfo.id);

  } else if (conferenceInfo.error === 'AUTH') {
    // Authenentication error. Implement a function to build the correct
    // authenication URL for the third-party conferencing system.
    var authenticationUrl = getAuthenticationUrl();
    var error = ConferenceDataService.newConferenceError()
        .setConferenceErrorType(
            ConferenceDataService.ConferenceErrorType.AUTHENTICATION)
        .setAuthenticationUrl(authenticationUrl);
    dataBuilder.setError(error);

  } else {
    // Other error type;
    var error = ConferenceDataService.newConferenceError()
        .setConferenceErrorType(
            ConferenceDataService.ConferenceErrorType.TEMPORARY);
    dataBuilder.setError(error);
  }

  // Don't forget to build the ConferenceData object.
  return dataBuilder.build();
}


/**
 *  Contact the third-party conferencing system to create a conference there,
 *  using the provided calendar event information. Collects and retuns the
 *  conference data returned by the third-party system in a custom JSON object
 *  with the following fields:
 *
 *    data.adminEmail - the conference administrator's email
 *    data.conferenceLegalNotice - the conference legal notice text
 *    data.error - Only present if there was an error during
 *         conference creation. Equal to 'AUTH' if the add-on user needs to
 *         authorize on the third-party system.
 *    data.id - the conference ID
 *    data.phoneNumber - the conference phone entry point phone number
 *    data.phonePin - the conference phone entry point PIN
 *    data.videoPasscode - the conference video entry point passcode
 *    data.videoUri - the conference video entry point URI
 *
 *  The above fields are specific to this example; which conference information
 *  your add-on needs is dependent on the third-party conferencing system
 *  requirements.
 *
 * @param {Object} calendarEvent A Calendar Event resource object returned by
 *     the Google Calendar API.
 * @return {Object}
 */
function create3rdPartyConference(calendarEvent) {
  var data = {};

  // Implementation details dependent on the third-party system API.
  // Typically one or more API calls are made to create the conference and
  // acquire its relevant data, which is then put in to the returned JSON
  // object.

  return data;
}

/**
 *  Return the URL used to authenticate the user with the third-party
 *  conferencing system.
 *
 *  @return {String}
 */
function getAuthenticationUrl() {
  var url;
  // Implementation details dependent on the third-party system.

  return url;
}