Tworzenie akcji dla Asystenta Google za pomocą pakietu Actions SDK (poziom 1)

1. Przegląd

Ostrzeżenie: 13 czerwca 2023 r. wycofaliśmy akcje dotyczące rozmów. Więcej informacji znajdziesz w artykule Wycofanie akcji dotyczących rozmów.

Platforma dla deweloperów Asystenta Google umożliwia tworzenie oprogramowania, które rozszerza funkcjonalność Asystenta Google, wirtualnego asystenta osobistego, na ponad miliardzie urządzeń, w tym na inteligentnych głośnikach, telefonach, samochodach, telewizorach, słuchawkach i innych. Użytkownicy rozmawiają z Asystentem, aby wykonywać różne czynności, np. kupować produkty spożywcze lub zamawiać przejazdy. Jako deweloper możesz używać platformy deweloperskiej Asystenta, aby łatwo tworzyć i zarządzać atrakcyjnymi i skutecznymi interakcjami głosowymi między użytkownikami a własną usługą realizacji zamówień.

W tym ćwiczeniu znajdziesz podstawowe informacje o tworzeniu aplikacji za pomocą pakietu Actions SDK dla Asystenta Google. Aby je ukończyć, nie musisz mieć żadnego doświadczenia z tą platformą. W tym samouczku utworzysz prostą akcję dla Asystenta Google, która będzie przepowiadać użytkownikom przyszłość na początku ich przygody w mitycznej krainie Gryffinberg. W samouczku dotyczącym pakietu Actions SDK na poziomie 2 rozbudujesz tę czynność, aby dostosować wróżbę do danych wejściowych użytkownika.

Co utworzysz

W tym ćwiczeniu z programowania utworzysz prostą akcję z tymi funkcjami:

• odpowiada użytkownikom wiadomością powitalną,
• zadaje użytkownikom pytania i odpowiada na ich wybory;
• Udostępnia sugestie, które użytkownicy mogą klikać, aby wprowadzać dane
• Modyfikuje wiadomość powitalną dla użytkownika w zależności od tego, czy jest on powracającym użytkownikiem.

Po ukończeniu tego laboratorium Twój gotowy projekt będzie miał następujący przebieg rozmowy (tekst obok mikrofonu reprezentuje dane wejściowe użytkownika, a tekst obok głośnika – odpowiedź projektu):

Czego się nauczysz

• Tworzenie projektu w Konsoli Actions
• Jak używać narzędzia gactions do przesyłania projektu działania między konsolą Actions a lokalnym systemem plików
• Jak wysłać prompt do użytkownika po wywołaniu przez niego działania
• Jak przetworzyć dane wejściowe użytkownika i zwrócić odpowiedź
• Testowanie działania w Symulatorze Actions
• Jak zaimplementować realizację za pomocą edytora Cloud Functions

Czego potrzebujesz

W środowisku muszą być dostępne te narzędzia:

• wybrane środowisko IDE lub edytor tekstu;
• terminal do uruchamiania poleceń powłoki dla Node.js i npm;
• przeglądarka internetowa, np. Google Chrome;

Jeśli wolisz tworzyć działania za pomocą bardziej wizualnych narzędzi, wykonaj samouczek dotyczący tworzenia działań dla Asystenta Google za pomocą narzędzia Actions Builder (poziom 1). W tym samouczku to samo działanie jest tworzone za pomocą środowiska IDE narzędzia Actions Builder w konsoli.

2. Skonfiguruj

W sekcjach poniżej znajdziesz informacje o tym, jak skonfigurować środowisko programistyczne i utworzyć projekt działań.

Sprawdzanie ustawień uprawnień Google

Aby przetestować działanie utworzone w tym module, musisz włączyć odpowiednie uprawnienia, aby symulator mógł uzyskać do niego dostęp.

Aby włączyć uprawnienia, wykonaj te czynności:

1. Otwórz Zarządzanie aktywnością.
2. Zaloguj się na swoje konto Google.
3. Włącz te uprawnienia:

• Aktywność w internecie i aplikacjach
• W sekcji Aktywność w internecie i aplikacjach zaznacz pole Uwzględnij historię Chrome i aktywność na stronach, urządzeniach i w aplikacjach, które używają usług Google**.**

Tworzenie projektu w Actions

Projekt w Actions jest kontenerem dla Twojej akcji.

Aby utworzyć projekt działań na potrzeby tego laboratorium, wykonaj te czynności:

1. Otwórz konsolę Actions.
2. Kliknij Nowy projekt.
3. Wpisz nazwę projektu, np. actions-codelab. (Nazwa jest przeznaczona do użytku wewnętrznego. Później możesz ustawić zewnętrzną nazwę projektu).

4. Kliknij Utwórz projekt.
5. Na ekranie Jakiego rodzaju działanie chcesz utworzyć? wybierz kartę Niestandardowe.
6. Kliknij Dalej.
7. Na ekranie Jak chcesz go utworzyć? wybierz kartę Pusty projekt.
8. Kliknij Rozpocznij tworzenie.

