Teilen Sie:
){kind=small}
Sina ist Java Developer Advocate bei Vonage. Er hat einen akademischen Hintergrund und ist generell neugierig auf alles, was mit Autos, Computern, Programmierung, Technologie und der menschlichen Natur zu tun hat. In seiner Freizeit geht er gerne spazieren oder spielt Videospiele.
Ankündigung des Vonage Java SDK v9.0.0
Lesedauer: 12 Minuten
Seit dem letzten Ankündigungsposting hat sich im Java SDK eine Menge geändert dem letzten Ankündigungsposting - über 39 Tausend Zeilen Code in der Tat! Diese Hauptversion hat lange auf sich warten lassen, mit einer Menge Verbesserungen und ja, auch den unvermeidlichen Änderungen, die sich aus dem Entfernen und Refactoring ergeben. Ich freue mich, diese Aktualisierungen endlich mit Ihnen teilen zu können, denn die Qualität des SDK hat sich noch weiter verbessert, mit 100% Testabdeckung als Ergebnis - das gleiche gilt für unser Kotlin SDK!
Natürlich ist es am besten, sich mit der neuesten SDK-Version auf dem Laufenden zu halten, um sicherzustellen, dass alle Funktionen der unterstützten APIs zur Verfügung stehen, natürlich zusammen mit Fehlerbehebungen und Sicherheitsupdates. Insbesondere wurden mehrere Updates vorgenommen für Messages APImit zusätzlichen optionalen Eigenschaften für eingehende und ausgehende Nachrichten, neuen unterstützten Nachrichtentypen für MMS-, WhatsApp Reaction & Button-Nachrichten, der Möglichkeit, WhatsApp-Nachrichten als gelesen zu markieren, und natürlich der Unterstützung für RCS-Nachrichten. Bei der Video API wurde die Implementierung aktualisiert, um Live-Untertitel, Audio Connector, Experience Composer, die Nur-Publisher-Rolle in Sitzungs-Tokens, Ende-zu-Ende-Verschlüsselung, maximale Bitrate und Quantisierungsparameter für Archive sowie verschiedene Fehler- und Inkonsistenzbehebungen zu unterstützen.
Auch die Webhooks wurden überarbeitet und vereinfacht, indem sie in die entsprechenden Pakete für die jeweiligen APIs verschoben wurden. Für Voice können Sie den AntwortWebhook und EventWebhook für die Deserialisierung von Webhooks je nach Typ (da die Antwort- und Ereignis-URLs normalerweise an unterschiedliche Endpunkte gesendet werden). Für SMS API, verwenden Sie MessageEvent zum Parsen von Webhooks für eingehende Nachrichten.
Seit der letzten Hauptversion wurden drei neue unterstützte APIs hinzugefügt:
Die lang erwartete Implementierung der Conversation API wurde dem Java SDK ursprünglich in Version 8.4.0 hinzugefügt, wurde aber seitdem verbessert und unterstützt nun fast alle Ereignistypen. Diese Low-Level-API untermauert die innere Funktionsweise der Voice APIund bietet leistungsfähigere Funktionen für die Abwicklung von Multi-Channel-Anrufen und Chats mit mehreren Teilnehmern. Es handelt sich zweifellos um die größte und komplexeste im SDK unterstützte API, die fortgeschrittene / Power-User nun mit einer vollwertigen, stark typisierten Implementierung nutzen können, anstatt sich auf die REST-API-Referenz.
Die SIM-Tausch-API ist eine der Netzwerk-APIs von Vonage. Damit können Sie überprüfen, ob die zu einer Numbers gehörende SIM-Karte mit einem anderen Gerät getauscht wurde. Standardmäßig wird dies innerhalb der letzten 10 Tage geprüft, kann aber auf einen beliebigen Zeitraum innerhalb der letzten 100 Tage, auf die Stunde genau, eingestellt werden. Beachten Sie, dass dies derzeit nur für deutsche und spanische Numbers verfügbar ist (siehe Verfügbarkeit für Netzwerk-APIs). Sie können es jedoch mit unserem Spielplatz mit Virtuellen Operatoren. Obwohl der API-Aufruf ein 3-stufiger Prozess ist ist, vereinfacht das SDK dies zu einem einzigen Methodenaufruf, der all dies für Sie automatisiert.
Nicht zu verwechseln mit Number Insight, der Numbers Verification API ist eine weitere Netzwerk-API, mit der Entwickler prüfen können, ob das Gerät des Nutzers mit seiner Mobilfunknummer übereinstimmt. Dies ist bereits in den Arbeitsablauf der stillen Authentifizierung in Verify API - siehe die Codeschnipsel für ein Anwendungsbeispiel. Die Numbers Verification API ist etwas komplexer, da sie mehrere API-Aufrufe erfordert. In der ersten Phase wird eine URL erstellt, die Sie an den Benutzer weitergeben können, damit dieser sie auf seinem mit dem Netzwerk verbundenen Gerät aufrufen kann. Daraufhin wird ein Rückruf mit einem Code an Ihren Server gesendet, den Sie dann an die API weitergeben, um die Übereinstimmung von Nummer und Gerät zu überprüfen. Derzeit gelten die gleichen Einschränkungen wie für die oben beschriebene SIM-Swap-API.
Major-Releases bieten eine gute Gelegenheit, technische Schulden zu beseitigen, die im Laufe des SDK-Lebenszyklus im Zuge der Weiterentwicklung natürlich entstehen. Diese Version ist keine Ausnahme, mit einer Reihe von Verwerfungen seit der letzten Hauptversion. Diese Verwerfungen - außer VonageClient.Builder#setHttpClient - wurden alle entfernt. Die setHttpClient Methode gibt es immer noch für Kunden, die mehr maßgeschneiderte Optionen benötigen, aber viele können mit httpConfig erreicht werden, wie z. B. Proxying, Anfrage-Timeouts und das Festlegen von Basis-URIs; alle diese Optionen sind verfügbar unter HttpConfig.Builder.
Neben der Entfernung der alten APIs - Meetings und Proactive Connect - wurden in dieser Version auch die Ecken und Kanten des SDKs aufgeräumt und interne Methoden, Klassen und Konstruktoren weiter gekapselt, um die Interaktion mit dem SDK konsistenter und schlanker zu gestalten und Verwirrung zu vermeiden. In Anlehnung an das Python-Mantra:
"Es sollte einen - und vorzugsweise nur einen - offensichtlichen Weg geben, dies zu tun.
Folglich geht es bei den Änderungen in dieser Version hauptsächlich um die Beseitigung von Inkonsistenzen. Die meisten Refactorings und Änderungen werden die meisten Benutzer nicht betreffen und die, die es tun, erfordern nur minimale Refactorings. Die wichtigsten Dinge, auf die man achten sollte, sind verschobene Enums (die weiter unten näher erläutert werden), spezifischere Rückgabetypen anstelle von String, wo anwendbar, und ein paar Stellen, an denen Methoden zugunsten konsistenterer oder einfacherer Alternativen umbenannt wurden. Es ist zu hoffen, dass diese Probleme relativ einfach zu lösen sind, insbesondere mit Hilfe Ihrer IDE und den umfassenden Javadocs. das Änderungsprotokoll um einen Überblick über alle Änderungen zu erhalten, die nicht in diesem Artikel beschrieben sind. Für die meisten Verwerfungen, die entfernt wurden, wird die Alternative in der Javadoc beschrieben worden sein, so dass es einfacher sein könnte, sich zuerst auf die Beseitigung veralteter Verwendungen zu konzentrieren, bevor Sie auf v9.0.0 aktualisieren, um einen reibungsloseren Übergang zu ermöglichen.
Debugging und Nachvollziehbarkeit sind in jeder Anwendung wichtig, daher wurde dieser Aspekt in Version 8.16.0 verbessert. Angesichts der unzähligen Logging-Frameworks im Java-Ökosystem und der inzwischen berüchtigten Log4j-Schwachstelle, die vor einigen Jahren entdeckt wurde, verlässt sich das Java SDK auf die integrierte java.util.logging um Abhängigkeiten und potenzielle Kompatibilitätsprobleme weiter zu minimieren. Die Protokollierung erfolgt hauptsächlich in AbstractMethod#execute(REQ) durchgeführt wenn die Protokollierungsstufe auf FINE eingestellt ist. Die Anfrage wird protokolliert, bevor der API-Aufruf erfolgt - einschließlich des vollständigen URI, der Anfragemethode, der Abfrageparameter und des Anfragebodys. Wenn der Aufruf erfolgreich war, wird auch der Antwortkörper protokolliert, sofern vorhanden. Für eine noch feinere Protokollierung, siehe DynamicEndpoint.parseResponse.
Seit Version 7.7.0 wurde durch eine grundlegende Überarbeitung des SDK die Jsonable Schnittstelle für Anfrage- und Antwortobjekte eingeführt. Diese Objekte erweitern nun alle das JsonableBaseObject Klasse. Diese implementiert die ist gleich, hashCode, und toString Methoden, die auf den Feldern des Objekts basieren, und Sie können JSON-Nutzdaten auf der Grundlage des Datenmodells des Objekts sowohl serialisieren als auch deserialisieren, indem Sie die toJson und fromJson Methoden. Letztere ist als statische Methode auf dem Objekt Jsonable Schnittstelle implementiert.
Eine der wichtigsten Änderungen in dieser Version ist die Behandlung von Enums. Die meisten Enums wurden nun aus den inneren Klassen auf die obere Ebene verschoben, wo es Sinn macht, und einige wurden in die com.vonage.client.common Paket verschoben, wenn sie von mehreren APIs verwendet werden. Darüber hinaus wurde die Deserialisierung durchgängig standardisiert, indem man auf die Jsonable.fromString Methode. Wenn die String-Darstellung nicht mit einem bekannten Wert übereinstimmt, wird null zurückgegeben, anstatt eine IllegalArgumentException auszulösen. Dadurch kann der Rest des Objektdatenmodells befüllt werden, was ansonsten verhindert worden wäre. Aus Gründen der Konsistenz mit diesem Ansatz wird die UNKNOWN Wert in den meisten Enums entfernt, es sei denn, es handelt sich um einen literalen, gültigen Wert, der von der API zurückgegeben werden kann (wie z. B. in Number Insight der Fall).
Diese Version verbessert die in den Datenmodellobjekten verwendeten Typen und führt weitere Änderungen durch. Mehrere Rückgabetypen wurden von Strings zu Enums oder einem geeigneteren Typ wie UUID, URI, Double usw. geändert. Die Aktualisierung Ihrer Anwendung, um mit diesen Änderungen zu arbeiten, sollte hoffentlich einfach und selbsterklärend sein, wird aber ausführlicher im dem Änderungsprotokoll.
Die einschneidendsten Änderungen finden sich in der Voice API Implementierung. Jede Methode und Klasse ist nun vollständig dokumentiert, und viele der Ungereimtheiten wurden beseitigt. Alle Setter-Methoden wurden entfernt und stattdessen durch Builder ersetzt. Neben neuen Funktionen und Fehlerkorrekturen gab es eine Reihe von Änderungen an der Voice API. Zum Beispiel akzeptieren Builder jetzt nur noch eine einzige URL für Parameter wie eventUrl. Obwohl diese bei der Serialisierung als JSON in ein Array verpackt werden muss, wird dies im SDK ausgeblendet, um Verwirrung zu vermeiden. Das Gleiche gilt für Endpunkte in Aufruf von und ConnectAction - Es kann nur ein einziger Endpunkt verwendet werden, aber zuvor vermittelte das SDK den Eindruck, dass mehrere Zielendpunkte angegeben werden können, obwohl dies nur deshalb der Fall ist, weil der Endpunkt in ein JSON-Array eingeschlossen werden muss. Apropos Endpunkte, Sie sind vielleicht auf einige Verwirrung gestoßen, wenn Sie NCCOs verwenden, um einen Anruf zu verbinden, da es zwei Klassen gab: com.vonage.client.voice.Endpoint und com.vonage.client.voice.ncco.Endpoint. Die erste Klasse wird verwendet in Aufrufverwendet, während die letztere in der ConnectAction NCCO VERWENDET WIRD. Diese wurden nun umbenannt in CallEndpoint und ConnectEndpoint um Überschneidungen zu vermeiden und vollqualifizierte Klassennamen zu verlangen, so dass Sie beide importieren können. Schließlich gab es eine gewisse Standardisierung in AnrufFilter (der nun die Klasse HalFilterRequest), der Folgendes verwendet Sofort anstelle des veralteten Datum Klasse verwendet (Wortspiel beabsichtigt!), und CallInfoPage, die nun die Klasse HalPageResponse. Beachten Sie, dass die EingebetteteAufrufe Klasse entfernt wurde, so dass man auf die Liste der Aufrufe direkter mit der getCallInfos() Methode auf CallInfoPage. Schließlich wird, wie bereits erwähnt, eine stärkere Typisierung verwendet, wo dies möglich ist (z.B., Satz und Preis in CallInfo sind jetzt Doubles anstelle von Strings), und Enums wurden aus den inneren Klassen entfernt.
In v8.10.0 wird die Numbers API Implementierung nicht nur aktualisiert, um fehlende Eigenschaften hinzuzufügen, sondern auch um die Dokumentation zu verbessern. Die Setter wurden zugunsten von Buildern entfernt, um die Konsistenz mit anderen APIs zu gewährleisten. Das Verknüpfen von Numbers mit einer Applikation funktioniert nun wie vorgesehen, da die fehlende Eigenschaft dafür hinzugefügt wurde. Die NumbersClient#listNumbers Methode gibt nun eine List<OwnedNumber> direkt zurück, anstatt eine ListNumbersResponsezurück, wodurch ein zusätzlicher Methodenaufruf eingespart wird, da dieses zusätzliche Wrapping unnötig ist.
Benutzer der Number Insight API werden sich freuen zu lesen, dass die Unterstützung für asynchrone erweiterte Einsicht jetzt richtig implementiert wurde, mit den richtigen Anfrage- und Antworttypen, im Gegensatz zu der umständlichen Lösung, die in früheren Versionen ein boolesches Flag für die synchrone erweiterte Einsicht setzte. Die Rückruf Parameter ist für asynchrone Advanced Insights obligatorisch, da hier die vollständige Antwort geliefert wird, die dann in AdvancedInsightResponse geparst werden kann, indem die Jsonable.fromJson(String, Klasse) Methode geparst werden kann.
Nebenbei bemerkt, fragen Sie sich vielleicht, was mit Number Insight v2 passiert ist. Technisch gesehen war diese API in der Beta-Phase und wurde daher in dieser Version entfernt, nachdem sie in v8.2.0 hinzugefügt wurde. Die API wurde umbenannt in Betrugs-Erkennungumbenannt, aber wir haben später größere Pläne für die Betrugserkennung und -vermeidung sowie Number Insight, also bleiben Sie dran für weitere Updates.
Wenn Sie schon einmal versucht haben, mithilfe der Messages API im Java SDK Nachrichten mit mehreren Kanälen oder Medien zu erstellen, sind Sie vielleicht auf das Problem gestoßen, dass Sie jeden Kanal und jede Typkombination einzeln behandeln müssen, auch wenn der Code für jeden Fall identisch ist. Betrachten Sie zum Beispiel den Code, der zur Demonstration aller Kanal- und Nachrichtentypkombinationen in dieser SpringBoot-Anwendung. Wo liegen die Gemeinsamkeiten? Nun, alle Textnachrichten (d.h. wenn der MessageType ist TEXT) haben eine text(String) Methode für den Builder. Ähnlich verhält es sich mit allen Mediennachrichten (d.h. wenn der MessageType ist FILE, IMAGE, AUDIO, VIDEO, oder VCARD) haben eine url(String) Methode auf ihren Buildern. Es gibt zwei Möglichkeiten, um diese an einer Stelle ohne Wiederholung gesetzt werden refactored. Die hacky Workaround Weg ist über Reflexion. Eine bessere Möglichkeit wäre die Verwendung einer Schnittstelle. Genau das wurde seit Version 8.11.0 implementiert. Sie können nun die Textnachrichten-Builder auf TextMessageRequest.Builderund MediaMessageRequest für Nachrichten mit einem URL-Feld. Da einige Kanäle auch eine optionale Beschriftung Eigenschaft unterstützen, gibt es auch CaptionMediaMessageRequestdie die Eigenschaft MediaMessageRequest mit dieser Eigenschaft erweitert. Folglich kann die Anwendung einer URL, einer Beschriftung oder eines Textes nun polymorph über mehrere Kanäle hinweg erfolgen.
Bei der Entwicklung des Kotlin-SDK im letzten Jahr fiel mir auf, dass die Handhabung von Capabilities im Java-SDK in der Anwendungs-API viel zu wünschen übrig ließ, weil sie unnötig ausführlich war und von der Konstruktion her nicht korrekt war. Die Kotlin-SDK-Implementierung korrigiert dies, indem sie sicherstellt, dass die Webhook-Typen (z. B. event_url, status_url, answer_url, usw.) können nur auf Fähigkeiten angewendet werden, die sie unterstützen. Die Capability Builder im Java SDK wurden aktualisiert und sind nun konstruktionsbedingt korrekt, was bedeutet, dass die addWebhook und removeWebhook Methoden durch typspezifische Methoden ersetzt worden sind. Zum Beispiel, in der com.vonage.client.application.capabilities.Voice.Builder Klasse gibt es jetzt die Methoden Ereignis, Antwort, und fallbackAntwort. Für die Fähigkeit Messages gibt es Status und Ereignis. Jede dieser Methoden setzt die entsprechende Eigenschaft in der JSON-Nutzlast, wodurch die Builder deklarativer, weniger wortreich und konstruktionsbedingt korrekt sind. Um einen Webhook zu entfernen, können Sie einfach null als Eingabe an diese Methoden übergeben.
Da das Kotlin-SDK auf dem Java-SDK aufbaut, wurde es aktualisiert, um mit den in Version 9.0.0 eingeführten Änderungen kompatibel zu sein. Dazu gehört das Entfernen von Verwerfungen und Funktionen, die nicht mehr unterstützt werden, wie die alte Preisgestaltung APIund WhatsApp Codeless Workflow in Verify API. Das Kotlin SDK folgt Semantische Versionierung wie Sie es erwarten würden, daher die Version 2.0.0.
Ein kurzer Hinweis zur Dokumentation: Obwohl Sie die Inline-Code-Dokumentation direkt in Ihrer IDE oder über einen Javadoc-Renderer finden können (funktioniert für beide Java SDK und Kotlin SDK), und Sie können natürlich auch Codeschnipsel in unserem Entwickler-Portal für jedes Produkt finden, möchten Sie vielleicht eine übersichtliche einseitige Ansicht von Codebeispielen, die zeigen, wie die einzelnen APIs mit dem SDK verwendet werden. Ich freue mich, Ihnen mitteilen zu können, dass die Generierung einer solchen Datei jetzt sowohl für Java und KotlinSie können also nach Herzenslust Ctrl-F drücken!
Das Java-SDK (und damit auch Kotlin) unterstützt auch in dieser Hauptversion weiterhin Java 8 als minimal erforderliche Laufzeitumgebung. Es ist kaum vorstellbar, dass Java 8, das zum Zeitpunkt der Erstellung dieses Artikels vor 11 Jahren veröffentlicht wurde, im Jahr 2025 noch immer relevant ist und verwendet wird. Beliebte Frameworks sind jedoch mindestens auf Java 17 umgestiegen, und selbst die wichtigsten Build-Tools, auf die wir uns verlassen (Maven, Gradle), haben die Unterstützung für Java 8 veraltet. Darüber hinaus hat der Apache HTTP Client 4, auf dem das Java SDK basiert, seine aktive Entwicklung eingestellt. In der Zwischenzeit wurde die Unterstützung für asynchrone/reaktive Aufrufe schon lange gefordert. Um dies zu erleichtern, und vielleicht schon allein aus Sicherheitsgründen, wäre es ratsam, die Baseline auf Java 11 zu verschieben, das einen eingebauten HTTP-Client in das JDK einführte. Indem dieser anstelle einer externen Abhängigkeit genutzt wird, kann der Platzbedarf des SDK weiter reduziert werden, während die Wartungs- und Sicherheitslast des zugrunde liegenden HTTP-Clients auf die Plattform selbst verlagert wird. Daher möchte ich Sie ermutigen, von Java 8 weg zu migrieren, sowohl als allgemeine gute Praxis als auch als Vorbereitung auf die nächste Hauptversion.
Das sind alle Änderungen, die Sie über die Version 9.0.0 des Java SDK und die dazugehörige Version 2.0.0 des Kotlin SDK wissen sollten. Für eine umfassendere Zusammenfassung der Änderungen siehe CHANGELOG.md für Java und Kotlin SDKs. Wenn Sie auf Probleme stoßen oder Verbesserungsvorschläge haben, können Sie gerne eine Frage auf GitHub stellen oder schauen Sie bei unserem Gemeinschaft Slack. Ich hoffe, Sie haben viel Spaß bei der Nutzung der Vonage APIs mit der neuesten Version der Java- und Kotlin-SDKs!
Teilen Sie:
Sina ist Java Developer Advocate bei Vonage. Er hat einen akademischen Hintergrund und ist generell neugierig auf alles, was mit Autos, Computern, Programmierung, Technologie und der menschlichen Natur zu tun hat. In seiner Freizeit geht er gerne spazieren oder spielt Videospiele.