Diese Seite wurde von der Cloud Translation API übersetzt.

Konferenzen mit Drittanbietern erstellen

Jede Konferenzlösung, die Sie im Manifest Ihres Skriptprojekts definiert haben, ist mit einer onCreateFunction verknüpft. Das Add-on ruft diese Funktion auf, um immer dann eine Konferenz zu erstellen, wenn ein Nutzer versucht, diese Konferenzlösung als Ereignis auszuwählen.

Sie müssen jede onCreateFunction implementieren, die in Ihrem Add-on-Manifest beschrieben wird. Im Allgemeinen müssen diese Funktionen Folgendes tun:

Rufen Sie alle Termininformationen aus Google Kalender ab, z. B. die Termin-ID oder die Teilnehmerliste, die das Drittanbietersystem möglicherweise benötigt, um die Konferenz zu erstellen.
Stellen Sie eine Verbindung zum Konferenzdienst des Drittanbieters her und erstellen Sie dort mithilfe der Google Kalender-Termininformationen eine neue Konferenz.
Wenn die Anfrage zum Erstellen der Konferenz aus irgendeinem Grund fehlgeschlagen ist, verwenden Sie die Fehlerinformationen, um ein ConferenceData-Objekt mit einem ConferenceError zu erstellen und zurückzugeben. Führen Sie andernfalls die nächsten Schritte aus.
1. Initialisieren Sie die Konferenzsynchronisierung.
2. Verwenden Sie die vom Videokonferenzdienst des Drittanbieters zurückgegebenen Informationen, um ein neues ConferenceData-Objekt zu erstellen und zurückzugeben.

Termininformationen abrufen

Für die Erstellung einer Drittanbieter-Konferenz werden bestimmte Informationen zum entsprechenden Google Kalender-Termin benötigt. Die genauen erforderlichen Veranstaltungsinformationen variieren je nach Drittanbieter-Konferenzsystemen. Oft gehören dazu jedoch die Startzeit des Ereignisses, die Endzeit, die Zusammenfassung, die Teilnehmerliste und die ID.

Beim Aufruf wird jeder definierten onCreateFunction ein Argument übergeben, das die Kalender- und Ereignis-ID enthält. Sie können diese IDs verwenden, um mit dem erweiterten Dienst von Google Kalender die vollständigen Termininformationen abzurufen.

In Google Kalender können einem Termin bereits Konferenzdetails hinzugefügt werden, bevor er vorhanden ist. In solchen Fällen übergibt Google Kalender dem onCreateFunction einen gültigen eventId. Nachfolgende Aufrufe von Calendar.Events.get() können jedoch zu einer Fehlerantwort führen, die besagt, dass der Termin nicht vorhanden ist. In diesen Fällen empfiehlt es sich, die Drittanbieterkonferenz mit Platzhalterdaten zu erstellen. Diese Daten werden bei der nächsten Synchronisierung des Termins ersetzt.

Drittanbieter-Konferenz 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 erfolgt dies über API-Anfragen, die vom Drittanbietersystem unterstützt werden. Lesen Sie in der Dokumentation zu Ihrer Drittanbieterlösung für Videokonferenzen nach, welche API-Anfragen Sie zum Erstellen von Konferenzen verwenden können.

In Apps Script lassen sich externe API-Anfragen am einfachsten mit den Open-Source-Bibliotheken OAuth2 für Apps Script oder OAuth1 für Apps Script stellen. Sie können auch mithilfe des UrlFetch-Diensts eine Verbindung zu externen APIs herstellen. Dazu müssen Sie jedoch die Autorisierungsdetails explizit verarbeiten.

Nachdem Sie die Erstellung der Konferenz angefordert haben, müssen Sie möglicherweise zusätzliche Anfragen zum Abrufen der neuen Konferenzdetails stellen.

Konferenzsynchronisierung initialisieren

Nachdem das Add-on eine Konferenz auf einem Drittanbietersystem erstellt hat, sollten Sie einige Schritte ausführen, um die Synchronisierung zu aktivieren und Änderungen am Google Kalender-Termin in der Konferenz widerzuspiegeln.

Weitere Informationen zum Einrichten der Synchronisierung nach dem Erstellen der Konferenz finden Sie unter Änderungen im Kalender synchronisieren.

Antwort auf Konferenzdaten erstellen

Anhand der vom Drittanbieterdienst zurückgegebenen Konferenzinformationen muss onCreateFunction dann ein ConferenceData-Objekt erstellen und zurückgeben. Im Abschnitt Konferenzdaten wird der Inhalt dieses Objekts beschrieben. Google Kalender verwendet diese Informationen, um Nutzer zur Konferenz weiterzuleiten, sobald diese begonnen hat.

Beachten Sie beim Erstellen eines ConferenceData-Objekts, dass es einige Einschränkungen in Bezug auf Feldlängen, Formate von Einstiegspunkt-URIs und die zulässigen Kombinationen von Einstiegspunkten gibt. Beispielsweise darf es höchstens einen VIDEO-Einstiegspunkt in einer einzelnen ConferenceData geben. Diese Einschränkungen sind identisch mit den Einschränkungen, die im Calendar API-Ereignis für das entsprechende Feld conferenceData beschrieben sind. Allerdings sind nicht alle hier beschriebenen API-Ereignisfelder in Apps Script verfügbar.

Fehlerbehebung

In einigen Fällen kann die Konferenz aufgrund eines Fehlers, der vom Drittanbietersystem zurückgegeben wurde, nicht erstellt werden. In diesen Fällen sollte das Add-on mit der Fehlerbedingung umgehen und ein ConferenceData-Objekt erstellen und zurückgeben, das ConferenceError-Details enthält, damit Google Kalender entsprechend reagieren kann.

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

Beispiel

Das folgende Beispiel zeigt ein onCreateFunction-Beispiel. Beachten Sie, dass der Name der Funktion beliebig sein kann. Sie müssen ihn nur im Add-on-Projektmanifest definieren.

Die Funktion create3rdPartyConference() kontaktiert das Drittanbietersystem, um dort die Konferenz zu erstellen, und die Funktion getAuthenticationUrl() erstellt eine URL zur Systemauthentifizierung des Drittanbietersystems. Diese wurden hier nicht vollständig implementiert, da sie in hohem Maße von den Systemdetails des Drittanbieters abhängen.

Die Funktion initializeSyncing() wird hier nicht angezeigt. Sie übernimmt alle vorbereitenden Arbeiten, 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;
}