Zapisywanie identyfikatora projektu dla działania

Identyfikator projektu to unikalny identyfikator Twojej działania. Identyfikator projektu będzie potrzebny w kilku krokach tego ćwiczenia.

Aby pobrać identyfikator projektu, wykonaj te czynności:

1. W konsoli Działania kliknij 3 kropki w pionie (wstaw ikonę).
2. Kliknij Ustawienia projektu.

3. Skopiuj identyfikator projektu**.**

Powiązywanie konta rozliczeniowego

Jeśli nie masz jeszcze konta rozliczeniowego, musisz je utworzyć i powiązać z projektem w Google Cloud, aby później wdrożyć realizację za pomocą Cloud Functions.

Aby powiązać konto rozliczeniowe z projektem, wykonaj te czynności:

1. Otwórz stronę rozliczeń Google Cloud Platform.
2. Kliknij Dodaj konto rozliczeniowe lub Utwórz konto.
3. Podaj dane karty.
4. Kliknij Rozpocznij bezpłatny okres próbny lub Prześlij i włącz płatności.
5. Otwórz stronę rozliczeń Google Cloud Platform.
6. Kliknij kartę Moje projekty.
7. Kliknij trzy kropki w sekcji Działania obok projektu Działań dla codelabu.
8. Kliknij Zmień płatności.
9. W menu wybierz skonfigurowane konto rozliczeniowe.
10. Kliknij Ustaw konto.

Aby uniknąć naliczania opłat, wykonaj czynności opisane w sekcji Zwalnianie miejsca w projekcie na końcu tego laboratorium.

Instalowanie interfejsu wiersza poleceń gactions

W tym laboratorium kodowym użyjesz narzędzia interfejsu wiersza poleceń gactions do synchronizowania projektu działań między konsolą Actions a lokalnym systemem plików.

Kluczowy termin:

• gactions CLI: narzędzie, które umożliwia inicjowanie plików projektu akcji, przesyłanie aktualizacji do Konsoli Actions, wdrażanie projektów akcji i nie tylko.

Aby zainstalować gactions CLI, postępuj zgodnie z instrukcjami w artykule Instalowanie narzędzia wiersza poleceń gactions.

Pobieranie projektu w Actions

Zacznij tworzyć akcję, pobierając projekt Actions z konsoli Actions.

Aby pobrać projekt działań, wykonaj te czynności:

1. Aby utworzyć nowy katalog i przejść do niego, uruchom te polecenia:

mkdir myproject
cd myproject

2. Aby skopiować konfigurację projektu Actions do lokalnego systemu plików, uruchom to polecenie:

gactions pull --project-id <projectID>

Poznaj strukturę pliku

Projekt działań pobrany z konsoli Actions jest reprezentowany w strukturze plików YAML. Obraz poniżej przedstawia ogólną strukturę pliku:

Struktura pliku składa się z tych elementów:

• actions/: reprezentuje Twój projekt działań. System wywołuje actions.yaml, gdy wywoływane jest działanie, które następnie wywołuje plik custom/global/actions.intent.MAIN.yaml.
• custom/: katalog, w którym będziesz pracować, aby zmodyfikować działanie.
• global/: ten katalog zawiera intencje systemowe, które platforma automatycznie dodaje do Twojego projektu. Więcej informacji o intencjach systemowych znajdziesz w dalszej części tego ćwiczenia z programowania.
• manifest.yaml: plik zawierający informacje, które można przenosić między projektami.
• settings/: reprezentuje ustawienia projektu w Actions, takie jak wyświetlana nazwa, domyślny język i kategoria.

3. Rozpoczynanie rozmowy

Użytkownicy rozpoczynają rozmowę z Twoją akcją za pomocą wywołania. Jeśli na przykład masz działanie o nazwie MovieTime, użytkownicy mogą je wywołać, mówiąc na przykład „OK Google, porozmawiaj z MovieTime”, gdzie MovieTime to nazwa wyświetlana. Jeśli chcesz wdrożyć akcję w środowisku produkcyjnym, musi ona mieć wyświetlaną nazwę. Aby jednak przetestować akcję, nie musisz definiować wyświetlanej nazwy. Zamiast tego możesz użyć w symulatorze wyrażenia „Porozmawiaj z aplikacją testową”, aby wywołać akcję. Więcej informacji o symulatorze znajdziesz w dalszej części tej sekcji.

Musisz edytować główne wywołanie, aby określić, co się stanie po wywołaniu działania przez użytkownika.

Kluczowy termin:

• Główne wywołanie: punkt wejścia, w którym użytkownicy mogą rozpocząć rozmowę z Twoją akcją. Gdy użytkownicy wypowiadają frazę podobną do „OK Google, porozmawiaj z <nazwa wyświetlana>”, następuje główne wywołanie, a usługa odpowiada użytkownikowi.

Domyślnie Twoja akcja zawiera ogólny prompt, który jest wyświetlany po wywołaniu („Zacznij tworzyć akcję od zdefiniowania głównego wywołania”).

