Erstellen einer Text-to-Speech-Anwendung mit Hanami

In diesem Tutorial wird gezeigt, wie man mit Hanami, dem Vonage Ruby SDK und der Voice API eine Text-to-Speech Sprachanwendung erstellt. Für dieses Tutorial muss eine Vonage-Anwendung mit Voice-Funktionen erstellt werden.

Sie können den Code und die vollständig funktionierende Anwendung, die in diesem Tutorial gezeigt wird, auch auf GitHub.

Voraussetzungen

• Vonage Voice-Anwendung

• Vonage bereitgestellte Rufnummer

• Ruby und Hanami auf Ihrem Rechner installiert

• Ngrok

Was ist Hanami?

Hanami ist ein voll funktionsfähiges Ruby-Web-Framework. Es bietet eine Alternative zu Ruby on Rails, die leichter ist und weniger Speicher verbraucht. Es basiert auf der gleichen MVC-Methodik (Models, Views und Controllers) wie Rails. Einer der Hauptunterschiede im Design besteht darin, dass die Funktionalität auf den kleinstmöglichen Teil heruntergebrochen wird. Daher hat eine Hanami-Webanwendung vielleicht mehr Dateien, um die gleiche Aufgabe wie eine Rails-Webanwendung zu erfüllen, aber jede Datei ist für so wenig wie möglich verantwortlich. Das macht die Fehlerverfolgung, das Hinzufügen von Funktionen und das Refactoring effizienter.

Es ist nicht ungewöhnlich, umfangreiche Modelle und Controller in einer Ruby on Rails-Anwendung zu finden. Oft wird ein großer Teil dieses Codes in einen Servicebereich oder Hilfsklassen umstrukturiert. In einer Hanami-Anwendung ist es jedoch aufgrund des Gesamtdesigns ziemlich schwierig, ein einzelnes Modell oder einen einzelnen Controller mit so viel Code zu füllen, dass er unhandlich wird.

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

In diesem Lernprogramm wird auch eine virtuelle Telefonnummer verwendet. Um eine zu erwerben, gehen Sie zu Rufnummern > Rufnummern kaufen und suchen Sie nach einer Nummer, die Ihren Anforderungen entspricht.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Erstellen einer Vonage Voice-Applikation

Um eine Webanwendung zu erstellen, die die Vonage Voice API nutzt, müssen wir eine Vonage Voice Application im Dashboard erstellen. Navigieren Sie zu Ihre Applications aus dem Menü in der Seitennavigation. Erstellen Sie eine neue Anwendung mit einem beliebigen Namen und wählen Sie dann "Öffentlichen und privaten Schlüssel generieren". Daraufhin wird die private.key Datei auf Ihren Computer herunter. Sobald wir mit der Erstellung unserer Hanami-Anwendung beginnen, verschieben wir diese Datei in den Stammordner.

Stellen Sie sicher, dass Sie die Funktion "Voice" unter Fähigkeiten aktivieren, wenn Sie die Anwendung erstellen. Sobald Sie fertig sind, klicken Sie auf Speichern. Wenn Sie vergessen haben, auf Speichernklicken, bleiben die Informationen zum öffentlichen und privaten Schlüssel in der Vonage-Anwendung nicht erhalten, und Sie müssen ein neues öffentliches und privates Schlüsselpaar erstellen.

Voice Applications in Vonage erfordern die Bereitstellung von extern zugänglichen Webhook-Adressen für Daten aus der Vonage Voice API. In diesem Tutorial werden wir nichts mit diesen Daten machen. Dennoch ist es in Produktionsumgebungen eine gute Praxis, wenn man mit Webhooks arbeitet, zumindest die von der API gesendeten Informationen zu bestätigen. Sie können ngrok verwenden, um Ihre lokale Entwicklungsumgebung von außen zugänglich zu machen, wenn Sie eine Anwendung erstellen oder daran arbeiten. Wenn Sie ngrok noch nie benutzt haben, können Sie diesem Tutorium folgen, um zu erfahren, wie Sie es einrichten und in Ihrer Vonage-Anwendung verwenden können.

Nachdem Sie die Voice Anwendung im Dashboard erstellt haben, erhalten Sie eine Anwendungs-ID. Diese wird in unserer Anwendung wichtig sein, also notieren Sie sie sich.

Jetzt, da wir eine Vonage Voice-Anwendung und eine virtuelle Vonage-Nummer haben, können wir unsere Anwendung erstellen!

Erstellen einer Hanami-App

Der erste Schritt in unserer neuen Anwendung besteht darin, sie zu initialisieren. Führen Sie in der Befehlszeile aus:

