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

• ؛

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

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

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

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

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

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

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

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

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

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

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

إعداد مزامنة مكالمة الفيديو

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

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

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

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

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