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

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

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

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

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

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

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

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

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

כשבונים אובייקט ConferenceData, חשוב לזכור שיש מגבלות על אורכי השדות, על הפורמטים של מזהי URI של נקודות הכניסה ועל השילובים המותרים של נקודות כניסה. לדוגמה, יכולה להיות לכל היותר נקודת כניסה אחת של VIDEO ב-ConferenceData. המגבלות האלה זהות למגבלות שמתוארות בקטע אירוע ב-API של יומן Google בשדה 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;
}