Dadurch wird ein neues Verzeichnis namens voice_app von wo aus wir diesen Befehl mit dem Gerüst einer Webanwendung mit PostgreSQL als Datenbank ausgeführt haben. Wechseln Sie nun in dieses Verzeichnis und öffnen Sie es mit Ihrem bevorzugten Code-Editor.

Jetzt können wir mit dem Schreiben des Codes für unsere Text-to-Speech-Anwendung beginnen.

Installieren Sie das Vonage Ruby SDK

Die erste Aufgabe besteht darin, das Vonage Ruby SDK als Gem-Abhängigkeit zur Datei Gemfile.

Öffnen Sie das Gemfile aus dem Stammordner und fügen Sie gem 'vonage' hinzu. Sobald Sie dies getan haben, können Sie bundle install von der Befehlszeile aus starten.

Um einen authentifizierten Vonage SDK-Client zu instanziieren, der in der Lage ist, Sprachanrufe zu tätigen, müssen wir einige Vonage API-Anmeldeinformationen bereitstellen. Die private.key Datei, die Sie vom Vonage Dashboard heruntergeladen haben, kann nun in den Stammordner Ihrer Hanami-App verschoben werden. Wir müssen auch unsere Vonage-Anwendungs-ID angeben und wir werden diesen Moment auch nutzen, um unsere Vonage-Telefonnummer hinzuzufügen. Falls noch keine vorhanden ist, erstellen Sie eine .env Datei im Stammordner an, oder öffnen Sie die aktuelle Datei und fügen Sie Folgendes hinzu:

VONAGE_APPLICATION_ID=Your Vonage Application ID Goes Here
VONAGE_PRIVATE_KEY=./private.key
VONAGE_NUMBER=Your Vonage Number Goes Here

Sie müssen den Text nach jedem Gleichheitszeichen durch den gewünschten Wert ersetzen. Sie können den Wert für das Feld VONAGE_PRIVATE_KEY beibehalten, da dieser genau auf Ihre private Schlüsseldatei verweist.

Vorbereiten der Datenbank

An dieser Stelle werden wir unsere Datenbank für die Anwendung vorbereiten. Wir werden die Datenbank verwenden, um eine Liste von Sprachoptionen für unsere Text-to-Speech-Anwendung zu speichern. Die Benutzer können eine beliebige Sprache aus der Datenbank auswählen, um eine Nachricht zu erstellen, die sie über einen Telefonanruf versenden.

Wir werden ein neues Modell erstellen, das die Informationen für unsere Sprachen enthält. In Hanami wird die Logik für ein Datenbankmodell in einem entitygespeichert, und die Daten werden in einem repository. Ein entity ist von der Datenbank entkoppelt, während die repository die Datenebene selbst ist.

Um unser Sprachmodell zu erstellen, können wir wieder den Hanami-Generator verwenden, indem wir bundle exec hanami generate model language.

Dadurch wird eine neue Entität in lib/voice_app/entities namens language.rbund ein neues Repository in lib/voice_app/repositories namens language_repository.rb und eine neue Datenbankmigration in db/migrations. Die Migrationsdatei beginnt mit einem Zeitstempel und endet mit create_languages.rb. Der Generator erstellt auch einige spezifische Dateien für uns.

Wir müssen die Migrationsdatei öffnen und sie so bearbeiten, dass sie Spalten für den Sprachnamen und die Sprache enthält IETF BCP-47 Code-Bezeichnung.

So sieht die Migrationsdatei aus, wenn Sie sie zunächst öffnen:

Hanami::Model.migration do
  change do
    create_table :languages do
      primary_key :id

      column :created_at, DateTime, null: false
      column :updated_at, DateTime, null: false
    end
  end
end

Nach der Zeile primary_key :id Zeile fügen Sie den Code hinzu, um zwei neue Datenspalten zu erstellen:

column :name, String, null: false
column :code, String, null: false

Sie können die Datei speichern und dann den folgenden Befehl ausführen, um unsere Datenbank mit der von uns hinzugefügten Sprachtabelle und ihren Spalten zu erstellen:

Zum Schluss fügen wir noch einige Sprachen zu unserer Datenbank hinzu. Der schnellste Weg, dies zu tun, ist, vom Terminal aus in die Hanami-Konsole zu gehen und ein paar Sprachen hinzuzufügen. Sie können aus der Liste der verfügbaren Sprachen auf dem Vonage API Developer Portal wählen oder die Sprachen aus dem Beispielcode unten verwenden. Um die Konsole zu öffnen, führen Sie zunächst bundle exec hanami console in der Befehlszeile aus. Führen Sie dann den folgenden Code aus, um die Daten zu erstellen. Verwenden Sie dabei entweder die Beispielsprachen aus dem unten stehenden Codeschnipsel oder ändern Sie sie aus den von Ihnen gewählten Sprachen ab:

