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

المحتوى

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بناء استجابة بيانات مكالمة الفيديو

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

عند إنشاء كائن ConferenceData، يجب الانتباه إلى أنّ هناك بعض القيود على أطوال الحقول وتنسيقات معرِّفات الموارد المنتظمة (URI) لنقاط الدخول ومجموعة نقاط الدخول المسموح بها. على سبيل المثال، يمكن أن تكون هناك نقطة دخول VIDEO واحدة كحدّ أقصى في ConferenceData تتطابق هذه القيود مع القيود الموضّحة في حدث واجهة برمجة التطبيقات للتقويم للحقل conferenceData المقابل، على الرغم من عدم توفُّر جميع حقول أحداث واجهة برمجة التطبيقات الموضحة هناك في "برمجة التطبيقات".

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

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