Kluczowy termin:

• Prompt: określa, co Twoja akcja wysyła użytkownikom w odpowiedzi. Prompty mogą być prostymi odpowiedziami tekstowymi i głosowymi lub rozbudowanymi wiadomościami, takimi jak karty i obrazy.

Możesz użyć specjalnego promptu Canvas, aby wyświetlać użytkownikowi wizualizacje na pełnym ekranie. Więcej informacji o Canvas znajdziesz w dokumentacji Interactive Canvas.

W następnej sekcji dostosujesz prompt dla głównego wywołania w pliku custom/global/actions.intent.MAIN.yaml.

Konfigurowanie głównego wywołania

Główny prompt wywołania możesz edytować w pliku actions.intent.MAIN.yaml.

Aby zmodyfikować prompt, który Twoja akcja wysyła do użytkownika po jej wywołaniu, wykonaj te czynności:

1. Otwórz custom/global/actions.intent.MAIN.yaml w edytorze tekstu.
2. Zastąp tekst w polu speech (Start building your action...) tym powitaniem: A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: A wondrous greeting, adventurer! Welcome to the mythical land of 
                Gryffinberg! Based on your clothes, you are not from around these lands. 
                It looks like you're on your way to an epic journey.
transitionToScene: actions.scene.END_CONVERSATION

3. Zapisz plik.

Testowanie głównego wywołania w symulatorze

Konsola Actions udostępnia narzędzie internetowe do testowania działania o nazwie symulator. Interfejs symuluje urządzenia i ich ustawienia, dzięki czemu możesz rozmawiać z działaniem tak, jakby było uruchomione na inteligentnym ekranie, telefonie, głośniku lub urządzeniu z KaiOS.

Najnowsze informacje o korzystaniu z symulatora w Konsoli Actions oraz pomoc w przypadku problemów z wykonaniem poniższych czynności znajdziesz na stronie Symulator.

Po wywołaniu działania powinno ono teraz odpowiedzieć dostosowanym promptem, który został dodany („Witaj, wspaniały podróżniku…”).

Możesz użyć polecenia gactions deploy preview, aby przetestować działanie w konsoli bez aktualizowania wersji projektu działania. Gdy uruchomisz to polecenie, żadne zmiany wprowadzone w lokalnym systemie plików nie zostaną przeniesione do wdrożonych wersji projektu działania, ale możesz je przetestować w wersji podglądowej.

Aby przetestować główne wywołanie działania w symulatorze:

1. Aby wdrożyć projekt w konsoli Actions w celu przetestowania, uruchom w terminalu to polecenie:

gactions deploy preview

Po uruchomieniu tego polecenia możesz otrzymać powiadomienie o problemach z weryfikacją. Jeśli pliki zostały przesłane, możesz zignorować ten komunikat.

Powinny się wyświetlić dane wyjściowe podobne do tych:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Skopiuj podany adres URL i wklej go do przeglądarki.
3. Aby wywołać działanie w symulatorze, wpisz Talk to my test app w polu Input (Dane wejściowe) i naciśnij Enter.

Wskazówka: możesz też kliknąć element z sugestią Porozmawiaj z moją aplikacją testową w sekcji Sugestie. Jest on przetwarzany w taki sam sposób jak wypowiedziane lub wpisane dane wejściowe użytkownika.

Możesz też kliknąć ikonę mikrofonu i powiedzieć „Porozmawiaj z aplikacją testową”, aby wywołać akcję.

Gdy wywołasz główną funkcję działania, Asystent odpowie spersonalizowaną wiadomością powitalną. W tym momencie rozmowa kończy się po tym, jak Asystent odpowie powitaniem. W następnej sekcji zmodyfikujesz działanie, aby rozmowa była kontynuowana.

Wyświetlanie logów zdarzeń

Gdy na karcie Test w konsoli działań pojawi się panel, zobaczysz w nim dzienniki zdarzeń, które wyświetlają historię rozmowy w postaci dzienników zdarzeń. Każdy dziennik zdarzeń zawiera zdarzenia, które wystąpiły w trakcie danej tury rozmowy.

Twoja akcja ma obecnie 1 dziennik zdarzeń, który zawiera zarówno dane wejściowe użytkownika („Porozmawiaj z moją aplikacją testową”), jak i odpowiedź akcji. Na zrzucie ekranu poniżej widać dziennik zdarzeń akcji:

Jeśli w dzienniku zdarzeń klikniesz strzałkę w dół obok ikony Talk to my test app, zobaczysz zdarzenia, które wystąpiły w tej turze rozmowy, ułożone chronologicznie:

• userInput: Odpowiada danym wejściowym użytkownika („Porozmawiaj z aplikacją testową”).
• interactionMatch: odpowiada głównej odpowiedzi na wywołanie działania, która została wywołana przez dane wejściowe użytkownika. Jeśli rozwiniesz ten wiersz, klikając strzałkę, zobaczysz prompt dodany do głównego wywołania (A wondrous greeting, adventurer!...).
• endConversation: odpowiada wybranemu przejściu w Main invocation intencji, która obecnie kończy rozmowę. Więcej informacji o przejściach znajdziesz w następnej sekcji tego laboratorium.