>> repository = LanguageRepository.new
>> repository.create(language: 'English', code: 'en-US')
>> repository.create(language: 'Danish', code: 'da-DK')
>> repository.create(language: 'Tamil', code: 'ta-IN')
>> exit

Wir haben nun eine Datenbank mit Sprachen in unserer neuen Anwendung erstellt und sind bereit für den nächsten Schritt, die Erstellung der Ansichten.

Erstellen Sie die Web-Aktionen

In diesem Tutorial werden wir Aktionen erstellen, die auf dem home Ordner, mit dem Hanami ausgeliefert wird, um unseren Code unkompliziert zu halten. So werden wir für unsere erste Aktion, die unserem Stammverzeichnis entspricht / Pfad entspricht, werden wir den Hanami Generator von der Kommandozeile aus verwenden, um eine index Aktion zu erstellen. Dies wird einen Controller für die index View und die HTML-Vorlage dafür innerhalb von app/web/templates/home/index.html.erb.

Außerdem fügt dieser Generator automatisch eine Route für uns in app/web/config/routes.rb: get '/', to: 'home#index'.

Wir führen das Folgende aus, um die oben genannten Daten zu erstellen: bundle exec hanami generate action web home#index.

Wir werden diesen Moment nutzen, um die anderen Aktionen zu erzeugen, die wir für unsere Anwendung benötigen. Kurz gesagt, wir benötigen Folgendes:

• new: Die POST Aktion für das Formular, das die Benutzer mit ihren Telefondaten übermitteln

• create: Die Aktion zum Erstellen eines neuen Text-to-Speech-Aufrufs mit den Formulardaten

• success: Die Aktion, die die Ansicht nach der Initialisierung des Aufrufs anzeigt

Um diese zu erstellen, führen Sie die folgenden Schritte aus. Der Übersichtlichkeit halber wird jede Zeile in eine separate Zeile aufgeteilt:

Jede der oben genannten Generatoraktionen hat ihre eigene Ordnerstruktur für Controller und Vorlagen erstellt, genau wie die erste index Aktion.

Erstellen Sie die Ansichten

Wir werden HTML für zwei Ansichten für unsere Anwendung hinzufügen. Die erste Ansicht ist die Stammansicht index Ansicht und die zweite wird die success Ansicht nach der Formularübermittlung.

Öffnen Sie die /apps/web/templates/home/index.html.erb Datei und fügen Sie Folgendes hinzu:

<h1>Text-to-Speech Calls on Hanami</h1>

<p>Let's make a phone call!</p>

<form action="/create" method="post">
  <label for="number">Enter a recipient number:</label>
  <input type="text" id="number" name="number">
  <br />
  <label for="language">Choose a language:</label>
  <select id="language" name="language">
    <% languages.each do |voice| %>
      <option value=<%= language.code %>><%= language.name %></option>
    <% end %>
  </select>
  <br />
  <label for="message">Enter a message:</label>
  <textarea id="message" name="message" col="10">
  </textarea>
  <br />
  <input type="submit" value="Submit">
</form>

Die Ansicht index Ansicht enthält ein kleines HTML-Formular mit drei Eingaben und einer Schaltfläche "Senden". Die erste Eingabe ist die Nummer, die der Benutzer wählen möchte. Die zweite Eingabe ist die Auswahl der Sprache. Die dritte Eingabe schließlich ist die Nachricht, die mit dem Anruf übermittelt werden soll.

Die Dropdown-Auswahl der Sprache in der zweiten Eingabe wird aus den Sprachen in unserem Sprachen-Repository generiert. Sie werden jedoch feststellen, dass der Zugriff auf diese Sprachen über eine lokale Variable voices in der Ansicht zugegriffen wird. Woher kommt diese Variable? Wir werden diese Variable in unserem nächsten Schritt dieses Tutorials zugänglich machen.

Fügen wir nun die success Ansicht. Öffnen Sie /apps/web/templates/home/success.html.erb und fügen Sie das Folgende hinzu:

<p>Congrats, you sent your message!</p>
<br />
<p>Care to <a href="/">try again?</a>

Diese Ansicht enthält eine Glückwunschnachricht zum Abschluss des Anrufs und eine Aufforderung, es erneut zu versuchen.

Fügen wir die Logik zu unseren Controllern hinzu, damit die voices lokale Variable in der Ansicht zu verwenden und den Telefonanruf durchzuführen.

Controller-Logik definieren

