Alexa und Azure

Ich habe mir vor einiger Zeit die das Amazon Echo zugelegt. Nun da dachte ich mir, die kann ja viel mit den Homematic Geräten umgehen und mit anderen Herstellern. Da dachte ich mir, warum sollte das nicht einfach mit FHEM funktionieren.

Einfach… ja …. wie es sich rausstellte war es doch etwas komplizierter als ich dachte. Ich habe nämlich beschlossen die Azure Cloud zu verwenden, da ich dort sehr viele Applikationen mittlerweile Betreibe und auch quasi dort im Umfeld tätig bin.

Das hat die Sache etwas verkompliziert und da ich bestimmt nicht der einzige bin, habe mir gedacht, schreibe ich das hier auch einmal runter…

Grundaufbau

Ich habe folgendes Grundszenario:

Homedevices

Das Echo ist hart mit der Amazon cloud über sog. Skills verbunden, diese liegen immer in der Amazon Cloud (AWS), da ich, wie bereits eingangs beschrieben die Azure Cloud verwende musste ich somit eine Brücke zur Azure Cloud herstellen. Diese beinhaltet ein Webapp Server in der eine Web-Api (ASP.net Core Web-Api) vorhanden ist. Diese Api nimmt die Daten der Alexa entgegen und liefert diese dann nach einer kleinen Korrektur der Input Daten weiter an meinem Homeserver hinter einem normalen Speedport Router liegt. Auf dem Homeserver läuft wie üblich FHEM, welches ein Alexa Modul aktiviert hat und somit mit den Daten arbeiten kann.

Das war es schon, nun womit startet man zuerst? Im Prinzip hat man zwei Baustellen aber ich fange mit der einfachsten an.

Einrichten des Azure AD

Ich habe mir gedacht, das ich immer auf Nummer sicher gehen will, daher habe ich die API -Schnittstelle auch entsprechend mit einem AD vor unbefugten Zugriff abgesichert. Dazu bedarf es noch ein paar Konfigurationen und zwar muss ich zwei App Registrierungen vornehmen. Eine für den Custom Skill der Alexa und eine für die Webapi. Bei den nachfolgenden Schritten gehe ich davon aus das ein AD bereits in Azure existiert, dies wird bei der Anmeldung in Azure kostenlos mit erstellt.

Einrichtung der App-Registrierung für die Web-Api

Die app-Registrierung für die Web-Api wird auch als Web-api angelegt:

alexa-webapi-appregistration

Dieser Schritt kann auch in Visual Studio durchgeführt werden, denn bei einer Neuanlage einer ASP.Net Core Webapi wird gefragt, ob ein AD als Authentifizierungsanbieter eingesetzt werden soll. Dieser erledigt dann diese Schritte bei der Anlage des Visual Studio Projekts schon im Hintergrund. Jedoch habe ich mir gedacht das man diesen Schritt auch manuell machen kann.

Die Anmelde URL, kann muss aber nicht geändert werden, da wir keinen direkten Login zulassen wollen.

Dieser Schritt ist nur dazu da, um der Web-Api die Möglichkeit zu geben Benutzer durch das AD zu authentifizieren. Oder auch auf andere Angebundene Dienste zugreifen zu können.

Von hier wird die APP-ID-Uri für später in einer Textdatei weg gesichert. Diese ist unter den Eigenschaften der App Registrierung abzurufen:

App-Ident

 

Jetzt müssen wir noch einen Schlüssel generieren. Dazu einfach auf “Schlüssel” gehen und einen Namen inkl. Gültigkeitsdatum vergeben. Erst nach dem speichern wird der Zugriffs-Schlüssel nur EINMAL angezeigt. Danach nicht mehr wieder. Diesen Wert notieren wir ebenfalls.

 

Einrichtung der App Registrierung für den Alexa Skill

Die App-Registrierung für den Alexa Skill wird im Azure AD als Native App registriert.

Create-AlexaSkillApp

Die Umleitungsurl kann erst später angepasst werden, wenn der Custom Skill erstellt wurde. Nun müssen noch folgende Werte für später notiert werden:

  • AnwendungsID
    Diese befindet sich in der Informationszeile ganz oben in der App-Registrierung
    Native-AppSettings

Nun noch zwei Weitere Einstellungen die aber in der Übersicht der App-Registrierungen zu sehen sind.

Endpoints

Von dort werden nachfolgende Adressen / Endpunkte verwendet

Nun haben wir folgendes Konstrukt.

AD-Apps

Berechtigungsvergabe

Wir haben nun zwei App-Registrierungen einmal für den Alexa Skill und einmal für die Webapi. Rein Theoretisch kann jeder Dienst schon darauf zugreifen und sich Authentifizieren. Doch ein wichtiger Punkt fehlt noch, und zwar würde das AD den Apps untersagen miteinander zu kommunizieren. Da wir aber nur den Skill unsere API Aufrufen und die API nicht den Skill reicht nur die eine Richtung. Um dies zu bewerkstelligen müssen wir unsere App-Registrierung mit namen Alexa-Skill öffnen so dass wir die Berechtigung anlegen können.

AccessrightsAlexaWebapi

Wir öffnen also den Punkt “Erforderliche Berechtigungen” klicken im nächsten Panel auf “Hinzufügen” und suchen dann nach “Alexa-webApi” (wichtig, es muss danach gesucht werden, sonst wird es nicht angezeigt). Nach der Auswahl sind noch alle Haken im nachfolgenden Panel zu setzen und abzuspeichern.

