Integracja Google Asystenta z Oracle APEX i Oracle DB. Część 2

13 stycznia 2020, Dominik Grabiński

Pomimo ogromnej ilości bezpłatnej dokumentacji dostępnej na stronie Google, nie ma jednoznacznej, klarownej ścieżki, jak połączyć bota z bazą danych Oracle. Dlatego też, ten artykuł zawiera informacje techniczne oraz problemy, które napotkałem podczas tworzenia mojego Asystenta Google wraz z propozycją ich rozwiązania, a nie instrukcją na stworzenie bota, który jest identyczny jak ten zamieszczony w filmie pod koniec artykułu (to jest przykład – moja interpretacja operowaniem danymi z bazy danych Oracle).

Przygotowanie aplikacji w APEX

Na początek zaznaczę, że aplikacja w APEX musi być  otwarta, widoczna w internecie, posiadać statyczny adres IP, swój unikalny adres lub podany Dynamiczny DNS. 

Jeżeli nie chcesz tworzyć swojej aplikacji za pomocą https://apex.oracle.com, lub nie jesteś w stanie uzyskać otwartego, statycznego IP, znalazłem inne rozwiązanie. Możesz użyć otwarcie dostępnego narzędzia, jakim jest ngrok (https://ngrok.com/). Po zarejestrowaniu się w na stronie ngrok i pobraniu ich narzędzia należy wpisać w konsoli następujące polecenie:

Po uruchomieniu programu ngrok, wszystkie adresy na Twoim lokalnym środowisku zaczynające się od 127.0.0.1 zostaną przekierowane na adres ngrok.io na losowy, unikalny port. W tym momencie wszystkie adresy z lokalnego środowiska będą też miały taką postać: https://XXXXXXXX.ngrok.io, gdzie XXXXXXXX to przypadkowe litery i cyfry. Ten przekierowany adres zostanie wykorzystany później, ale jest niezbędny w czasie tworzenia swojego bota.

Kroki w APEX (App Builder) lub w bazie danych (SQL Developer)

Pamiętaj by na swojej bazie danych Oracle mieć zainstalowany Oracle Rest Data Service (ORDS). Jest on niezbędny do przesyłania danych typu POST.

Tą samą metodę POST można stworzyć na apex.oracle.com gdzie ORDS jest już zainstalowany (bez konieczności posiadania narzędzia SQL Developer).

Jeżeli potrzebujesz użyć tabeli lub widoku za pomocą serwisu REST, musisz tą opcję włączyć na danym obiekcie. W tym celu należy kliknąć prawym klawiszem myszy (PKM) na danym obiekcie i zaznaczyć opcję : Enable REST Service… > Enable object > Object alias i nadać mu dowolny alias. Upewnij się, że pole Authorization required nie jest zaznaczone, naciśnij Dalej a następnie Finish.

Należy stworzyć metodę przesyłania danych typu POST (na wzór tej przedstawionej na screenie), następnie nacisnąć PKM na stworzonej metodzie POST i kliknąć Edit… . Wejść do Parameters i dodać parametr odpowiedzi (screen). Nazwać go fulfillmentText, TAK SAMO jak jest nazwana na screenie poniżej. Nazwa jest bardzo istotna, gdyż jest ona częścią odpowiedzi typu JSON z Dialogflow).

Przejdź do zakładki SQL Worksheet – tutaj można dodać logikę związaną z obsługą informacji zawartych w bazie danych, pamiętając, że zmienna: fulfillmentText zawiera odpowiedź, której asystent użyje na zadane przez Ciebie pytanie (dane, które będą pobierane z bazy).

Wskazówka #1:

W SQL Worksheet omawianym powyżej, znajduje się ukryta zmienna :body. Jest to odpowiedź, jaką uzyskamy od asystenta w postaci JSON. Jeżeli chcesz zobaczyć, co „zwraca” odpowiedź od bota, wystarczy stworzyć nową tabelę o takiej strukturze: json_table (json_body CLOB, creation_date DATE) a następnie wpisać takie polecenie uzupełniające tą tabelę:

Teraz można podejrzeć, co kryje się w zmiennej :body mając odpowiedź typu JSON w zmiennej v_response_json którą można sparsować (za pomocą apex_json.parse(v_response_json)) i otrzymać z niej użyteczne informacje takie jak: 

Wskazówka #2:

