Praxiswissen: Micronaut Integration mit Zoom (API-Aufrufe)
Der Beitrag Praxiswissen: Micronaut Integration mit Zoom (Authentifizierung) hat die Authentifizierungs-Mechanismen für Zoom vorgestellt und damit die Grundlage zur Nutzung der Zoom API geschaffen. In diesem Artikel werden einige zentrale API-Aufrufe vorgestellt, um Events und ihre Teilnehmer zu verwalten.
Ausgangs-Szenario
Das Ausgangs-Szenario ist eine zentrale, unabhängige Plattform in einem Unternehmen für die Verwaltung von Events. Über diese Plattform werden neben Präsenz-Veranstaltungen ebenfalls Online-Events organisiert. Eines der genutzten Werkzeuge zur Durchführung der Online-Events ist Zoom.
Zoom unterscheidet zwischen den beiden Event-Typen Meetings und Webinare. Webinare bieten mehr Möglichkeiten, wie bspw. die Durchführung von wiederkehrenden Terminen. Da die Schnittstellen für beide Typen ähnlich sind, werden in den vorgestellten Szenarien nur Meetings betrachtet.
Folgende Use Cases werden durch die zentrale Plattform abgebildet:
- Anlegen und Aktualisieren von Meetings
- Registrieren von Teilnehmern
- Abrufen von Teilnehmerdaten nach der Durchführung eines Meetings
Anlegen und Aktualisieren von Meetings
Die zentrale Plattform speichert sämtliche Stammdaten der Veranstaltungen, wie Titel, Beschreibung, Beginn oder Dauer, in einer Datenbank. Außerdem wird für jede Veranstaltung der Typ festgelegt. Die verfügbaren Typen sind bspw. Zoom, SpotMe oder Präsenz und dienen der weiteren Steuerung.
In unserem Fall wird der Typ "Zoom" gesetzt und dieser löst nach dem Speichern die Registrierung bei Zoom über einen Hintergrundjob aus.
Mit Micronaut gestaltet sich Umsetzung eines REST-Aufrufs sehr einfach. Die nachfolgende Methode legt ein neues Meeting an.
EventZoomResult createEvent(String accessToken, String uriPath, String userId, EventZoomCmd eventZoom) {
String uri = UriTemplate.of("/users/${userId}/${uriPath}")
HttpRequest request = POST(uri, eventZoom)
request.bearerAuth(accessToken)
EventZoomResult result = httpClientApi.toBlocking().retrieve(request, Argument.of(EventZoomResult))
return result
}Die Klasse EventZoomCmd enthält die in der Zoom Api vorgegebenen JSON-Attribute. Der für die Kommunikation mit HTTP zur Verfügung stehende Client von Micronaut kann einfach über eine Annotation deklariert werden.
In unserem Fall wird die Zoom-URL als Variable deklariert und aus der Konfigurationsdatei gelesen:
ZoomClient(@Client(value = '${zoom.baseurl-api}') RxHttpClient httpClientApi {
this.httpClientApi = httpClientApi
}Neben den Eckdaten können für ein Meeting zahlreiche Eigenschaften definiert werden. Hierzu zählt beispielsweise, ob die Teilnehmer beim Betreten des Meetings automatisch stumm geschaltet sind oder ob eine E-Mail bei erfolgreicher Registrierung verschickt wird.
Es ist nicht notwendig über die zentrale Plattform sämtliche Eigenschaften pflegbar zu machen. Es ist zweckmäßiger, im Zuge der Einheitlichkeit mit dem Fachbereich Standardeinstellungen festzulegen und diese dann über die API mitzugeben. Sollte dennoch für einzelne Meetings eine Spezialbehandlung notwendig sein, so können über die Zoom Administrationsoberfläche direkt die Einstellungen angepasst werden.
Zoom gibt nach dem Anlegen alle Attribute des Meetings zurück. In unserem Fall ist hierbei die ID wichtig, da diese von der Middleware gespeichert wird und für das Durchführen von Aktualisierungen benötigt wird. Aktualisierungen erfolgen nach dem gleichen Prinzip wie das Erstellen eines Meetings.
Registrieren von Teilnehmern
Teilnehmer müssen vor einer Anmeldung zu einem Zoom Meeting als Benutzer auf der Middleware mit ihren Stammdaten hinterlegt sein. Für die Anmeldung über die Zoom API werden die gespeicherte Meeting-ID sowie die Benutzer-Stammdaten an die Zoom API übergeben. Der fachliche Schlüssel für den Teilnehmer ist die E-Mail-Adresse. Werden an die Zoom API für ein Meeting zwei Requests mit der gleichen E-Mail-Adresse gesendet, dann werden beim zweiten Request lediglich die Daten aktualisiert, es wird aber kein zweiter Teilnehmer angelegt.
Bei einer erfolgreichen Registrierung wird die von der API zurückgebene eindeutige Teilnahme-URL (join_url) auf der zentralen Plattform gespeichert. Diese URL wird dem Benutzer dann bspw. auf der Webseite des Events angezeigt, bei dessen Aufruf sich Zoom für die Teilnahme am Event öffnet.
Abrufen von Teilnehmerdaten
Für die Veranstalter sind Teilnehmer-Statistiken aus vielerlei Hinsicht interessant.
Daraus lassen sich weitere Maßnahmen, wie Werbung oder Meeting-Erinnerungen, für zukünftige Events ableiten. Außerdem können die Statistiken für anwesende Teilnehmer bspw. genutzt werden, um Bonuspunkte für Fortbildungen zu sammeln oder Zertifizierungen auszustellen.
Mit der Reports API stellt Zoom die erwähnten Funktionalitäten zur Verfügung. Nach Veranstaltungsende werden für eine Veranstaltung sämtliche Teilnehmerdaten für ein Meeting abgerufen. In der Middleware wird für jeden Teilnehmer seine Einwahldauer gespeichert.
Das nachfolgende Beispiel zeigt wie einfach REST-Aufrufe mit Micronaut und in diesem Fall groovy in wenigen Zeilen Code umgesetzt werden können:
String uri = UriTemplate.of("/report/${uriPath}/${id}/participants?page_size=300")
HttpRequest request = GET(uri)
request.bearerAuth(accessToken)
ParticipantsReportResult result = httpClientApi.toBlocking().retrieve(request, Argument.of(ParticipantsReportResult))Es ist wichtig zu wissen, dass die Zoom API sämtliche Requests in die drei Kategorien "Light", "Medium" und "Heavy" klassifiziert. Diese Klassifizierung wird von Zoom für die Drosselung der Anfragen genutzt. Zoom beschränkt die Anzahl an zulässigen Anfragen pro Sekunde abhängig vom Account und der jeweiligen Kategorie.
Anfragen für Reports sind mit "Heavy" klassifiziert, da im Hintergrund entsprechende Berechnungen notwendig sind. Aus diesem Grund werden diese Anfragen in unserem Fall auch nur einmal am Tag ausgeführt. Hier erfolgt ein Aufruf nur, wenn eine Veranstaltung beendet ist und noch keine Daten abgerufen wurden.
Zusammenfassung
Die Zoom API verfügt über eine exzellente Dokumentation, so dass diese für Entwickler ohne weitere Quellen nutzbar ist.
Vor der Integration einer Online-Schnittstelle wie Zoom ist es wichtig mit dem Fachbereich abzustimmen, welche Attribute über die zentrale Plattform nutzbar sind. Bei der Integration von mehreren Online-Systemen bleibt es nicht aus, dass es Konflikte zwischen den einzelnen Attributen gibt und es sind entsprechende Mapping-Regeln zu definieren. Manche Systeme haben evtuell nur einen Titel und andere Systeme einen Titel und eine Beschreibung, so dass in diesen Fällen ein Abgleich notwendig ist.