Mỗi giải pháp hội nghị truyền hình
mà bạn đã xác định trong dự án tập lệnh của mình
tệp kê khai
có một onCreateFunction
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,
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:
- 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 có để tạo hội nghị truyền hình.
- 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 tại đó bằng thông tin sự kiện trên Lịch Google.
- Nếu yêu cầu tạo hội nghị truyền hình không thành công vì lý do nào đó, hãy sử dụng lỗi
để tạo và trả về một
ConferenceData
đối tượng có chứaConferenceError
. Nếu không, hãy hoàn tất các bước tiếp theo.- Chạy quá trình đồng bộ hoá hội nghị truyền hình.
- Sử dụng thông tin mà dịch vụ hội nghị truyền hình của bên thứ ba trả về để
tạo và trả về một
ConferenceData
.
Truy xuất thông tin sự kiện
Để tạo hội nghị của bên thứ ba, một số thông tin nhất định về Cần có sự kiện trên Lịch Google. Thông tin chính xác cần thiết về sự kiện sẽ khác nhau giữa các hệ thống hội nghị truyền hình bên thứ ba, nhưng thường thì bao gồm thời gian bắt đầu sự kiện, thời gian kết thúc, bản tóm tắt, danh sách người tham dự và mã nhận dạng.
Khi được gọi, mỗi onCreateFunction
bạn xác định sẽ được truyền một đối số
chứa lịch và mã sự kiện. Bạn có thể sử dụng các ID này để truy xuất
toàn bộ thông tin sự kiện bằng cách sử dụ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ị truyền hình vào một sự kiện trước
nó tồn tại. Trong những trường hợp như vậy, Lịch Google chuyển onCreateFunction
một
eventId
, nhưng các lệnh gọi tiếp theo tới Calendar.Events.get()
có thể dẫn đến
cho biết sự kiện không tồn tại. Trong những trường hợp này, tốt nhất bạn nên
tạo hội nghị của bên thứ ba bằng dữ liệu giữ chỗ; dữ liệu này sẽ bị thay thế
lần tới khi sự kiện diễn ra
đồ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, mã này 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ị truyền hình đó.
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 được hỗ trợ
hệ thống hội nghị truyền hình của bên thứ ba. Hãy xem tài liệu về bên thứ ba
hội nghị truyền hình để xác định những yêu cầu API mà bạn có thể dùng để tạo
hội nghị truyền hình.
Trong Apps Script, cách dễ nhất để xử lý việc tạo các yêu cầu API bên ngoài là bằng cách sử dụng OAuth2 cho Apps Script hoặc OAuth1 cho Apps Script thư viện nguồn mở. 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 điều này yêu cầu bạn xử lý chi tiết ủy quyền một cách rõ ràng.
Sau khi yêu cầu tạo hội nghị, bạn có thể phải tạo thêm để truy xuất thông tin chi tiết về hội nghị truyền hình mới.
Khởi chạy quá trình đồng bộ hoá hội nghị
Sau khi tiện ích bổ sung đã tạo thành công một hội nghị trên hệ thống của bên thứ ba, bạn sẽ cần thực hiện vài bước để bật đồng bộ hoá để thay đổi thành sự kiện trên Lịch Google sẽ được phản ánh trong hội nghị truyền hình.
Xem Đồng bộ hóa các thay đổi 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ị truyền hình.
Xây dựng phản hồi cho dữ liệu hội nghị truyền hình
Sử dụng thông tin hội nghị do dịch vụ bên thứ ba trả về,
thì onCreateFunction
phải tạo và trả về một
ConferenceData
object; thời gian
Dữ liệu của hội nghị
mô tả nội dung của đối tượng này. Lịch Google sử dụng chế độ này
sử dụng thông tin này để chuyển hướng người dùng đến hội nghị truyền hình sau khi hội nghị bắt đầu.
Khi tạo ConferenceData
cần lưu ý rằng có một số giới hạn về độ dài trường, định dạng
URI điểm truy cập và các tổ hợp điểm truy cập được phép. Ví dụ:
có thể có tối đa một điểm truy cập VIDEO
trong một
ConferenceData
Các hạn chế này giống với các hạn chế đã mô tả
trong Sự kiện API Lịch để
Trường conferenceData
, mặc dù không phải tất cả các trường sự kiện API được mô tả ở đó
có trong Apps Script.
Xử lý lỗi
Trong một số trường hợp, bạn không thể hoàn tất quá trình tạo hội nghị vì
lỗi do hệ thống hội nghị truyền hình của bên thứ ba trả về. Trong những trường hợp này
tiện ích bổ sung của bạn phải xử lý mạnh mẽ điều kiện lỗi bằng cách tạo và
trả về một
ConferenceData
đối tượng chứa
ConferenceError
chi tiết để Lịch Google có thể hành động phù hợp.
Khi tạo đối tượng ConferenceData
để báo cáo lỗi, bạn không được
cần 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 có vấn đề 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
(xin lưu ý rằng tên của
hàm có thể là bất kỳ nội dung nào; bạn chỉ cần xác định mã này trong dự án tiện ích bổ sung của mình
tệp kê khai).
Hàm create3rdPartyConference()
liên hệ với hệ thống của bên thứ ba
để tạo hội nghị truyền hình ở đó và hàm getAuthenticationUrl()
tạo một URL xác thực hệ thống của bên thứ ba. Các lượt chuyển đổi này sẽ không được triển khai
hoàn toàn ở đây, vì chúng phụ thuộc rất lớn 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ệ thống này xử lý mọi bước sơ bộ
công việc cần thiết để đồng bộ hoá.
Xem phần Đồng bộ hoá các thay đổi về 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; }