Ankündigung des Vonage Java SDK v8.0.0

Einführung

Seit dem letzten Ankündigungsposting hat sich im Java SDK eine Menge geändert dem letzten Ankündigungsposting - über 17 Tausend Zeilen Code in der Tat! Obwohl es sich dabei größtenteils um internes Refactoring und Verbesserungen der Lebensqualität handelt, gibt es einige wichtige Änderungen, die Sie beachten sollten, da es sich um eine wichtige Version handelt. Ohne weitere Umschweife, lassen Sie uns eintauchen!

Video-API

Beginnen wir mit der großen Neuigkeit: die Vonage Video API ist nun offiziell freigegeben. Der Übergang von OpenTok zu Vonage ist schon seit einiger Zeit im Gange, daher die zahlreichen Beta-Versionen des SDK. Jetzt, da die API stabil ist, ist sie im com.vonage.client.video Paket des Java-Server-SDK.

Neue Artefakt-ID

Wenn es eine Sache gibt, die man aus diesem Artikel mitnehmen kann, dann ist es die Tatsache, dass das SDK jetzt in ein neues artifactId auf Maven Central migriert ist. Dies steht seit 2022 auf der Roadmap, wie man an den verschiedenen Beta-Releases zum neuen Standort. Die groupId ist immer noch die gleiche (com.vonage), aber die artifactId ist jetzt server-sdk anstelle von client. Diese Migration wurde in den Metadaten gekennzeichnet, so dass einige Tools und Websites auf das neue Artefakt verweisen können. Sie können diesen Hinweis sehen auf mvnrepository.com zum Beispiel.

Was ist der Grund für diese Änderung? Der Hauptgrund ist die Vermeidung von Verwechslungen mit anderen Werkzeugen zu vermeiden, die unter der com.vonage Gruppe. Da wir auch Client-seitige SDKs für die Android-Entwicklung anbieten, kann die client Benennung etwas Verwirrung stiften, da es sich in Wirklichkeit um das serverseitige SDK handelt.

Die Aktualisierung Ihrer Abhängigkeiten sollte immer noch ein unkomplizierter Prozess sein: Ersetzen Sie com.vonage:client:7.11.1 (oder die Version, die Sie gerade verwenden) durch com.vonage:server-sdk:8.0.0. Anweisungen für Ihr spezielles Build-System finden Sie auf der rechten Seite der der Maven Central-Webseite.

Wechselnde Änderungen

Als die semantische Version Nummer andeutet, gibt es in dieser Version einige abwärtskompatible Änderungen an der öffentlichen API des SDK, aber lassen Sie sich davon nicht abschrecken, denn die meisten dieser Änderungen werden Sie wahrscheinlich nicht betreffen, und falls doch, sollten sie recht einfach zu beheben sein. Das SDK unterstützt nach wie vor Java 8, und alle Paketnamen und Klassen sind immer noch dieselben. Allerdings wurden die meisten veralteten Elemente im SDK wie geplant entfernt. Zum Beispiel wurde der WAPPush SMS-Nachrichtentyp, der von der API nicht mehr unterstützt wird. Hier ist eine Liste der entfernten Elemente und ihrer Ersetzungen.

Entfernte SNS

Wie bei jedem Projekt, das eine gewisse Geschichte hat, wird es zwangsläufig Code geben, der nicht mehr verwendet oder unterstützt wird. Im Java SDK gab es einige Pakete, die aufgrund ihrer Veralterung und der Tatsache, dass sie nicht mehr verwendet werden, nicht mehr gepflegt werden. Der SNS-Client ist ein solches Beispiel (die API ist seit langem tot), das auch Abhängigkeiten von einigen XML-Dienstprogrammen hatte. Die legacyutils, sns und logging Pakete sind alle entfernt worden. Dies gilt auch für die SNS-URI-Konfiguration in HttpConfig da sie nicht verwendet wird.

Unnötige Abhängigkeiten

Eines der häufigsten Probleme bei der Verwendung einer Bibliothek sind Abhängigkeitskonflikte. Ich habe einen Artikel darüber geschrieben, wie man das lösen kanngeschrieben, aber im Allgemeinen ist es für die Betreuer von Bibliotheken ratsam, ihre Abhängigkeiten so weit wie möglich zu minimieren.

