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 deweloperska Asystenta Google umożliwia tworzenie oprogramowania rozszerzającego 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 Twoją usługą realizacji zamówień.

To ćwiczenie obejmuje podstawowe koncepcje tworzenia aplikacji za pomocą pakietu Actions SDK dla Asystenta Google. Aby je ukończyć, nie musisz mieć wcześniejszego doświadczenia z tą platformą. W tym ćwiczeniu 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ę akcję, aby dostosowywać 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;
• Zawiera sugestie, które użytkownicy mogą kliknąć, aby wprowadzić 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 Action będzie miał następujący przebieg rozmowy (tekst obok mikrofonu reprezentuje dane wejściowe użytkownika, a tekst obok głośnika – odpowiedź Action):

Czego się nauczysz

• Jak utworzyć projekt 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 przetwarzać dane wejściowe użytkownika i zwracać 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ć akcje za pomocą bardziej wizualnych narzędzi, wykonaj ćwiczenie Tworzenie akcji dla Asystenta Google przy użyciu narzędzia Actions Builder (poziom 1), w którym tworzy się tę samą akcję 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 Actions jest kontenerem dla Twojej akcji.

Aby utworzyć projekt Actions 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.

Zapisz identyfikator 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:

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 do płatności.
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 3 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 ćwiczenia.

Instalowanie interfejsu wiersza poleceń gactions

W tym ćwiczeniu użyjesz narzędzia interfejsu wiersza poleceń gactions, aby zsynchronizować projekt 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ń:

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>

Struktura 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 funkcję actions.yaml, gdy wywoływana jest Twoja czynność, która 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ć lub które nie są specyficzne dla żadnego projektu i można je przenosić między projektami.
• settings/: reprezentuje ustawienia projektu 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 „Talk to my test app” (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, gdy zostanie wywołana („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świetlić użytkownikowi obrazy na pełnym ekranie. Więcej informacji o Canvas znajdziesz w dokumentacji interaktywnego płótna.

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, gdy ją wywołuje, wykonaj te czynności:

1. Otwórz plik custom/global/actions.intent.MAIN.yaml w edytorze tekstu.
2. Zastąp tekst w polu speech (Start building your action...) tą wiadomością powitalną: 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 o rozwiązywaniu problemów, które mogą wystąpić podczas wykonywania 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łań. 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ądu.

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 pojawić się 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 w przeglądarce.
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 dzienników zdarzeń

Gdy na karcie Test w konsoli Działania pojawi się panel z dziennikami zdarzeń, zobaczysz historię rozmowy w postaci dzienników zdarzeń. Każdy dziennik zdarzeń zawiera zdarzenia, które wystąpiły podczas 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 danym momencie 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 akcji i są przydatnym narzędziem do debugowania w przypadku wystąpienia problemów. 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 usłudze:

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.
• Niestandardowy zamiar: 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, dopasowywana jest odpowiednia intencja.
• 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 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 powodowała przejście do innej sceny i jej aktywowanie.

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 zamiar Main invocation, który spowoduje 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. Przebieg typowej tury 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 od 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 plik 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

Dzięki temu Twoja akcja przejdzie 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 plik 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 wchodzi 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

Elementy z sugestiami oferują klikalne sugestie dla użytkownika, które Twoja czynność przetwarza jako dane wejściowe użytkownika. W tej sekcji dodajesz sugestie Yes i No, 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ć podpowiedzi 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 pojawić się 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 w przeglądarce.
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ć promptem Main invocation i dodatkowym promptem sceny Start „Zanim wyruszysz w dalszą podróż, czy chcesz poznać swoją przyszłość?”, wyświetlając sugestie.

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). Czy możesz spróbować jeszcze raz? Ponieważ nie skonfigurowano jeszcze akcji tak, aby rozpoznawała i odpowiadała na dane wejściowe „Tak” lub „Nie”, akcja dopasowuje 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 akcji.
• 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 plik 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.

Dodaj intencję yes do sceny Start

Teraz akcja może rozpoznawać, kiedy użytkownik wyraża zamiar „tak”. Możesz dodać yes niestandardową intencję do Start sceny, ponieważ użytkownik odpowiada na Start prompt („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 plik 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 „Twoja przyszłość zależy od przedmiotu, którego użyjesz w swojej misji…”. 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 czynność 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 pojawić się 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 w przeglądarce.
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 plik 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.

Dodaj intencję 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 plik 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 będzie wiedzieć, kiedy użytkownik nie chce poznać swojej przyszłości, i zwróci odpowiednią odpowiedź.

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

1. W terminalu uruchom to polecenie:

gactions deploy preview

Powinny pojawić się 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 w przeglądarce.
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 zostanie aktywowana, akcja za każdym razem wysyła ten sam prompt. W tej sekcji zaimplementujesz realizację, która zawiera logikę tworzenia dynamicznej odpowiedzi konwersacyjnej.

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 ponownie w mitycznej krainie Gryffinberg!

W tym ćwiczeniu do edytowania i wdrażania kodu realizacji użyjesz edytora Cloud Functions.

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.

Zbuduj swój system realizacji

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

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 nowy plik o nazwie ActionsOnGoogleFulfillment.yaml w katalogu webhooks:

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. Otwórz plik ActionsOnGoogleFulfillment.yaml w edytorze tekstu.
4. Dodaj do pliku ActionsOnGoogleFulfillment.yaml obsługę 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 działanie, ż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 nowy plik o nazwie index.js w katalogu ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. Otwórz plik 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 nowy plik o nazwie package.json w katalogu ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/package.json

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

11. Otwórz plik 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 Actions on Google Fulfillment 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ść potwierdza powrót użytkownika i generuje 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 plik 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 ćwiczenia.

Powinny pojawić się 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 w przeglądarce.
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 laboratorium kodowania testujesz działanie wcześniej, nie jesteś nowym użytkownikiem, więc otrzymujesz skróconą wersję powitania: „Witaj, podróżniku! Witamy ponownie w mitycznej krainie Gryffinberg…"

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

Pakiet Actions SDK jest kompatybilny 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 wizualną reprezentację konfiguracji akcji. Wizualizacja działania może być przydatna podczas programowania 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 działań 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 pojawić się 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 w przeglądarce.
3. W Konsoli Actions na górnym pasku nawigacyjnym kliknij Rozwijaj.
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: ćwiczenie na poziomie 2, Tworzenie akcji dla Asystenta Google przy użyciu pakietu Actions SDK (poziom 2), jest oparte na projekcie utworzonym w tym ćwiczeniu. Jeśli planujesz wykonać ćwiczenie z programowania na poziomie 2, nie usuwaj projektu. Zamiast tego możesz go usunąć w sekcji „Czyszczenie projektu” na końcu ćwiczenia z programowania na poziomie 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 Zamykanie (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.

Co obejmuje ochrona

• Jak skonfigurować projekt w Actions w konsoli Actions
• Jak używać pakietu Actions SDK do tworzenia projektu akcji w lokalnym systemie plików
• Jak dodać prompt do głównego wywołania, aby użytkownicy mogli rozpocząć rozmowę z Twoją czynnością
• Jak utworzyć interfejs konwersacyjny ze scenami, intencjami, przejściami, 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ń.