Jede Konferenzlösung, die Sie im Manifest Ihres Script-Projekts definiert haben, ist mit einer onCreateFunction
verknüpft. Das Add-on ruft diese Funktion auf, um eine Konferenz zu erstellen, wenn ein Nutzer versucht, diese Konferenzlösung für einen Termin auszuwählen.
Sie müssen alle onCreateFunction
implementieren, die in Ihrem Add-on-Manifest beschrieben sind.
Im Allgemeinen müssen diese Funktionen Folgendes tun:
- Alle Google Kalender-Termininformationen abrufen, z. B. die Termin-ID oder die Teilnehmerliste, die das Konferenzsystem des Drittanbieters zum Erstellen der Konferenz benötigt.
- Stellen Sie eine Verbindung zum Konferenzdienst des Drittanbieters her und erstellen Sie dort eine neue Konferenz mit den Informationen aus dem Google Kalender-Termin.
- Wenn die Anfrage zum Erstellen einer Konferenz aus irgendeinem Grund fehlgeschlagen ist, verwende die Fehlerinformationen, um ein
ConferenceData
-Objekt mit einemConferenceError
zu erstellen und zurückzugeben. Andernfalls führen Sie die folgenden Schritte aus.- Synchronisierung der Konferenz initialisieren
- Verwenden Sie die vom Konferenzdienst des Drittanbieters zurückgegebenen Informationen, um ein neues
ConferenceData
-Objekt zu erstellen und zurückzugeben.
Ereignisinformationen abrufen
Zum Erstellen einer Drittanbieterkonferenz sind bestimmte Informationen zum entsprechenden Google Kalender-Termin erforderlich. Die genauen erforderlichen Ereignisinformationen variieren je nach Konferenzsystem des Drittanbieters. Häufig sind dies jedoch die Start- und Endzeit, die Zusammenfassung, die Teilnehmerliste und die ID.
Bei jedem Aufruf wird an die von Ihnen definierte onCreateFunction
ein Argument übergeben, das die Kalender- und Ereignis-IDs enthält. Mit diesen IDs können Sie die vollständigen Termininformationen mit dem erweiterten Google Kalender-Dienst abrufen.
Es ist möglich, dass Google Kalender einem Termin Konferenzdetails hinzufügt, bevor er existiert. In solchen Fällen gibt Google Kalender der onCreateFunction
eine gültige eventId
weiter. Nachfolgende Aufrufe von Calendar.Events.get()
können jedoch zu einer Fehlermeldung führen, dass das Ereignis nicht existiert. In diesen Fällen sollten Sie die Konferenz des Drittanbieters mit Platzhalterdaten erstellen. Diese Daten werden bei der nächsten Synchronisierung des Ereignisses ersetzt.
Drittanbieterkonferenz erstellen
Sobald onCreateFunction
die erforderlichen Ereignisdaten abgerufen hat, muss eine Verbindung zum Konferenzsystem des Drittanbieters hergestellt werden, um die Konferenz zu erstellen.
In der Regel geschieht dies über API-Anfragen, die vom Konferenzsystem des Drittanbieters unterstützt werden. Lesen Sie in der Dokumentation Ihrer Konferenzlösung eines Drittanbieters nach, welche API-Anfragen Sie zum Erstellen von Konferenzen verwenden können.
In Apps Script können Sie externe API-Anfragen am einfachsten mit den Open-Source-Bibliotheken OAuth2 for Apps Script oder OAuth1 for Apps Script stellen. Sie können auch über den UrlFetch-Dienst eine Verbindung zu externen APIs herstellen. In diesem Fall müssen Sie die Autorisierungsdetails jedoch explizit verarbeiten.
Nachdem Sie die Erstellung der Konferenz angefordert haben, müssen Sie möglicherweise weitere Anfragen stellen, um die neuen Konferenzdetails abzurufen.
Konferenzsynchronisierung initialisieren
Nachdem das Add-on eine Konferenz in einem Drittanbietersystem erstellt hat, sollten Sie die Synchronisierung aktivieren, damit Änderungen am Google Kalender-Termin in der Konferenz übernommen werden.
Weitere Informationen zum Einrichten der Synchronisierung nach dem Erstellen der Konferenz finden Sie unter Kalenderänderungen synchronisieren.
Antwort auf Konferenzdaten erstellen
Anhand der vom Drittanbieterdienst zurückgegebenen Konferenzinformationen muss onCreateFunction
dann ein ConferenceData
-Objekt erstellen und zurückgeben. Der Abschnitt Konferenzdaten beschreibt den Inhalt dieses Objekts. Google Kalender verwendet diese Informationen, um Nutzer zur Konferenz weiterzuleiten, sobald sie beginnt.
Beim Erstellen eines ConferenceData
-Objekts sind die Feldlängen, die Formate von Einstiegspunkt-URIs und die zulässigen Kombinationen von Einstiegspunkten eingeschränkt. Beispiel: In einer einzelnen ConferenceData
kann es maximal einen VIDEO
-Einstiegspunkt geben. Diese Einschränkungen stimmen mit den Einschränkungen überein, die im Abschnitt Calendar API-Ereignis für das entsprechende conferenceData
-Feld beschrieben sind. Allerdings sind nicht alle dort beschriebenen API-Ereignisfelder in Apps Script verfügbar.
Fehlerbehebung
In einigen Fällen kann die Konferenz nicht erstellt werden, weil das Konferenzsystem eines Drittanbieters einen Fehler zurückgibt. In diesen Fällen sollte Ihr Add-on den Fehler robust verarbeiten, indem es ein ConferenceData
-Objekt mit ConferenceError
-Details erstellt und zurückgibt, damit Google Kalender entsprechend reagieren kann.
Wenn Sie ein ConferenceData
-Objekt zum Melden eines Fehlers erstellen, müssen Sie neben dem ConferenceError
-Objekt keine weiteren ConferenceData
-Komponenten angeben. ConferenceErrors
kann eine ConferenceErrorType
, eine Fehlermeldung und bei Authentifizierungsproblemen eine URL enthalten, über die sich Nutzer im Konferenzsystem des Drittanbieters anmelden können.
Beispiel
Im Folgenden sehen Sie ein Beispiel für eine onCreateFunction
. Der Name der Funktion kann beliebig sein. Sie müssen ihn nur im Manifest Ihres Add-on-Projekts definieren.
Die Funktion create3rdPartyConference()
kontaktiert das Drittanbietersystem, um die Konferenz dort zu erstellen, und die Funktion getAuthenticationUrl()
erstellt eine URL für die Authentifizierung des Drittanbietersystems. Diese werden hier nicht vollständig implementiert, da sie stark von den Systemdetails des Drittanbieters abhängen.
Die Funktion initializeSyncing()
wird hier nicht angezeigt. Sie übernimmt alle Vorarbeiten, die für die Synchronisierung erforderlich sind.
Weitere Informationen finden Sie unter Kalenderänderungen synchronisieren.
/** * 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; }