Ein solches Beispiel im SDK ist die javax.servlet Abhängigkeit. Da diese nun in den Jakarta-Namensraum verschoben wurde, macht sie die Verwendung des Java SDK mit neueren Versionen von Jakarta Servlet schwieriger. Außerdem war die Verwendung dieser Abhängigkeit ziemlich unnötig, und die Klassen, die sie verwendeten, werden nicht mehr gepflegt. Daher wurden alle Methoden und Klassen, die auf diese Abhängigkeit verwiesen - insbesondere, HttpServletRequest - entfernt worden. Dies schließt das com.vonage.client.voice.servlet Paket und com.vonage.client.sms.callback.AbstractMOServlet. Wenn Sie die Klasse RequestSigning Klasse zur Überprüfung von Signaturen eingehender Nachrichten von der SMS-API verwendet haben, können Sie jetzt die Ersatz verifySignature Methode verwenden - siehe das Code-Schnipsel-Repositorium für ein Beispiel.

Die andere Abhängigkeit, die entfernt wurde, ist jackson-dataformat-hal. Diese stellte eine Erweiterung der Jackson-Bibliothek für die Deserialisierung von HAL-Antworten zur Verfügung, die jedoch nur durch die Account-API - speziell die ListSecretsResponse Klasse. Um die Konsistenz mit dem Rest des SDK zu gewährleisten, wurde sie umstrukturiert, so dass die Abhängigkeit nicht mehr notwendig ist.

API überprüfen

Aus der Verify-API wurden unter anderem die BaseResult Klasse - die nur Statuscodes enthielt, aber im Rest des SDK nicht verwendet wurde - und LineTypedie zuvor veraltet war. Das schließt auch Methoden ein, die LineTypebenutzten, natürlich. Das ipAddress Feld wurde ebenfalls entfernt, sowohl aus AdvancedInsightRequest (in Number Insight) und CheckRequest. Das verify2 Paket wird empfohlen, anstelle von verify als die Verify v2 API mehr Unterstützung erhalten wird. Apropos, es wurden zahlreiche Gebietsschemata zu Verify v2 hinzugefügt - so viele, dass es zu einem Wartungsaufwand geworden ist, den Überblick zu behalten. Aus diesem Grund wurde die benutzerdefinierte com.vonage.client.verify2.Locale Enum entfernt worden. Stattdessen sollten Sie die eingebaute java.util.Locale. Sie können die VerificationRequest.Builder#locale(String) aus Gründen der Bequemlichkeit verwenden, indem Sie die aus zwei Buchstaben bestehenden Tags für Sprache und Region bereitstellen (zum Beispiel, en-gb).

Sprach-API

Es wurden einige Qualitätsverbesserungen an der Voice-API-Implementierung vorgenommen, darunter das Entfernen zuvor veralteter Methoden - zum Beispiel die Setter in com.vonage.client.voice.Call Klasse, zugunsten der Verwendung des Builders, der in Version 7.3.0 hinzugefügt wurde. Die beiden wichtigsten Änderungen betreffen VoiceClient.

Erstens: Die modifyCall Methode wurde zusammen mit ModifyCallResponse. Die Implementierung vereinfacht nun Aktionen zur Änderung von Anrufen durch direkte Methodenaufrufe. Um zum Beispiel einen Anruf zu beenden (aufzulegen), verwenden Sie die Methode terminateCall(String) Methode, wobei nur die Anruf-ID übergeben wird. Ähnliche Methoden gibt es auch für die anderen Aktionen (earmuff / unearmuff, mute / unmute).

Die andere Änderung betrifft die downloadRecording Methode. Diese gab ein Recording Objekt zurück, mit dem man nur zwei Dinge tun konnte: entweder den Inhalt als InputStream oder den Aufruf der save(Path) Methode aufrufen, um ihn in einer Datei zu speichern. Die interne Implementierung dieser Methode war nicht schön, daher wurde sie vereinfacht, indem zwei neue Methoden auf VoiceClient: void saveRecording(String recordingUrl, Path destination) und byte[] downloadRecordingRaw(String recordingUrl). Die erste speichert, wie der Name schon sagt, die Aufnahme von der angegebenen URL (recordingUrl) in die gewünschte Datei (destination). Letztere gibt Ihnen den binären Inhalt der Aufnahme (heruntergeladen von der URL recordingUrl) als Byte-Array, so dass Sie entscheiden können, was damit geschehen soll, wenn Sie die Aufnahme nicht in einer Datei speichern wollen. Daher wurde die vorherige Recording downloadRecording(String recordingUrl) Methode entfernt worden, zusammen mit der com.vonage.voice.client.Recording Klasse.

Schließlich hat der PayAction NCCO zusammen mit der PaymentPrompt Klasse entfernt, da diese nicht mehr von der API unterstützt werden.

Andere Aktualisierungen

