יצירת שיחות ועידה של צד שלישי

הערה: הפונקציונליות הזו נוצרה במיוחד לספקי שיחות ועידה, והיא הייתה זמינה במקור כתוספים לשיחות ועידה ביומן.

לכל פתרון לניהול שיחות ועידה שהגדרתם במניפסט של פרויקט הסקריפט יש onCreateFunction משויך. התוסף קורא לפונקציה הזו כדי ליצור שיחת ועידה בכל פעם שמשתמש מנסה לבחור את הפתרון הזה לשיחות ועידה לאירוע.

אתם צריכים להטמיע כל onCreateFunction שמתואר במניפסט של התוסף. באופן כללי, הפונקציות האלה צריכות לבצע את הפעולות הבאות:

1. לאחזר פרטי אירועים ביומן Google, כמו מזהה האירוע או רשימת המשתתפים, שנדרשים למערכת שיחות הוועידה של צד שלישי כדי ליצור את הוועידה.
2. מתחברים לשירות הוועידות של הצד השלישי ויוצרים בו ועידה חדשה באמצעות פרטי האירוע ביומן Google.
3. אם בקשת היצירה של שיחת הוועידה נכשלה מסיבה כלשהי, צריך להשתמש בפרטי השגיאה כדי ליצור ולהחזיר אובייקט ConferenceData שמכיל ConferenceError. אם לא, מבצעים את השלבים הבאים.
   1. מאתחלים את הסנכרון של שיחות ועידה.
   2. משתמשים במידע שמוחזר משירות הוועידות של הצד השלישי כדי ליצור ולהחזיר אובייקט חדש של ConferenceData.

אחזור פרטי האירוע

כדי ליצור שיחת ועידה מצד שלישי, צריך מידע מסוים על האירוע התואם ביומן Google. המידע המדויק שנדרש לגבי האירוע משתנה ממערכת אחת לשיחות ועידה של צד שלישי למערכת אחרת, אבל לרוב הוא כולל את שעת ההתחלה, שעת הסיום, הסיכום, רשימת המשתתפים והמזהה של האירוע.

כשמפעילים את הפונקציה, כל onCreateFunction שמוגדר מועבר כארגומנט שמכיל את מזהי היומן והאירוע. אפשר להשתמש במזהים האלה כדי לאחזר את פרטי האירוע המלאים באמצעות השירות המתקדם של יומן Google.

יכול להיות שיומן Google יוסיף פרטים של שיחת ועידה לאירוע עוד לפני שהוא נוצר. במקרים כאלה, יומן Google מעביר onCreateFunction תקף eventId, אבל קריאות עוקבות אל Calendar.Events.get() עשויות להניב תגובת שגיאה שבה מצוין שהאירוע לא קיים. במקרים כאלה, הכי טוב ליצור את שיחת הוועידה של הצד השלישי באמצעות נתוני placeholder. הנתונים האלה מוחלפים בפעם הבאה שמסנכרנים את האירוע.

יצירת שיחת הוועידה של הצד השלישי

אחרי ש-onCreateFunction מאחזר את נתוני האירוע הנדרשים, הוא צריך להתחבר למערכת שיחות הוועידה של הצד השלישי כדי ליצור את הוועידה. בדרך כלל עושים את זה על ידי שליחת בקשות API שנתמכות על ידי מערכת הוועידות של צד שלישי. כדאי לעיין בתיעוד של פתרון הוועידות של הצד השלישי כדי לראות באילו בקשות API אפשר להשתמש כדי ליצור ועידות.

ב-Apps Script, הדרך הקלה ביותר לבצע בקשות חיצוניות ל-API היא באמצעות שימוש בספריות קוד פתוח של OAuth2 for Apps Script או OAuth1 for Apps Script. אפשר גם להתחבר לממשקי API חיצוניים באמצעות שירות UrlFetch, אבל במקרה הזה צריך לטפל בפרטי ההרשאה באופן מפורש.

אחרי שמבקשים ליצור את הוועידה, יכול להיות שיהיה צורך לשלוח בקשות נוספות כדי לאחזר את הפרטים החדשים של הוועידה.

הפעלת סנכרון של שיחות ועידה

אחרי שהתוסף יוצר בהצלחה ועידה במערכת של צד שלישי, צריך לבצע כמה שלבים כדי להפעיל סנכרון, כך ששינויים באירוע ביומן Google יופיעו בוועידה.

פרטים על הגדרת הסנכרון אחרי יצירת שיחת הוועידה זמינים במאמר סנכרון שינויים ביומן.

יצירת תשובה עם נתוני שיחות ועידה

באמצעות פרטי הוועידה שמוחזרים משירות הצד השלישי, onCreateFunction צריך ליצור ולהחזיר אובייקט ConferenceData. בקטע פרטי הוועידה מוסבר מה התוכן של האובייקט הזה. יומן Google משתמש במידע הזה כדי להפנות את המשתמשים לוועידה כשהיא מתחילה.

כשיוצרים אובייקט ConferenceData, חשוב לדעת שיש כמה הגבלות על אורכי השדות, על הפורמטים של מזהי ה-URI של נקודות הכניסה ועל השילובים המותרים של נקודות הכניסה. לדוגמה, יכולה להיות נקודת כניסה אחת לכל היותר VIDEO ב-ConferenceData אחד. המגבלות האלה זהות למגבלות שמתוארות ב-Calendar API Event](/workspace/calendar/v3/reference/events) בשדה conferenceData המתאים, למרות שלא כל שדות האירועים ב-API שמתוארים שם זמינים ב-Apps Script.

טיפול בשגיאות

במקרים מסוימים, אי אפשר להשלים את יצירת הוועידה בגלל שגיאה שמוחזרת ממערכת הוועידות של הצד השלישי. במקרים כאלה, התוסף צריך לטפל בשגיאה בצורה חזקה על ידי יצירה והחזרה של אובייקט 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;
}