Nun dürfen die beiden Dienste miteinander Reden und wir haben das Diagram von oben komplett.

Fertig?

Nuja wenn wir nur im AD Spielen wollten ja, aber es fehlt jetzt noch der Skill von Alexa und ja wir haben doch noch Umleitungs URL’s oben zu setzen. Zudem hatten wir noch Konfigurationen notiert, diese kommen nun aber zum Einsatz.

Alexa Skill

Anlage eines Skills

Zuerst einmal erstellen wir einen Skill (Ich würde jetzt nicht beschreiben wollen wir man ein Developer Account bei Amazon anlegt). Daher gehe ich sofort den Schritt weiter und wir loggen uns im Developer Portal  von Amazon Im Menüpunkt Alexa ein. Anschließend klicken wir auf “Get startet” im Alexa Skill Set.

DevAlexaNewSkill

Anschliessend auf “New Skill” oben rechts. Nun befinden wir uns schon in der Konfiguration des Skills. Wir wählen nun die Option “Custom Skill” aus.customSkill

Mit diesem sind wir in der Lage eigene Sprachmodelle und Interaktionen zu definieren. im nächsten Schritt “Interaction Model” geben wir nun dieses auch ein.

Interaction Modell definieren

“Wassn das?” würden nun viele Denken. Ich fasse es einmal kurz zusammen. Dieses Modell ist lediglich eine Art Schablone mit der die Befehle entsprechend abgegriffen und in einem Daten Jason abgelegt werden. Es ist somit eine Definition dessen wie die Daten später zum Dienst ankommen sollen.

Zuerst wird ein Schema definiert. Ich habe folgendes für einfache Zwecke definiert:

Dies definiert drei Variablen Device, Action und Command. Damit der Sprachinterpreter auch weis welches wohin gehört gibt ein Mapping. Diese Mappings sind nichts weiteres als Wortlisten und im Type angegeben in meinem Beispiel ist Device mit dem Type List_Of_ROOMS angegeben, welche dann beispielsweise “Wohnzimmer”, “Schlafzimmer” uvm. beinhaltet. Bei Command lediglich nur “ein” und “aus”. Bei Action habe ich aktuell nur “schalte” hinterlegt. Da ich aktuell nur Lichtschalter damit bedienen wollte.

Im Portal sieht das dann wie folgt aus

SlotTypes

Als nächste Eingabe kann (muss aber nicht), ein paar Beispiele eingegeben werden. Ich habe das einmal durchgeführt und dabei werden die Parameter und das Modell von oben bereits angewendet. Diese Eingabe dient lediglich nur für die Beispiel ansage die Alexa macht. So wie “Wenn sie x wollen dann sagen Sie …”.

Ich habe folgendes eingegeben

Es wird alles validiert in der Box, da ich Smarthome als bekanntes intent angegeben habe wird dies auch zugelassen. Im Anschluss dessen kommen dann die Befehle, welche im Model definiert werden. So besteht die Möglichkeit eine Art Pattern zu erstellen.

Configuration

Diese Konfiguration ist nun essentiell wichtig für die Kommunikation mit unserer Web-Api.

ConfigurationSkill

 

Zuerst müssen wir bekannt geben das wir keine Amazon Resource nehmen sondern eine HTTPS Ressource nehmen wollen. Direkt darunter geben wir den Endpunkt zu unserer API an. Darunter können wir noch Regionsspezifisch (Beispielsweise für Europe) den Endpunkt ebenfalls angeben. Ich würde Europe empfehlen, da wir sonst unseren Sprach befehl einmal um den Globus senden. Bei Accounts Linking geben wir “Yes” an.  Nun geben wir die Authorizierungs URL an. Dazu müssen wir eine URL zusammen bauen in Foglenden Format.

Ein Beispiel kann dann wie folgt aussehen

Danach kommt die Client ID, dort tragen wir die AnwendungsID von oben ein.

Nun kommen die Redirect URLs, diese werden jetzt in der app-Registrierung der Native App eingetragen. Dazu gehen wir in die App-Registrierung Alexa-Skill, dort dann auf den Reiter Weiterleitungs-URLs und tragen dort die Adressen ein.

Nun kommt noch ein Teil der Authorisierung-Einstellungen und wir haben es fast geschafft.

Auth

Wir wählen als Option “Auth-Code Grant” aus. Im nächsten Eingabefeld geben wir den Zugriffs-Schlüssel im Auswahlfeld lassen wir HTTP Basic.

Ganz wichtig für Amazon ist, das man eine Policy unten im Feld hinterlegt, das kann auf einer Leeren Seite zeigen oder auf eine von Amazon. Wichtig ist das diese Seite existiert.

SSL-Certificate

Hier ist lediglich die Option “My development endpoint is a sub-domain of a domain that has a wildcard certificate from a certificate authority” bei beiden Auswahlen anzugeben.

Das war es nun auch schon was die Technik angeht. Die Restlichen Eingaben bedarf keiner großen Erklärung.

Nachdem die Werte gespeichert wurden kann der Skill auf dem Echo installiert werden. Bei der Installation wird einmal die Authentifizierung abgefragt, hier müssen wir dann ein Login angeben mit dem wir im AD bekannt sind. Danach ist alles fertig.

 

Im nächsten Blog werde ich darauf eingehen wie man diesen Dienst mit der Heimautomation verbinden kann.