Logi zdarzeń zapewniają wgląd w działanie Twojej czynności i są przydatnym narzędziem do debugowania, jeśli napotkasz jakieś problemy. Aby wyświetlić szczegóły zdarzenia, kliknij strzałkę obok jego nazwy, jak pokazano na zrzucie ekranu poniżej:

4. Tworzenie rozmowy działania

Teraz, gdy już wiesz, co się stanie po wywołaniu Twojej akcji przez użytkownika, możesz rozbudować resztę rozmowy akcji. Zanim przejdziesz dalej, zapoznaj się z tymi terminami, aby zrozumieć, jak działa rozmowa w Twojej akcji:

Kluczowe terminy:

• Scena: element składowy akcji, który przetwarza dane wejściowe użytkownika i zwykle generuje odpowiedź dla niego. Niestandardowe intencje często aktywują inne sceny, ale sceny mogą być aktywowane również w inny sposób.
• Niestandardowi odbiorcy o podobnych zamiarach: określa dane wejściowe użytkownika, które działanie może zrozumieć. Dla tych intencji określasz frazy treningowe. Gdy użytkownicy mówią coś, co pasuje do frazy treningowej lub jest do niej podobne, dopasowywany jest odpowiedni zamiar.
• Wyrażenia na potrzeby trenowania: przykłady tego, co użytkownik może powiedzieć, aby dopasować intencję. Silnik rozumienia języka naturalnego (NLU) Asystenta automatycznie rozszerza te frazy treningowe, aby uwzględniać inne podobne frazy.
• Przejście: określa scenę, do której ma nastąpić przejście po spełnieniu warunku.

Twoja czynność może mieć jedną lub wiele scen, a każdą z nich musisz aktywować, zanim będzie można ją uruchomić. Działanie, które utworzysz w tym laboratorium, ma tylko 1 scenę o nazwie Start. Najczęstszym sposobem aktywowania sceny jest skonfigurowanie działania tak, aby gdy dane wejściowe użytkownika pasowały do intencji w scenie, ta intencja wywoływała przejście do innej sceny i ją aktywowała.

Wyobraź sobie na przykład hipotetyczną czynność, która dostarcza użytkownikowi ciekawostek o zwierzętach. Gdy użytkownik wywoła to działanie, zostanie dopasowany Main invocation zamiar i nastąpi przejście do sceny o nazwie Facts.. To przejście aktywuje scenę Facts, która wysyła do użytkownika ten prompt: Would you like to hear a fact about cats or dogs?. W scenie Facts znajduje się niestandardowy zamiar o nazwie Cat, który zawiera frazy treningowe, jakie użytkownik może wypowiedzieć, aby usłyszeć ciekawostkę o kotach, np. „Chcę usłyszeć ciekawostkę o kotach” lub „kot”. Gdy użytkownik poprosi o ciekawostkę o kotach, zostanie dopasowany zamiar Cat, który spowoduje przejście do sceny o nazwie Cat fact.. Scena Cat fact zostanie aktywowana i wyśle do użytkownika prompt zawierający ciekawostkę o kotach.

Rysunek 1. Typowy przebieg rozmowy w akcji utworzonej za pomocą pakietu Actions SDK.

Sceny, intencje i przejścia tworzą logikę rozmowy i określają różne ścieżki, którymi użytkownik może podążać w rozmowie z akcją. W następnej sekcji utworzysz scenę i określisz, jak będzie ona aktywowana po wywołaniu działania przez użytkownika.

Przejście od głównego wywołania do sceny

W tej sekcji utworzysz nową scenę o nazwie Start, która wyświetla użytkownikowi pytanie, czy chce poznać swoją przyszłość. Dodajesz też przejście z głównego wywołania do nowej sceny Start.

Aby utworzyć tę scenę i dodać do niej przejście, wykonaj te czynności:

1. Otwórz custom/global/actions.intent.MAIN.yaml w edytorze tekstu.
2. Zastąp tekst w polu transitionToScene (actions.scene.END_CONVERSATION) tym tekstem: transitionToScene: Start

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Welcome to the mythical land of  Gryffinberg! Based on your clothes,
              you are not from around these lands. It looks like you're on your way
              to an epic journey.
transitionToScene: Start

Informuje to działanie, że ma przejść z głównego wywołania do sceny Start.

3. Zapisz plik.
4. W terminalu utwórz nowy katalog scenes w katalogu custom:

mkdir custom/scenes 

5. Utwórz w katalogu scenes nowy plik o nazwie Start.yaml, który reprezentuje scenę start w Twojej akcji:

touch custom/scenes/Start.yaml 

6. Otwórz Start.yaml w edytorze tekstu.
7. Wklej do pliku Start.yaml ten kod:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?

W kodzie pliku Start.yaml znajduje się pole o nazwie onEnter, które jest pierwszym etapem cyklu życia sceny.

