کنفرانس های شخص ثالث ایجاد کنید

توجه: این قابلیت به‌طور خاص برای ارائه‌دهندگان کنفرانس ساخته شده است و در ابتدا به‌عنوان افزونه‌های کنفرانس تقویم در دسترس بود.

هر راهکار کنفرانس تعریف شده در اسکریپت مانیفست پروژه شما یک onCreateFunction مرتبط دارد. افزونه Google Workspace این تابع را برای ایجاد یک کنفرانس فراخوانی می‌کند، هر زمان که کاربر سعی کند آن راهکار کنفرانس را برای یک رویداد انتخاب کند.

هر onCreateFunction که در فایل مانیفست افزونه شما توضیح داده شده است را پیاده‌سازی کنید. این توابع باید موارد زیر را انجام دهند:

1. هرگونه اطلاعات رویداد تقویم گوگل، مانند شناسه رویداد یا فهرست شرکت‌کنندگان، را که سیستم کنفرانس شخص ثالث برای ایجاد کنفرانس به آن نیاز دارد، بازیابی کنید.
2. به سرویس کنفرانس شخص ثالث متصل شوید و با استفاده از اطلاعات رویداد تقویم، یک کنفرانس جدید در آنجا ایجاد کنید.
3. اگر درخواست ایجاد کنفرانس با شکست مواجه شد، از اطلاعات خطا برای ساخت و بازگرداندن یک شیء ConferenceData حاوی ConferenceError استفاده کنید. در غیر این صورت، مراحل بعدی را انجام دهید.
4. همگام‌سازی کنفرانس را آغاز کنید.
5. از اطلاعات برگردانده شده توسط سرویس کنفرانس شخص ثالث برای ساخت و برگرداندن یک شیء جدید ConferenceData استفاده کنید.

بازیابی اطلاعات رویداد

برای ایجاد یک کنفرانس شخص ثالث، اطلاعات مربوط به رویداد تقویم مربوطه مورد نیاز است. اطلاعات دقیق رویداد مورد نیاز بین سیستم‌های کنفرانس شخص ثالث مختلف متفاوت است، اما اغلب شامل زمان شروع رویداد، زمان پایان، خلاصه، لیست شرکت‌کنندگان و شناسه می‌شود.

هنگام فراخوانی، به هر onCreateFunction که تعریف می‌کنید، یک آرگومان ارسال می‌شود که شامل شناسه‌های تقویم و رویداد است. از این شناسه‌ها برای بازیابی اطلاعات کامل رویداد با استفاده از سرویس پیشرفته Calendar استفاده کنید.

تقویم می‌تواند جزئیات کنفرانس را قبل از وجود یک رویداد به آن اضافه کند. در چنین مواردی، تقویم به تابع onCreateFunction یک eventId معتبر ارسال می‌کند، اما فراخوانی‌های بعدی به Calendar.Events.get می‌تواند منجر به خطایی شود که می‌گوید رویداد وجود ندارد. در این موارد، کنفرانس شخص ثالث را با استفاده از داده‌های placeholder ایجاد کنید؛ این داده‌ها دفعه بعد که رویداد همگام‌سازی می‌شود، جایگزین می‌شوند.

ایجاد کنفرانس شخص ثالث

پس از اینکه onCreateFunction داده‌های رویداد لازم را بازیابی کرد، باید برای ایجاد کنفرانس به سیستم کنفرانس شخص ثالث متصل شود. معمولاً این کار با ارسال درخواست‌های API پشتیبانی‌شده توسط سیستم کنفرانس شخص ثالث انجام می‌شود. مستندات مربوط به راهکار کنفرانس شخص ثالث خود را بررسی کنید تا مشخص شود از چه درخواست‌های API می‌توانید برای ایجاد کنفرانس‌ها استفاده کنید.

در Google Apps Script، ساده‌ترین راه برای مدیریت درخواست‌های API خارجی، استفاده از کتابخانه‌های متن‌باز OAuth2 for Apps Script یا OAuth1 for Apps Script است. همچنین می‌توانید با استفاده از سرویس UrlFetch به APIهای خارجی متصل شوید ، اما این امر مستلزم آن است که جزئیات مجوز را به صراحت مدیریت کنید.

پس از درخواست ایجاد کنفرانس، ممکن است لازم باشد درخواست‌های دیگری برای بازیابی جزئیات کنفرانس جدید ارسال کنید.

همگام‌سازی کنفرانس را آغاز کنید

پس از اینکه افزونه با موفقیت کنفرانسی را در یک سیستم شخص ثالث ایجاد کرد، باید چند مرحله را برای فعال کردن همگام‌سازی انجام دهد تا تغییرات رویداد تقویم در کنفرانس منعکس شود.

برای جزئیات بیشتر در مورد تنظیمات همگام‌سازی پس از ایجاد کنفرانس، به بخش همگام‌سازی تغییرات تقویم مراجعه کنید.

ساخت یک پاسخ داده کنفرانسی

با استفاده از اطلاعات کنفرانس که توسط سرویس شخص ثالث برگردانده می‌شود، تابع onCreateFunction باید یک شیء ConferenceData بسازد و برگرداند؛ بخش داده‌های کنفرانس ، محتوای این شیء را توصیف می‌کند. تقویم از این اطلاعات برای هدایت کاربران به کنفرانس پس از شروع آن استفاده می‌کند.

هنگام ساخت یک شیء ConferenceData ، از طول فیلدها، قالب‌های URIهای نقطه ورودی و ترکیب‌های مجاز نقاط ورودی آگاه باشید. برای مثال، حداکثر یک نقطه ورودی VIDEO می‌تواند در یک ConferenceData وجود داشته باشد. این محدودیت‌ها با محدودیت‌های شرح داده شده در رویداد API تقویم برای فیلد conferenceData مربوطه یکسان هستند، اگرچه همه فیلدهای رویداد API شرح داده شده در آنجا در Apps Script موجود نیستند.

مدیریت خطاها

ممکن است در طول فرآیند ایجاد کنفرانس، خطاهایی رخ دهد. در برخی موارد، ایجاد کنفرانس به دلیل خطایی که توسط سیستم کنفرانس شخص ثالث بازگردانده می‌شود، نمی‌تواند تکمیل شود. در این موارد، افزونه شما باید با ساخت و بازگرداندن یک شیء ConferenceData حاوی جزئیات ConferenceError ، شرایط خطا را مدیریت کند تا تقویم بتواند بر اساس آن عمل کند.

هنگام ساخت یک شیء 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;
}