יצירת כנסים של צד שלישי

ל

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

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

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

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

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