Kluczowe terminy:

• OnEnter: etap, który jest uruchamiany po aktywowaniu sceny. OnEnter określa, co się stanie, gdy użytkownik wejdzie do sceny.

W tym przypadku prompt (Before you continue on your quest...) jest dodawany do kolejki promptów, gdy użytkownik po raz pierwszy wejdzie na scenę Start.

Kluczowe terminy:

• Kolejka promptów: prompty są do siebie dołączane w kolejce promptów. Zanim użytkownik będzie mógł odpowiedzieć, Asystent wyświetli wszystkie prompty w kolejce promptów.

Dodawanie elementów z sugestiami

Element z sugestią to klikalna sugestia dla użytkownika, którą Twoja czynność przetwarza jako dane wejściowe użytkownika. W tej sekcji dodajesz Yes i No, czyli sugestie, które pojawiają się pod skonfigurowanym przed chwilą promptem (Before you continue on your quest, would you like your fortune told?), aby wspierać użytkowników urządzeń z ekranami.

Aby dodać chipy z sugestiami do promptu sceny Start, wykonaj te czynności:

1. Zaktualizuj kod w sekcji Start.yaml, aby pasował do tego fragmentu kodu, który zawiera kod konfiguracji sugestii:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?
        suggestions:
        - title: "Yes"
        - title: "No"

2. Zapisz plik.

Testowanie działania w symulatorze

W tym momencie Twoja czynność powinna przejść z głównego wywołania do sceny Start i zapytać użytkownika, czy chce poznać swoją przyszłość. W symulowanym wyświetlaczu powinny się też pojawić karty z sugestiami.

Aby przetestować działanie w symulatorze, wykonaj te czynności:

1. W terminalu uruchom to polecenie:

gactions deploy preview

Powinny się wyświetlić dane wyjściowe podobne do tych:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Skopiuj podany adres URL i wklej go do przeglądarki.
3. Kliknij Testuj, aby przejść do symulatora.
4. Wpisz Talk to my test app w polu Input (Dane wejściowe) i naciśnij Enter. Twoja czynność powinna odpowiedzieć Main invocation promptem i dodatkowym Start promptem sceny „Zanim wyruszysz w dalszą podróż, czy chcesz poznać swoją przyszłość?” wraz z wyświetlonymi sugestiami.

Na tym zrzucie ekranu widać tę interakcję:

Dzienniki zdarzeń rejestrują każdą interakcję z symulatorem w bieżącej sesji, więc dziennik zdarzeń z testów przeprowadzonych wcześniej w tym samouczku pojawi się jako pierwszy. Aby wyczyścić dzienniki zdarzeń, kliknij Zresetuj test.

5. Aby odpowiedzieć na prompt, kliknij element z sugestią Tak lub Nie. (Możesz też powiedzieć „Tak” lub „Nie” albo wpisać Yes lub No w polu Wpisz).

Gdy odpowiesz na prompt, akcja odpowie komunikatem informującym, że nie rozumie Twoich danych wejściowych: „Przepraszam, nie zrozumiałem(-am) tego. Możesz spróbować ponownie? Ponieważ nie masz jeszcze skonfigurowanej akcji, która rozumie i odpowiada na dane wejściowe „Tak” lub „Nie”, akcja dopasowuje Twoje dane wejściowe do intencji NO_MATCH.

Kluczowe terminy:

• NO_MATCH: ogólny zamiar, który jest dopasowywany, gdy użytkownik powie coś, czego nie można dopasować do innego zamiaru w Twojej usłudze.
• Intencja systemowa: intencja skonfigurowana domyślnie, która obsługuje typowe zdarzenia systemowe, np. gdy użytkownik nie poda danych wejściowych. NO_MATCH i intencja powiązana z głównym wywołaniem to przykłady intencji systemowych.

Domyślnie intencja systemowa NO_MATCH zapewnia ogólne odpowiedzi, ale możesz je dostosować, aby poinformować użytkownika, że nie rozumiesz jego danych wejściowych. Asystent kończy rozmowę użytkownika z Twoją akcją, gdy 3 razy nie uda mu się dopasować danych wejściowych użytkownika.

Dodawanie intencji yes i no

Teraz, gdy użytkownicy mogą odpowiadać na pytania zadawane przez Twoją czynność, możesz skonfigurować ją tak, aby rozpoznawała odpowiedzi użytkowników („Tak” lub „Nie”). W kolejnych sekcjach utworzysz niestandardowe intencje, które będą dopasowywane, gdy użytkownik powie „Tak” lub „Nie”, a następnie dodasz te intencje do sceny Start.

Tworzenie intencji yes

Aby utworzyć yes intencję, wykonaj te czynności:

1. W terminalu utwórz w katalogu custom nowy katalog o nazwie intents:

mkdir custom/intents 

2. Utwórz nowy plik o nazwie yes.yaml w katalogu intents:

touch custom/intents/yes.yaml

