Part 2 – Alexa Custom Skill: Azure Function

/, SharePoint, Sonstiges, Web application/Part 2 – Alexa Custom Skill: Azure Function

Part 2 – Alexa Custom Skill: Azure Function

In diesem Blogbeitrag geht es um die von Alexa gesendeten Anfragen, Anfragen an SharePoint Online sowie die Verarbeitung dieser mithilfe von C#. Der Beitrag baut auf  “Part 1 – Alexa Custom Skill: Amazon” auf.
Als Endpoint für den Skill haben wir eine Azure-Function gewählt. Für diese gibt es die Visual Studio Tools for Azure Functions. Für Visual Studio 2015 ist leider lediglich eine Preview vorhanden. In diesem Fall muss darauf geachtet werden, dass Azure .Net SDK nur in Version 2.9 installiert ist. Für Visual Studio 2017 sind die Tools for Azure Functions vollständig vorhanden und werden von Microsoft unterstützt. Nachdem wir mit beiden Varianten Probleme hatten, hat es am Ende mit der Preview für 2015 funktioniert.

Mit diesen Tools kann eine Solution im Visual Studio erstellt werden. Daraufhin muss noch eine Funktion im Azure Portal erstellt werden und anschließend eine Verbindung zum Visual Studio hergestellt werden. Initial und nach Änderungen am Code muss die Funktion in Visual Studio veröffentlicht („Publish“) werden.

Von Alexa gesendete Anfragen

Für jeden von Alexa erkannten Intent wird ein POST-Request an den angegebenen Endpoint geschickt. Dieser muss das gesendete JSON entgegennehmen und eine entsprechende Antwort schicken. Das JSON enthält neben einem session-Objekt welches u.A. die sessionId und die userId enthält, ein request-Objekt. In diesem sind Informationen über den Aufruf des Users enthalten.
Dieses request-Objekt unterscheidet sich je nach Aufruf; wir unterstützen in unserer Version nur die drei Standard Requests die in jeden Custom Skill verwendet werden: LaunchRequest, SessionEndedRequest und IntentRequest.

  • Der LaunchRequest wird verwendet, wenn der User den Skill aufruft ohne eine speziellen Intent aufzurufen. In unserem Fall wird von uns einfach eine Willkommens-Nachricht zurückgesendet.
  • Der SessionEndedRequest wird verwendet, wenn eine Session offen ist und ein Fehler auftritt oder der User nichts sagt. Er ist vor allem wichtig, wenn Daten für eine spätere Verwendung innerhalb der Session gespeichert werden. Nachdem mit diesem Request die Session beendet wird, können die Session-Relevanten Daten bei Empfangen dieses Requests gelöscht werden. Da wir keine Session-Daten speichern, erstellen wir für diesen Fall nur einen Eintrag in der Log-Datei.
  • Der IntentRequest wird aufgerufen, wenn der User den Skill mit einem bestimmten Intent aufruft oder innerhalb einer aktiven Session einen Intent aufruft. In diesem Fall enthält das request-Objekt ein Intent-Objekt: Hier sind neben dem Namen des Intents alle vom User angegebenen Slots aufgeführt.

Neben den selbst angelegten Custom-Intents gibt es auch Built-in Intents für Aktionen, die in vielen Skills gebraucht werden, wie z.B. für die Hilfe der AMAZON.HelpIntent. Neben diesem sollte auch der AMAZON.StopIntent zum Stoppen der Anwendung sowie der AMAZON.CancelIntent zum Abbrechen implementiert werden. Die letzten beiden sind in vielen Fällen als gleichwertig zu betrachten.

Helper-Klasse

Da die Azure Function „nur“ eine Funktion enthält, kann nur schlecht redundanter Code verhindert werden. Deshalb haben wir eine eigene Klasse unter der Funktion platziert. In diese Helper-Klasse haben wir Methoden gepackt, um den Code innerhalb der Funktion übersichtlicher zu halten. So sind z.B. die Anfragen an SharePoint Online hier implementiert sowie die Verarbeitung dieser Daten.

In der Funktion selber haben wir nur das von Amazon im POST-Request geschickte JSON aufbereitet und entsprechend die Methoden der Helper-Klasse aufgerufen. Da in Azure-Functions standardmäßig Newtonsoft.Json und Newtonsoft.Json.Linq enthalten sind, haben wir zur Deserialisierung Methoden verwendet, die diese bereitstellen.

