Konferenzen mit Drittanbietern erstellen

Jeder Konferenzlösung, die in Ihrem Scriptprojekt-Manifest definiert ist, ist ein onCreateFunction zugeordnet. Das Google Workspace-Add‑on ruft diese Funktion auf, um eine Videokonferenz zu erstellen, wenn ein Nutzer versucht, diese Konferenzlösung für einen Termin auszuwählen.

Implementieren Sie jede onCreateFunction, die in Ihrem Add-on-Manifest beschrieben ist. Diese Funktionen müssen Folgendes tun:

  1. Alle Google Kalender-Termininformationen abrufen, die das Videokonferenzsystem eines Drittanbieters zum Erstellen der Videokonferenz benötigt, z. B. die Termin-ID oder die Liste der Teilnehmer.
  2. Stellen Sie eine Verbindung zum Videokonferenzdienst eines Drittanbieters her und erstellen Sie dort eine neue Videokonferenz mit den Informationen aus dem Google Kalender-Termin.
  3. Wenn die Anfrage zum Erstellen der Videokonferenz fehlschlägt, verwenden Sie die Fehlerinformationen, um ein ConferenceData-Objekt mit einem ConferenceError zu erstellen und zurückzugeben. Andernfalls führen Sie die nächsten Schritte aus.
  4. Initialisieren Sie die Synchronisierung von Videokonferenzen.
  5. Verwenden Sie die vom Drittanbieter-Videokonferenzdienst zurückgegebenen Informationen, um ein neues ConferenceData-Objekt zu erstellen und zurückzugeben.

Termininformationen abrufen

Um eine Videokonferenz von Drittanbietern zu erstellen, sind Informationen zum entsprechenden Kalendertermin erforderlich. Die genauen Ereignisinformationen, die erforderlich sind, variieren je nach Drittanbieter-Konferenzsystem. Häufig sind jedoch die Start- und Endzeit des Ereignisses, die Zusammenfassung, die Teilnehmerliste und die ID erforderlich.

Wenn eine onCreateFunction aufgerufen wird, wird ihr ein Argument übergeben, das die Kalender- und Ereignis-IDs enthält. Mit diesen IDs können Sie die vollständigen Termininformationen über den erweiterten Kalenderdienst abrufen.

Es ist möglich, dass Google Kalender einem Termin Konferenzdetails hinzufügt, bevor er stattfindet. In solchen Fällen übergibt Calendar einen gültigen eventId an onCreateFunction, aber nachfolgende Aufrufe von Calendar.Events.get können zu einem Fehler führen, der besagt, dass das Ereignis nicht vorhanden ist. Erstellen Sie in diesen Fällen die Drittanbieterkonferenz mit Platzhalterdaten. Diese Daten werden beim nächsten Synchronisieren des Termins ersetzt.

Drittanbieterkonferenz erstellen

Nachdem onCreateFunction die erforderlichen Ereignisdaten abgerufen hat, muss es eine Verbindung zum Drittanbieter-Videokonferenzsystem herstellen, um die Videokonferenz zu erstellen. In der Regel geschieht dies durch API-Anfragen, die vom Drittanbieter-Konferenzsystem unterstützt werden. In der Dokumentation Ihrer Drittanbieterlösung für Videokonferenzen finden Sie Informationen dazu, welche API-Anfragen Sie zum Erstellen von Videokonferenzen verwenden können.

In Google Apps Script ist die einfachste Möglichkeit, externe API-Anfragen zu stellen, die Verwendung der Open-Source-Bibliotheken OAuth2 for Apps Script oder OAuth1 for Apps Script. Sie können auch über den UrlFetch-Dienst eine Verbindung zu externen APIs herstellen. Dazu müssen Sie jedoch die Autorisierungsdetails explizit verarbeiten.

Nachdem Sie die Erstellung der Videokonferenz angefordert haben, müssen Sie möglicherweise zusätzliche Anfragen stellen, um die neuen Videokonferenzdetails abzurufen.

Konferenzsynchronisierung initialisieren

Nachdem das Add-on erfolgreich eine Konferenz in einem Drittanbietersystem erstellt hat, sind einige Schritte erforderlich, um die Synchronisierung zu aktivieren. So werden Änderungen am Kalendertermin in der Konferenz übernommen.

Weitere Informationen zum Einrichten der Synchronisierung nach dem Erstellen einer Videokonferenz finden Sie unter Kalenderänderungen synchronisieren.

Antwort mit Konferenzdaten erstellen

Anhand der vom Drittanbieterdienst zurückgegebenen Konferenzinformationen muss die onCreateFunction dann ein ConferenceData-Objekt erstellen und zurückgeben. Der Inhalt dieses Objekts wird im Abschnitt Konferenzdaten beschrieben. Der Kalender verwendet diese Informationen, um Nutzer nach Beginn der Videokonferenz dorthin weiterzuleiten.

Achten Sie beim Erstellen eines ConferenceData-Objekts auf Feldlängen, Formate von Einstiegs-URIs und zulässige Kombinationen von Einstiegspunkten. Beispiel: In einem einzelnen ConferenceData kann es höchstens einen VIDEO-Einstiegspunkt geben. Diese Einschränkungen sind identisch mit den Einschränkungen, die im Calendar API-Ereignis für das entsprechende Feld conferenceData beschrieben werden. Allerdings sind nicht alle dort beschriebenen API-Ereignisfelder in Apps Script verfügbar.

Fehler verarbeiten

Beim Erstellen einer Videokonferenz können Fehler auftreten. In einigen Fällen kann die Konferenzerstellung nicht abgeschlossen werden, weil das Drittanbieter-Konferenzsystem einen Fehler zurückgibt. In diesen Fällen sollte Ihr Add-on den Fehlerzustand verarbeiten, indem es ein ConferenceData-Objekt mit ConferenceError-Details erstellt und zurückgibt, damit Calendar entsprechend reagieren kann.

Wenn Sie ein ConferenceData-Objekt erstellen, um einen Fehler zu melden, müssen Sie außer dem ConferenceError-Objekt keine ConferenceData-Komponenten angeben. ConferenceErrors kann eine ConferenceErrorType, eine Fehlermeldung und bei Authentifizierungsproblemen eine URL enthalten, über die sich Nutzer im Videokonferenzsystem des Drittanbieters anmelden können.

Ihr Add‑on muss nicht versuchen, die Konferenzsynchronisierung einzurichten, wenn der Versuch, die Konferenz zu erstellen, fehlgeschlagen ist.

Beispiel

Im folgenden Beispiel wird eine onCreateFunction-Implementierung gezeigt. 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 Videokonferenz zu erstellen, und die Funktion getAuthenticationUrl erstellt eine Authentifizierungs-URL für das Drittanbietersystem. Diese sind hier nicht vollständig implementiert.

Die Funktion initializeSyncing wird hier nicht angezeigt. Sie führt die für die Synchronisierung erforderlichen Vorarbeiten aus. 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;
}