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

كل حلّ لعقد المؤتمرات التي حددتها في مشروع النص البيان حساب 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 لبرمجة التطبيقات أو 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;
}