3. Otwórz yes.yaml w edytorze tekstu.
4. Wklej do pliku yes.yaml ten fragment kodu zawierający wyrażenia na potrzeby trenowania:

yes.yaml

trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"

5. Zapisz plik.

Dodawanie intencji yes do sceny Start

Teraz akcja może rozpoznawać, kiedy użytkownik wyraża zamiar „tak”. Możesz dodać yesniestandardową intencję do Startsceny, ponieważ użytkownik odpowiada na Startprompt („Zanim wyruszysz w dalszą podróż, czy chcesz poznać swoją przyszłość?”).

Aby dodać ten niestandardowy zamiar do sceny Start, wykonaj te czynności:

1. Otwórz custom/scenes/Start.yaml w edytorze tekstu.
2. Dodaj obsługę intentEvents i yes na końcu pliku Start.yaml:

Start.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
  intent: "yes"
  transitionToScene: actions.scene.END_CONVERSATION

Gdy zostanie dopasowany yes, do kolejki promptów zostanie dodany prompt „Your future depends on the item you choose to use for your quest...". Scena Start przechodzi następnie w scenę actions.scene.END_CONVERSATION systemu, która dostarcza prompty w kolejce promptów i kończy rozmowę.

Testowanie intencji yes w symulatorze

W tym momencie Twoja akcja rozumie, kiedy użytkownik chce poznać swoją przyszłość, i zwraca odpowiednią odpowiedź.

Aby przetestować ten zamiar w symulatorze, wykonaj te czynności:

1. W terminalu uruchom to polecenie:

gactions deploy preview

Powinny się wyświetlić dane wyjściowe podobne do tych:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Skopiuj podany adres URL i wklej go do przeglądarki.
3. Kliknij Testuj, aby przejść do symulatora.
4. Aby przetestować działanie w symulatorze, wpisz Talk to my test app w polu Input (Dane wejściowe) i naciśnij Enter.
5. Wpisz Yes w polu Input (Dane wejściowe) i naciśnij Enter. Możesz też kliknąć element z sugestią Tak.

Twoja akcja odpowiada użytkownikowi i informuje go, że jego przyszłość zależy od wybranej pomocy. Działanie kończy sesję, ponieważ przejście End conversation zostało skonfigurowane dla intencji yes.

Tworzenie intencji no

Teraz możesz utworzyć intencję no, aby akcja mogła zrozumieć użytkownika i odpowiedzieć mu, gdy nie chce poznać swojej przyszłości.

Aby utworzyć ten zamiar, wykonaj te czynności:

1. W terminalu utwórz w katalogu intents nowy plik o nazwie no.yaml:

touch custom/intents/no.yaml

2. Otwórz no.yaml w edytorze tekstu.
3. Wklej do pliku no.yaml te wyrażenia na potrzeby trenowania:

no.yaml

trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks

4. Zapisz plik.

Dodawanie intencji no do sceny Start

Teraz akcja może zrozumieć, kiedy użytkownik mówi „nie” lub coś podobnego do „nie”, np. „nie”. Musisz dodać no niestandardową intencję do Start sceny, ponieważ użytkownik odpowiada na Start prompt („Zanim wyruszysz w dalszą drogę, czy chcesz poznać swoją przyszłość?”).

Aby dodać ten zamiar do sceny Start, wykonaj te czynności:

1. Otwórz custom/scenes/Start.yaml w edytorze tekstu.
2. Dodaj ten moduł obsługi no pod modułem obsługi yes w pliku Start.yaml:

Start.yaml

- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: I understand, stranger. Best of luck on your quest! Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

3. Zapisz plik.

Testowanie intencji no w symulatorze

W tym momencie Twoja akcja rozumie, kiedy użytkownik nie chce usłyszeć przepowiedni, i zwraca odpowiednią odpowiedź.

Aby przetestować ten zamiar w symulatorze, wykonaj te czynności:

1. W terminalu uruchom to polecenie:

gactions deploy preview

Powinny się wyświetlić dane wyjściowe podobne do tych:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Skopiuj podany adres URL i wklej go do przeglądarki.
3. Kliknij Testuj, aby przejść do symulatora.
4. Wpisz Talk to my test app w polu Input (Dane wejściowe) i naciśnij Enter.
5. Wpisz No w polu Input (Dane wejściowe) i naciśnij Enter. Możesz też kliknąć element z sugestią No.

Zamiast przepowiadać przyszłość, Twoja akcja życzy użytkownikowi powodzenia w dalszej podróży. Działanie kończy sesję, ponieważ przejście End conversation zostało skonfigurowane dla intencji no.

5. Wdrożenie realizacji

Obecnie odpowiedzi akcji są statyczne. Gdy scena zawierająca prompt jest aktywowana, akcja za każdym razem wysyła ten sam prompt. W tej sekcji zaimplementujesz realizację, która zawiera logikę tworzenia dynamicznej odpowiedzi w formie rozmowy.

Kluczowy termin:

• Realizacja: kod zawierający logikę działania. Webhook wywołuje połączenia z realizacją na podstawie zdarzeń, które występują w Twoich akcjach.