Chcąc uzyskać wartość z parametru, który w nazwie posiada myślnik (‘-’), należy ją wpisać w cudzysłów:

Wskazówka #3:

Można również dodać jako typ (MIME Type) do metody POST: application/json tak jak na screenie poniżej:

Poniżej jest fragment kodu (z zakładki SQL Worksheet), ułatwiający pobranie z bazy danych interesują nas informację:

Przygotowanie rozmowy z chatbotem w Dialogflow i opublikowania go za pomocą narzędzia Actions on Google 

Przejdź na stronę  https://console.actions.google.com, zaloguj się swoimi danymi do logowania z google, naciśnij Add/import project, wpisz nazwę dla nowego projektu i naciśnij CREATE PROJECT:

Wybierz szablon Conversational template (prawy dół):

Wskazówka #4:

Po stworzeniu projektu, utwórz jeszcze jeden (z dowolną nazwą i o dowolnym szablonie). Jest to konieczne ponieważ są problemy z przetestowaniem chatbota, posiadając tylko jeden projekt.

 

Następnie przejdź na: https://console.dialogflow.com i naciśnij przycisk CREATE AGENT:

Wpisz nazwę Agenta (np. APEX), zostaw standardowe opcje wybrane przez google, naciśnij przycisk CREATE. Powinieneś zostać przekierowany na tą stronę:

Wybierz zakładkę Intents (lewe menu) i przejdź do Default Welcome Intent, naciśnij na Events i dodaj opcję Google Assistant Welcome (teraz już chatbot będzie w stanie odpowiedzieć na każdym urządzeniu wspierającym Google Assistant takich jak Google Home, każdym telefonie z  iOS 10.0+ lub Androidem 6.0+).

Przejdź do Responses, usuń wszystkie standardowe, przygotowane przez Google odpowiedzi i wpisz coś swojego, unikalnego jak: “Dzień Dobry Słoneczko!” (teraz testując bota, będziesz wiedział już przy przywitaniu, że rozmawiasz z tym przygotowanym właśnie przez Ciebie), naciśnij SAVE.

Przyszedł czas na przygotowanie własnego zdarzenia, na które będzie bot reagował. Przejdź do Intents, naciśnij CREATE INTENT i wpisz nazwę w polu Intent name np. number a następnie naciśnij na Training phrases:

Dodaj kilka własnych zdań/zwrotów jak ‘tell me 7’ lub ‘give me three’ (im więcej podobnych, z tej samej kategorii zwrotów wpiszesz, tym lepiej). Jak zauważyłeś, liczby zostały podświetlone. Dzieje się tak, ponieważ Dialogflow wykrył liczby jako wbudowaną encję. Naciśnij MANAGE PARAMETERS AND ACTION:

Teraz w regionie Action and parameters, wyrażenie ‘@sys.number’ jest podkreślone na ten sam kolor co wyżej opisana encja. Można odznaczyć ten parametr jako REQUIRED i dodać PROMPT (jest to pytanie, jakie zada asystent zwracając się o podanie tej zmiennej), zostaw REQUIRED jako niezaznaczone, pomiń ‘Responses’ przejdź do regionu ‘Fulfillment’ i naciśnij ENABLE FULFILMENT:

W Fulfillment włącz opcję Enable webhook call for this intent i naciśnij SAVE.

Encja to typ obiektu, na którym możemy wywoływać określone akcje/reakcje chatbota. Przykładowo, jeżeli chcemy dodać nową encję z rodzajami jedzenia, ubraniami, zadaniami matematycznymi, wystarczy przejść do zakładki Entities, nacisnąć CREATE ENTITY, dodać kilka słów z synonimami (opcja wł/wył Define synonyms). Możesz też uzyskać (jako zmienną) każde słowo dodane w Training phrases z poprzedniej zakładki Intents (w Entities opcja wł/wył Allow automated expansion). W tym opisie, nie ma potrzeby stworzenia dodatkowej encji:

Przyszedł czas na połączenie asystenta z bazą danych. Potrzebny jest adres z protokołem https:// (nie http:// !) użyty z metodą przesyłu danych typu POST. Adres możesz znaleźć w dwóch miejscach:

  • W SQL Developer, przejdź do POST method, prawy klawisz myszy > Edit… > Details, oraz na zakładce Examples jest podany adres do tej metody:

Wskazówka #5:

