Tạo hội nghị truyền hình của bên thứ ba

Mỗi giải pháp hội nghị mà bạn xác định trong tệp kê khai dự án tập lệnh đều có một onCreateFunction được liên kết. Tiện ích bổ sung này gọi hàm này để tạo một hội nghị truyền hình bất cứ khi nào người dùng cố gắng chọn giải pháp hội nghị truyền hình đó cho một sự kiện.

Bạn phải triển khai từng onCreateFunction được mô tả trong tệp kê khai tiện ích bổ sung. Nhìn chung, các hàm này phải thực hiện những việc sau:

  1. Truy xuất mọi thông tin về sự kiện trên Lịch Google, chẳng hạn như mã sự kiện hoặc danh sách người tham dự mà hệ thống hội nghị truyền hình của bên thứ ba có thể cần để tạo hội nghị.
  2. Kết nối với dịch vụ hội nghị truyền hình của bên thứ ba và tạo một hội nghị truyền hình mới ở đó bằng thông tin sự kiện trên Lịch Google.
  3. Nếu yêu cầu tạo hội nghị truyền hình không thành công vì một lý do nào đó, hãy dùng thông tin lỗi để tạo và trả về một đối tượng ConferenceData chứa ConferenceError. Nếu không, hãy hoàn tất các bước tiếp theo.
    1. Khởi động tính năng đồng bộ hoá cuộc họp.
    2. Sử dụng thông tin do dịch vụ hội nghị truyền hình bên thứ ba trả về để tạo và trả về một đối tượng ConferenceData mới.

Truy xuất thông tin sự kiện

Để tạo một hội nghị do bên thứ ba tổ chức, bạn cần có một số thông tin về sự kiện tương ứng trên Lịch Google. Thông tin chính xác về sự kiện cần thiết sẽ khác nhau tuỳ thuộc vào hệ thống hội nghị của bên thứ ba, nhưng thường bao gồm thời gian bắt đầu, thời gian kết thúc, nội dung tóm tắt, danh sách người tham dự và mã nhận dạng của sự kiện.

Khi được gọi, mỗi onCreateFunction mà bạn xác định sẽ được truyền một đối số chứa mã nhận dạng lịch và sự kiện. Bạn có thể sử dụng các mã nhận dạng này để truy xuất thông tin đầy đủ về sự kiện bằng dịch vụ nâng cao của Lịch Google.

Lịch Google có thể thêm thông tin chi tiết về hội nghị vào một sự kiện trước khi sự kiện đó diễn ra. Trong những trường hợp như vậy, Lịch Google sẽ truyền onCreateFunction một eventId hợp lệ, nhưng các lệnh gọi tiếp theo đến Calendar.Events.get() có thể dẫn đến một phản hồi lỗi cho biết sự kiện không tồn tại. Trong những trường hợp này, bạn nên tạo hội nghị bên thứ ba bằng cách sử dụng dữ liệu giữ chỗ; dữ liệu này sẽ được thay thế vào lần tiếp theo sự kiện đồng bộ hoá.

Tạo hội nghị truyền hình của bên thứ ba

Sau khi onCreateFunction truy xuất dữ liệu sự kiện cần thiết, onCreateFunction phải kết nối với hệ thống hội nghị truyền hình của bên thứ ba để tạo hội nghị. Thông thường, việc này được thực hiện bằng cách đưa ra các yêu cầu API do hệ thống hội nghị truyền hình bên thứ ba hỗ trợ. Kiểm tra tài liệu về giải pháp hội nghị truyền hình của bên thứ ba để xác định những yêu cầu API mà bạn có thể dùng để tạo hội nghị.

Trong Apps Script, cách dễ nhất để xử lý việc đưa ra yêu cầu API bên ngoài là sử dụng thư viện nguồn mở OAuth2 cho Apps Script hoặc OAuth1 cho Apps Script. Bạn cũng có thể kết nối với các API bên ngoài bằng dịch vụ UrlFetch, nhưng bạn phải xử lý rõ ràng thông tin uỷ quyền.

Sau khi yêu cầu tạo hội nghị, bạn có thể cần đưa ra các yêu cầu bổ sung để truy xuất thông tin chi tiết về hội nghị mới.

Khởi động tính năng đồng bộ hoá hội nghị

Sau khi tạo thành công một hội nghị trên hệ thống của bên thứ ba, tiện ích bổ sung sẽ cần thực hiện một số bước để bật tính năng đồng bộ hoá để các thay đổi đối với sự kiện trên Lịch Google được phản ánh trong hội nghị.

Hãy xem phần Đồng bộ hoá các thay đổi trên Lịch để biết thông tin chi tiết về cách thiết lập tính năng đồng bộ hoá sau khi tạo hội nghị.

Xây dựng phản hồi dữ liệu hội nghị

Bằng cách sử dụng thông tin hội nghị do dịch vụ bên thứ ba trả về, onCreateFunction sau đó phải tạo và trả về một đối tượng ConferenceData; phần Dữ liệu hội nghị mô tả nội dung của đối tượng này. Lịch Google sử dụng thông tin này để chuyển người dùng đến hội nghị khi hội nghị bắt đầu.

Khi tạo một đối tượng ConferenceData, hãy lưu ý rằng có một số hạn chế về độ dài trường, định dạng của URI điểm truy cập và các tổ hợp được phép của điểm truy cập. Ví dụ: có thể có tối đa một điểm vào VIDEO trong một ConferenceData duy nhất. Những hạn chế này giống với những hạn chế được mô tả trong API Lịch Event](/workspace/calendar/v3/reference/events) cho trường conferenceData tương ứng, mặc dù không phải tất cả các trường sự kiện API được mô tả ở đó đều có trong Apps Script.

Xử lý lỗi

Trong một số trường hợp, không thể hoàn tất quá trình tạo hội nghị do hệ thống hội nghị truyền hình của bên thứ ba trả về lỗi. Trong những trường hợp này, tiện ích bổ sung của bạn phải xử lý điều kiện lỗi một cách mạnh mẽ bằng cách tạo và trả về một đối tượng ConferenceData chứa thông tin chi tiết ConferenceError, để Lịch Google có thể hành động cho phù hợp.

Khi tạo một đối tượng ConferenceData để báo cáo lỗi, bạn không cần phải thêm bất kỳ thành phần ConferenceData nào ngoài đối tượng ConferenceError. ConferenceErrors có thể có ConferenceErrorType, thông báo lỗi và trong trường hợp gặp vấn đề về xác thực, URL cho phép người dùng đăng nhập vào hệ thống hội nghị truyền hình của bên thứ ba.

Ví dụ:

Sau đây là ví dụ về onCreateFunction (lưu ý rằng tên của hàm có thể là bất kỳ tên nào; bạn chỉ cần xác định tên đó trong tệp kê khai dự án tiện ích bổ sung).

Hàm create3rdPartyConference() liên hệ với hệ thống bên thứ ba để tạo hội nghị ở đó và hàm getAuthenticationUrl() tạo URL xác thực hệ thống bên thứ ba. Các lớp này không được triển khai đầy đủ ở đây, vì chúng phụ thuộc nhiều vào thông tin chi tiết về hệ thống của bên thứ ba.

Hàm initializeSyncing() không xuất hiện ở đây; hàm này xử lý mọi công việc sơ bộ cần thiết để đồng bộ hoá. Hãy xem bài viết Đồng bộ hoá các thay đổi đối với lịch để biết thông tin chi tiết.

/**
 *  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;
}