Neben der Entfernung von veraltetem Code zur Beseitigung technischer Schulden gibt es auch einige neue Funktionen, die im Folgenden beschrieben werden. Falls Sie neugierig sind, die internen Refactoring-Arbeiten zur Entkopplung der API-Implementierungen vom zugrundeliegenden HTTP-Client, die in Version 7.7.0 begonnen wurden, sind nun abgeschlossen, was den Weg für künftige Aktualisierungen des Clients ebnet - zum Beispiel, um die Unterstützung asynchroner Anfragen zu ermöglichen. Auch die Tests wurden auf JUnit 5 migriert.

Konfigurierbare Anfrage-Timeouts

In Version 7.8.0 wurde die Möglichkeit hinzugefügt, ein benutzerdefiniertes Timeout für alle vom SDK gesendeten Anfragen festzulegen. Obwohl unsere REST-APIs in der Regel zeitnah antworten (gemessen in Millisekunden und nicht in Sekunden), können einige Endpunkte je nach Umfang der erforderlichen Verarbeitung und den Netzwerkbedingungen länger brauchen. Bei zeitkritischen Anwendungen kann es sinnvoll sein, eine feste Frist für Antworten festzulegen, damit Sie nicht länger als nötig warten müssen, ohne separate Threads erstellen zu müssen. Vor Version 7.8.0 war der Standard-Timeout systemabhängig, da es sich um den Standardwert des zugrunde liegenden Apache-HTTP-Clients handelte (normalerweise 60 Sekunden). Jetzt kann dies auf die nächste Millisekunde genau konfiguriert werden, indem die HttpConfig.Builder#timeoutMillis(int) Methode. Außerdem beträgt der Standardwert jetzt 60 Sekunden, unabhängig von den Systemeinstellungen.

Stille Authentifizierung

In der Verify v2 API wurden einige zusätzliche Felder für den Silent Auth Workflow hinzugefügt. Nämlich die Felder sandbox und redirect_url Parameter in SilentAuthWorkflow, check_url in VerificationResponse. Unsere Dokumentation enthält weitere Informationen über den synchronen Silent Auth-Workflow und Silent Auth Sandkasten wenn Sie neugierig sind.

AccountClient Verbesserungen

Die AccountClient Klasse im Java SDK hat Endpunkte sowohl für die Preis- als auch für die Konto-APIs. Es fehlte jedoch der Endpunkt für ausgehende Preise für alle Länder Implementierung, die seit Version 7.9.0 hinzugefügt wurde. Dieser Endpunkt - der mit der Methode AccountClient#listPriceAllCountries(ServiceType) Methode aufgerufen werden kann - ruft die Preisinformationen für alle verfügbaren Länder ab.

Außerdem wurden Überladungen von Komfortmethoden für die Verwaltung von Geheimnissen hinzugefügt. Wenn Sie nun Geheimnisse für Ihr Hauptkonto (im Gegensatz zu Unterkonten) verwalten möchten, müssen Sie den API-Schlüssel nicht mehr an die Methode übergeben - dieser wird automatisch von der Authentifizierungsmethode abgeleitet, die zur Erstellung der VonageClient.

JWT-Überprüfung

Beim Empfang von Webhooks von Vonage wird empfohlen, die Authentizität der Nutzdaten durch Validierung der Token-Signatur zu überprüfen. Bisher war dies ein manueller Prozess, aber seit v7.11.0 können Sie die verifySignature(String jwt, String secret) Helper-Methode in VoiceClient und verwenden. MessagesClient. Diese delegiert einfach an die neue Jwt.verifySignature Methode in dem com.vonage:jwt Artefakt, das aktualisiert wurde um diese Funktion zu unterstützen. Jetzt müssen Sie nicht mehr die Logik zum Extrahieren und Validieren der Signatur einer eingehenden Nutzlast mithilfe von Bibliotheken von Drittanbietern implementieren - Sie müssen lediglich das JWT und das gemeinsame Geheimnis bereitstellen. Die Methode gibt true zurück, wenn das Token mit dem angegebenen Geheimnis signiert wurde.

Abmeldung

Und das sind alle Änderungen, die Sie in Version 8.0.0 des Java SDK kennen sollten. Vergessen Sie nicht, auf die Veröffentlichungen unter den com.vonage:server-sdk Koordinaten für zukünftige Aktualisierungen! Wenn Sie auf irgendwelche Probleme stoßen oder Verbesserungsvorschläge haben, können Sie gerne einen Fehler auf GitHub zu meldenoder erreichen Sie uns auf Twitter oder schauen Sie bei unserem Gemeinschaft Slack. Ich hoffe, Sie haben viel Spaß bei der Nutzung der Vonage APIs mit der neuesten Version des Java SDK!