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

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