Usługa realizująca prośbę określa, czy użytkownik jest powracającym użytkownikiem czy nowym użytkownikiem, i modyfikuje powitanie w przypadku powracających użytkowników. Wiadomość powitalna dla powracających użytkowników jest skrócona i zawiera podziękowanie za powrót: „Witaj, wędrowcze! Witamy z powrotem w mitycznej krainie Gryffinberg!

W tym laboratorium kodowania będziesz używać edytora Cloud Functions do edytowania i wdrażania kodu realizacji.

Kluczowy termin:

• Edytor Cloud Functions: zintegrowany edytor projektów działań, w którym możesz edytować i wdrażać kod realizacji za pomocą Cloud Functions dla Firebase.

Twoja akcja może wywoływać elementy webhook, które powiadamiają o zdarzeniu występującym podczas wywołania lub w określonych częściach wykonania sceny. Gdy wywoływany jest webhook, Twoja akcja wysyła do realizacji żądanie z ładunkiem JSON oraz nazwą modułu obsługi, który ma przetworzyć zdarzenie. Ten moduł obsługi wykonuje pewne operacje logiczne i zwraca odpowiednią odpowiedź w formacie JSON.

Budowanie realizacji

W tej sekcji zmodyfikujesz realizację, aby generować różne prompty dla powracających i nowych użytkowników, gdy wywołują Twoją czynność.

Aby dodać tę logikę do realizacji zamówienia, wykonaj te czynności:

1. W terminalu upewnij się, że jesteś w katalogu głównym projektu, i utwórz nowy katalog webhooks:

mkdir webhooks 

2. Utwórz w katalogu webhooks nowy plik o nazwie ActionsOnGoogleFulfillment.yaml:

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. Otwórz ActionsOnGoogleFulfillment.yaml w edytorze tekstu.
4. Dodaj do pliku ActionsOnGoogleFulfillment.yaml procedurę obsługi greeting i treść inlineCloudFunction:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

Plik ActionsOnGoogleFulfillment.yaml definiuje moduły obsługi webhooka (np. moduł greeting) i informuje Twoją akcję, że ma używać Cloud Functions jako punktu końcowego webhooka.

5. Utwórz nowy katalog ActionsOnGoogleFulfillment w katalogu webhooks:

mkdir webhooks/ActionsOnGoogleFulfillment

6. Utwórz w katalogu ActionsOnGoogleFulfillment nowy plik o nazwie index.js:

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. Otwórz index.js w edytorze tekstu.
8. Dodaj do pliku index.js ten kod:

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});


exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Ten kod definiuje moduł obsługi greeting, który wysyła odpowiednie powitanie do

użytkownika.

9. Zapisz plik.
10. Utwórz w katalogu ActionsOnGoogleFulfillment nowy plik o nazwie package.json:

touch webhooks/ActionsOnGoogleFulfillment/package.json

Plik package.json określa zależności i inne metadane webhooka.

11. Otwórz package.json w edytorze tekstu.
12. Skopiuj kod z tego repozytorium GitHub i wklej go do pliku package.json.
13. Zapisz plik.

Zrozumienie kodu

Realizacja, która korzysta z biblioteki realizacji Actions on Google dla Node.js, odpowiada na żądania HTTP od Asystenta Google.

W poprzednim fragmencie kodu definiujesz greeting, który sprawdza, czy użytkownik odwiedził wcześniej działanie z właściwością lastSeenTime. Jeśli właściwość lastSeenTime nie jest zdefiniowana, użytkownik jest nowy i otrzymuje powitanie przeznaczone dla nowych użytkowników. W przeciwnym razie wiadomość potwierdzi powrót użytkownika i wygeneruje zmodyfikowane powitanie.

Aktualizowanie głównego wywołania w celu wywołania webhooka

Po zdefiniowaniu funkcji greeting możesz skonfigurować w głównym zamiarze wywołania moduł obsługi zdarzeń greeting, aby Twoja akcja wiedziała, że ma wywołać tę funkcję, gdy użytkownik ją wywoła.

Aby skonfigurować działanie tak, aby wywoływało nowy moduł obsługi greeting, wykonaj te czynności:

1. Otwórz custom/global/actions.intent.MAIN.yaml w edytorze tekstu.
2. Zastąp kod w pliku actions.intent.MAIN.yaml tym kodem:

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. Zapisz plik.

Gdy główny zamiar wywołania zostanie dopasowany, wywoływany jest moduł obsługi webhooka greeting.

Testowanie zaktualizowanego głównego wywołania w symulatorze

Aby przetestować działanie w symulatorze, wykonaj te czynności:

1. W terminalu uruchom to polecenie:

To polecenie wdraża webhooka i instaluje zależności, więc może potrwać dłużej niż poprzednie polecenia.

gactions deploy preview