Wie bereits im vorherigen Schritt erwähnt, müssen wir den Kontext der Variablen in der index Ansicht angeben. Andernfalls wird sie von unserer Anwendung als undefiniert angesehen. Wir tun dies, indem wir eine Instanzvariablendefinition in der index Controller innerhalb von apps/web/controllers/home/index.rb. Es sind zwei Schritte erforderlich. Zuerst müssen wir die Daten dem Controller zur Verfügung stellen. Hanami geht nicht davon aus, dass jeder Controller Zugriff auf jeden Datenspeicher benötigt, daher muss man sich Gedanken darüber machen, auf welche Daten ein Controller zugreifen kann. Zweitens, müssen wir eine Variable in der #call Methode mit den Daten instanziieren.

So sieht der index Controller aussieht:

module Web
  module Controllers
    module Home
      class Index
        include Web::Action

        def call(params)
        end
      end
    end
  end
end

Nach der include Web::Action Zeile fügen Sie eine weitere Zeile mit expose :languages. Damit wird die Datenbanktabelle languages für unseren Controller verfügbar gemacht. Dann, innerhalb der #call Aktion das Folgende ein: @languages = LanguageRepository.new.all um alle Sprachen des Repositorys an die index Ansicht zu übergeben.

Lassen Sie uns nun fortfahren und das Vonage Ruby SDK in den Controller einbinden. create Controller ein. Wir instanziieren eine Instanz des SDK mit Anmeldeinformationen und verwenden es, um den Telefonanruf mit dem Text des Benutzers zu generieren, der im Anruf über Text-to-Speech gesendet wird. Sie können Folgendes zu Ihrer apps/web/controllers/home/create.rb Datei hinzufügen:

require 'vonage'

module Web
  module Controllers
    module Home
      class Create
        include Web::Action

        def call(params)
          client = Vonage::Client.new(
            application_id: ENV['VONAGE_APPLICATION_ID'],
            private_key: ENV['VONAGE_PRIVATE_KEY']
          )

          response = client.voice.create(
            to: [{
              type: 'phone',
              number: params[:number]
            }],
            from: {
              type: 'phone',
              number: ENV['VONAGE_NUMBER']
            },
            ncco: [{
              action: 'talk',
              text: params[:message],
              language: params[:language]
            }]
          )

          redirect_to '/success'
        end
      end
    end
  end
end

In der ersten Zeile des Codeschnipsels wird require das Vonage Ruby SDK. Dann, innerhalb der #call Methode erstellen wir unseren Client und verwenden dann die SDK voice#create Instanzmethode des SDK, um den Anruf zu senden. Die voice#create Methode folgt der API-Spezifikation für die Voice API bei den erforderlichen und optionalen Parametern, die sie akzeptiert. Die Methode benötigt mindestens folgende Parameter:

• to Parameter: Ein Array, das einen Hash mit type und number Schlüssel

• from Parameter: Ein Hash mit zwei Schlüsseln von type und number

• ncco Parameter: Ein Array mit einem Hash, das die an die Voice API gesendeten Anweisungen enthält.

Die API-Spezifikationals auch die NCCO-Referenzsind gute Ausgangspunkte, um alle möglichen Werte zu entdecken, die beim Aufbau Ihres Voice-Anrufs verwendet werden können.

Ausführen der Anwendung

Sie sind nun bereit, Ihre Anwendung zu starten! Um Ihre Hanami-Webanwendung zu starten, führen Sie den folgenden Befehl in Ihrem Terminal aus:

Mit dem obigen Befehl wird ein Webserver an Port 2300 gestartet. Sie können nun Ihren Webbrowser verwenden, um zu navigieren http://localhost:2300. Sie sehen das Formular, das Sie erstellt haben, um Text-to-Speech über einen Telefonanruf zu senden. Füllen Sie es aus, vielleicht mit Ihrer Telefonnummer als Empfängernummer. Sobald Sie auf "Absenden" klicken, sollten Sie den Anruf mit Ihrer Nachricht erhalten, und Ihr Browser sollte zur success Ansicht.

Herzlichen Glückwunsch! Sie haben eine voll funktionsfähige Sprachanwendung erstellt, die die Text-to-Speech-Funktion der Vonage Voice API mit Hanami nutzt.

Was kommt als Nächstes?

Nachdem Sie nun begonnen haben, mit den Möglichkeiten der Vonage Voice API zu experimentieren, gibt es noch so viel mehr zu entdecken. Die folgenden Ressourcen sind ein guter Ausgangspunkt, um Ihre Reise fortzusetzen:

• Interaktive Voice-Antwort

• Anruf-Bots / Voice-Assistenten

• Verwendung von WebSockets

• Erkennung von Sprache

• Erstellen von Voicemail mit Ruby on Rails