Używając programu ngrok.exe opisanego w “Przygotowanie aplikacji w APEX”, należy zamienić część adresu: http://localhost:8080 na https://XXXXXXXX.ngrok.io

Zatem cały adres URI powinien wyglądać tak: https://XXXXXXXX.ngrok.io/ords/hr/emps/id, gdzie znaki X będą zastąpione Twoim unikalnym ngrok ID.

  • w APEX (apex.oracle.com) po zalogowaniu przejdź do SQL Workshop > RESTful Services > znajdź przygotowaną wcześniej metodę przesyłu danych typu POST. Skopiuj z niej cały adres URL.

Posiadając skopiowany adres, wracamy do Dialogflow i wybieramy zakładkę  Fulfillment > ENABLE Webhook option i go wklejamy (pamiętając by był to https, NIE http), naciskamy SAVE (prawy dół).

Teraz chatbot, zapytany o każdą encje z zaznaczoną opcją Enable webhook call for this intent oraz nie posiadająca standardowej odpowiedzi (zadanej w encji) odpowie danymi z połączonej bazy danych (opisanych w rozdziale “Kroki w APEX (App Builder) lub w bazie danych (SQL Developer)”).

Na tym etapie możesz przetestować chatbota na 2 sposoby:

  • w Dialogflow (prawa góra) jest udostępnione okno chatu z etykietą: Try it now. Napisz ‘hi’, dostając odpowiedź ‘Dzień Dobry Słoneczko!’, wiesz, że bot działa poprawnie.

  • jeżeli chcesz zrobić więcej testów naciśnij na link:

Zostaniesz przekierowany na stronę: Actions on Google, przejdź do zakładki Test (lewe menu), naciśnij Simulator,następnie naciśnij na szary przycisk Talk to my test app. Napisz ‘hi’, jeżeli znów dostaniesz odpowiedź ‘Dzień Dobry Słoneczko!’ bot działa poprawnie. Teraz zapytajmy o coś z bazy danych, napisz  ‘tell me nine’, jeżeli dostaniesz odpowiedź: ‘From database: 9’ wszystko działa poprawnie!

Wskazówka #6:

Jeżeli masz problem z odpowiedzią z bazy danych, sprawdź cały adres URL lub SQL Worksheet w SQL Developer (opisany w rozdziale “Kroki w APEX (App Builder) lub w bazie danych (SQL Developer)”).

 

Jeżeli chcesz użyć swojego bota na jakimkolwiek urządzeniu posiadającym Google Asystenta, musisz go wypuścić (Release) zgodnie ze standardami Google. Na stronie Actions on Google, przejdź do Overview i krok po kroku wypełnij wszystkie wymagania (jak nazwa chatbota bądź politykę prywatności dla niego). Na tym etapie nie istnieje uniwersalne rozwiązanie, każdy bot jest rozpatrywany przez Google osobno.

Po zatwierdzeniu, dostaniesz informację (za pomocą e-maila oraz na stronie Actions on Google):

Ostatni krok to dodanie okna z asystentem do aplikacji w APEX. Przejdź do Dialogflow, naciśnij Integrations i włącz opcję Web Demo.

Naciśnij na Web Demo i skopiuj kod <iframe> do statycznego szablonu jako treść (Static Content) w APEX:

Po poprawnym dopuszczeniu do użytku przez Google Twojego Google Asystenta, możesz cieszyć się rozmową chociażby na swoim telefonie komórkowym:

lub w aplikacji APEX:

A tak wygląda przykładowa rozmowa z działającym Asystentem Google połączonym z bazą danych:

Podsumowanie

Mam nadzieję, że dzięki temu opisowi udało Ci się stworzyć własnego bota Asystenta Google. To może być twój pierwszy, może być twój 20, ale ten jest szczególnie wyjątkowy, ponieważ jest zintegrowany z bazą danych Oracle. Dziękuje za przeczytanie tego artykułu.

Przydatne linki i materiały:

https://console.dialogflow.com

https://console.actions.google.com

https://apex.oracle.com/pls/apex

https://ngrok.com

Tagi: , , , , , ,

Zapraszamy do kontaktu!

Pretius jest firmą tworząca oprogramowanie wspierające biznes.
Tworzymy aplikacje webowe wykorzystując: Java, Oracle DB, Oracle Apex, AngularJS.
Skontaktuj się z nami, aby porozmawiać o tym jak możemy pomóc w realizacji Twojego projektu!