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

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

يجب تنفيذ كل onCreateFunction موضّح في بيان الملحق. بشكل عام، يجب أن تؤدي هذه الدوالّ ما يلي:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

عند إنشاء عنصر ConferenceData ، يُرجى العِلم أنّ هناك بعض القيود المفروضة على أطوال الحقول وتنسيقات معرّفات الموارد المنتظمة لنقاط الدخول والمجموعات المسموح بها لنقاط الدخول. على سبيل المثال، يمكن أن تكون هناك نقطة إدخال VIDEO واحدة على الأكثر في ConferenceData واحدة. وتتشابه هذه القيود مع القيود الموضّحة في حدث واجهة برمجة تطبيقات التقويم للحقل 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;
}