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

לכל פתרון כנס שהגדרתם במניפסט של פרויקט הסקריפט יש 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 בשדה 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;
}