Jeśli otrzymasz błąd 403 dotyczący interfejsu Cloud Build API lub błąd 403 dotyczący powiązania konta rozliczeniowego, zapoznaj się z artykułem Włączanie, wyłączanie i zmienianie rozliczeń w projekcie. Aby wdrożyć funkcję za pomocą Cloud Functions, musisz powiązać konto rozliczeniowe z projektem w Google Cloud. Po powiązaniu konta rozliczeniowego ponownie uruchom gactions deploy preview. Aby uniknąć naliczania opłat, wykonaj czynności opisane w sekcji Zwalnianie miejsca w projekcie na końcu tego laboratorium.

Powinny się wyświetlić dane wyjściowe podobne do tych:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Skopiuj podany adres URL i wklej go do przeglądarki.
3. Aby przetestować działanie w symulatorze, wpisz Talk to my test app w polu Input (Dane wejściowe) i naciśnij Enter.

Ponieważ w tym samouczku testujesz działanie wcześniej, nie jesteś nowym użytkownikiem, więc otrzymujesz skrócone powitanie: „Witaj, podróżniku! Witamy z powrotem w mitycznej krainie Gryffinberg…"

6. Wizualizacja działania za pomocą narzędzia Actions Builder

Pakiet Actions SDK jest interoperacyjny z internetowym środowiskiem IDE o nazwie Actions Builder, które jest zintegrowane z Konsolą Actions. Możesz przesłać lokalny system plików do wersji roboczej działania w konsoli za pomocą polecenia gactions push. W przeciwieństwie do gactions deploy preview, które umożliwia testowanie działania tylko w symulatorze, gactions push przenosi całą zawartość z plików lokalnych do narzędzia Actions Builder.

Konsola Actions udostępnia wizualizację konfiguracji akcji. Wizualizacja działania może być przydatna podczas tworzenia i nie wpływa na wersję działania, która jest używana do testowania.

Uruchomienie gactions push zastępuje bieżącą wersję roboczą projektu działań, jeśli pracujesz w zespole.

Aby przesłać projekt Actions i wyświetlić go w Konsoli Actions, wykonaj te czynności:

1. Aby przesłać projekt do konsoli Actions, uruchom w terminalu to polecenie:

gactions push

Powinny się wyświetlić dane wyjściowe podobne do tych:

✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.

2. Skopiuj podany adres URL i wklej go do przeglądarki.
3. W Konsoli Actions kliknij Rozwijaj na górnym pasku nawigacyjnym.
4. Kliknij strzałkę w dół obok opcji Sceny i kliknij Start. Powinna się wyświetlić wizualizacja sceny Start akcji, jak na tym zrzucie ekranu:

Zwolnij miejsce w projekcie [zalecane]

Uwaga: w samouczku poziomu 2 Tworzenie działań dla Asystenta Google za pomocą pakietu Actions SDK (poziom 2) wykorzystywany jest projekt utworzony w tym samouczku. Jeśli planujesz wykonać ćwiczenie Level 2, nie usuwaj projektu. Zamiast tego możesz go usunąć w sekcji „Wyczyść projekt” na końcu ćwiczenia Level 2.

Aby uniknąć ewentualnych opłat, zalecamy usunięcie projektów, których nie zamierzasz używać. Aby usunąć projekty utworzone w tym laboratorium, wykonaj te czynności:

1. Aby usunąć projekt Cloud i zasoby, wykonaj czynności opisane w sekcji Wyłączanie (usuwanie) projektów.

Na stronie Ustawienia Google Cloud Platform wybierz projekt, który chcesz usunąć.

2. Opcjonalnie: aby natychmiast usunąć projekt z Konsoli Actions, wykonaj czynności opisane w sekcji Usuwanie projektu. Jeśli nie wykonasz tego kroku, projekt zostanie automatycznie usunięty po około 30 dniach.

7. Gratulacje!

Znasz podstawy tworzenia akcji dla Asystenta Google za pomocą pakietu Actions SDK.

Omówione kwestie

• Jak skonfigurować projekt w Actions w konsoli Actions
• Jak używać pakietu Actions SDK do tworzenia projektu działań w lokalnym systemie plików
• Jak dodać prompt do głównego wywołania, aby użytkownicy mogli rozpocząć rozmowę z Twoją akcją
• Jak utworzyć interfejs konwersacyjny ze scenami, intencjami, przejściami, przyciskami z sugestiami i realizacją
• Testowanie działania za pomocą Symulatora Actions

Więcej informacji

Aby dowiedzieć się więcej o tworzeniu działań dla Asystenta Google, zapoznaj się z tymi materiałami:

• Oficjalna witryna z dokumentacją dotyczącą tworzenia działań dla Asystenta Google
• Strona Actions on Google w GitHubie z przykładowym kodem i bibliotekami
• Oficjalna społeczność Reddit dla deweloperów korzystających z Asystenta

Obserwuj @ActionsOnGoogle na Twitterze, aby otrzymywać najnowsze ogłoszenia, i publikuj tweety z hashtagiem #AoGDevs, aby dzielić się swoimi projektami.

Ankieta dotycząca opinii

Zanim wyjdziesz, wypełnij krótką ankietę dotyczącą Twoich wrażeń.