Logging

Gerade beim Entwickeln, aber auch im späteren Betrieb ist es oft sinnvoll, in eine Log-Datei zu schreiben. Azure Functions bietet diese Möglichkeit von Haus aus an. Dem Funktionsaufruf wird direkt ein Logger übergeben.
Leider ist die Log-Datei nicht so einfach zu finden. Zuerst müssen die erweiterten Tools (Kudu) geöffnet werden. Dazu die Funktionen-App öffnen, anschließend Plattformfeatures und “Erweiterte Tools (Kudu)” öffnen.

Kudu wird in einem neuen Fenster geöffnet. Hier unter “Debug console” CMD oder PowerShell öffnen. Anschließend zu LogFiles → Application → Functions → Function → FunktionName navigieren. Dies kann mit Klicken oder mit CMD/PowerShell erreicht werden.

Nun kann die Datei heruntergeladen und angezeigt werden.

Kommunikation mit SharePoint Online

Um Daten aus SharePoint Online zu bekommen, werden Zugangsdaten benötigt. Diese müssen dem Web-Request per Cookie übergeben werden. In C# gibt es für die Zugangsdaten eine eigene Klasse: SharePointOnlineCredentials im Namespace Microsoft.SharePoint.Client. Einer Instanz dieser Klasse können Username (als String) und Passwort (als System.Security.SecureString) im Konstruktor übergeben werden. Die Klasse bietet dann eine Methode GetAuthenticationCookie(WebUri) welche den Cookie-Header erstellt, wobei WebUri die Uri der abzufragenden App ist. Der Cookie muss zusammen mit der Uri dem CookieContainer des HttpClientHandlers gegeben werden, welcher dem HttpClient übergeben wird. Der HttpClient führt den Web-Request aus, wobei als Antwort ein String im JSON-Format gesendet wird. Dieser enthält die angefragten Daten.

Leider bindet Azure-Functions Microsoft.SharePoint.Client nicht standardmäßig ein. Deshalb müssen die Microsoft.SharePoint.Client.dll und die Microsoft.SharePoint.Client.Runtime.dll manuell eingebunden werden. Dazu die Dateien im Ordner „bin“ einfügen. Anschließend einmal ganz oben im Code die Zeilen #r “Microsoft.SharePoint.Client.Runtime.dll” und #r “Microsoft.SharePoint.Client.dll” einfügen. Auch muss im project.json die Zeile “Microsoft.SharePoint.Client”: “15.0.0.0” unter dependencies eingebunden werden, wobei 15.0.0.0 die Versionsnummer der Microsoft.SharePoint.Client.dll ist. Eventuell müssen die dlls noch im Azureportal hochgeladen werden. Hierzu unter „Funktionen-Apps“ zu den Funktionen der App navigieren und die Funktion auswählen. Anschließend auf der rechten Seite auf „Dateien anzeigen“ gehen und auch hier die dlls im in den „bin“ Ordner einfügen. Das kann über „Hochladen“ erreicht werden.

Da natürlich nicht die Website, sondern nur bestimmte Daten aus der Liste abgerufen werden sollen, muss der Uri, damit der HttpClient die GET Abfrage ausführt, noch ein „Spezifikator“-String angehängt werden. Dieser besteht aus /_api/web/lists/getbytitle(‘ListName’)/items, wobei „ListName“ der Name der abzufragenden Liste ist. Zudem kann dieser „Spezifikator“ nach den gültigen REST-Regeln mit Paramenten versehen werden. Diese werden einmalig mit einem „?“angehängt, beginnen jeweils mit einem „$“ und werden durch ein „&“ verbunden. So kann z.B. „$select=“ gefolgt von einer kommaseparierten Aufzählung von Spaltennamen verwendet werden.

Wichtige Links

Visual Studio 2017 Tools for Azure Functions
https://blogs.msdn.microsoft.com/webdev/2016/12/01/visual-studio-tools-for-azure-functions/
JSON-Schema
https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/alexa-skills-kit-interface-reference
Built-in Intents
https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/built-in-intent-ref/standard-intents
SharePoint REST
https://dev.office.com/sharepoint/docs/sp-add-ins/get-to-know-the-sharepoint-rest-service

By | 2017-08-02T16:59:48+00:00 August 2nd, 2017|Azure, SharePoint, Sonstiges, Web application|0 Comments

About the Author:

Associate Technology Specialist

Leave a Reply

%d bloggers like this: