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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

با استفاده از اطلاعات کنفرانس بازگردانده شده توسط سرویس شخص ثالث، onCreateFunction باید یک شی ConferenceData را بسازد و برگرداند. بخش داده های کنفرانس محتوای این شی را توضیح می دهد. Google Calendar از این اطلاعات استفاده می کند تا کاربران را به محض شروع به کنفرانس هدایت کند.

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

رسیدگی به خطاها

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

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