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

1. Omówienie

Uwaga: 13 czerwca 2023 r. wycofaliśmy działania dotyczące rozmów. Więcej informacji znajdziesz w artykule Wycofanie akcji z rozmowami.

Platforma dla deweloperów Asystenta Google umożliwia tworzenie oprogramowania rozszerzającego funkcje Asystenta Google – wirtualnego osobistego asystenta – działa na ponad miliardzie urządzeń, w tym inteligentnych głośnikach, telefonach, samochodach, telewizorach, słuchawkach i nie tylko. Użytkownicy angażują się w rozmowę z Asystentem, aby wykonać różne czynności, na przykład kupić produkty spożywcze lub zamówić przejazd. Jako deweloper możesz korzystać z platformy dla deweloperów Asystenta, aby łatwo tworzyć ciekawe i skuteczne rozmowy między użytkownikami i zewnętrzną usługą realizacji zamówień oraz nimi zarządzać.

To ćwiczenie w Codelabs zawiera zagadnienia na poziomie podstawowym, które umożliwiają programowanie za pomocą pakietu SDK Actions w Asystencie Google. nie jest wymagane żadne wcześniejsze doświadczenie na platformie. W ramach tego ćwiczenia w programie tworzysz prostą akcję dla Asystenta Google, która opowiada użytkownikom o swoim losie, gdy rozpoczynają przygodę w mitycznej krainie Gryffinberg. W ramach ćwiczenia z programowania na poziomie 2 pakietu Actions SDK jeszcze bardziej rozwijasz to działanie, aby dostosować los użytkownika na podstawie jego danych wejściowych.

Co utworzysz

W tym ćwiczeniu w Codelabs dowiesz się, jak utworzyć prostą akcję przy użyciu tych funkcji:

• Odpowiada użytkownikom za pomocą wiadomości powitalnej.
• Użytkownik zadaje pytanie i odpowiednio odpowiada na wybór użytkownika
• Udostępnia elementy z sugestią, które użytkownicy mogą kliknąć, aby wprowadzić dane wejściowe
• Modyfikuje wiadomość powitalną w zależności od tego, czy użytkownik jest powracającym użytkownikiem.

Gdy ukończysz to ćwiczenia w programie, ukończona akcja będzie miała następujący przebieg rozmowy (tekst obok mikrofonu reprezentuje dane wejściowe użytkownika, a tekst obok osoby mówiącej – odpowiedź akcji):

Czego się nauczysz

• Jak utworzyć projekt w Konsoli Actions
• Jak używać narzędzia gactions do przekazywania projektu akcji i przeciągania go między konsolą Actions a lokalnym systemem plików
• Jak wysłać prośbę do użytkownika po wywołaniu przez niego akcji
• Jak przetworzyć dane wejściowe użytkownika i zwrócić odpowiedź
• Jak przetestować akcję w Actions Simulator (Symulatorze Actions)
• Jak wdrożyć realizację za pomocą edytora Cloud Functions

Czego potrzebujesz

W Twoim środowisku muszą znajdować się te narzędzia:

• wybranym IDE lub edytorem tekstu.
• terminal do uruchamiania poleceń powłoki dla Node.js i npm,
• przeglądarki, na przykład Google Chrome;

Jeśli podczas tworzenia akcji wolisz używać większej liczby narzędzi wizualnych, wykonaj ćwiczenie z programowania w ramach Actions Builder (na poziomie 1), które pozwala utworzyć działania w ramach Akcji przy użyciu interfejsu Actions Builder w konsoli.

2. Skonfiguruj

W sekcjach poniżej opisujemy, jak skonfigurować środowisko programistyczne i utworzyć projekt w Actions.

Sprawdzanie ustawień uprawnień Google

Aby przetestować akcję utworzoną w ramach tego ćwiczenia z programowania, musisz włączyć niezbędne uprawnienia, aby symulator mógł uzyskać dostęp do akcji.

Aby włączyć uprawnienia, wykonaj następujące 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 Sieć i Aktywność w aplikacjach, zaznacz pole wyboru 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 w Actions na potrzeby tego ćwiczenia z programowania, wykonaj te czynności:

1. Otwórz konsolę Actions.
2. Kliknij Nowy projekt.
3. Wpisz nazwę projektu, np. actions-codelab. (Nazwa ma służyć do celów wewnętrznych. Później możesz ustawić nazwę zewnętrzną projektu).

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

Zapisz identyfikator projektu dla akcji

Identyfikator projektu to unikalny identyfikator akcji. Potrzebujesz identyfikatora projektu do wykonania kilku kroków w tym ćwiczeniu z programowania.

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

1. W Konsoli Actions kliknij 3 pionowe kropki (wstaw ikonę tutaj).
2. Kliknij Ustawienia projektu.

3. Skopiuj identyfikator projektu**.

Powiąż konto rozliczeniowe

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

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

1. Otwórz stronę płatności 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ę płatności Google Cloud Platform.
6. Kliknij kartę Moje projekty.
7. Kliknij 3 kropki w sekcji Działania obok projektu Actions, którego dotyczy ćwiczenia z programowania.
8. Kliknij Zmień ustawienia płatności.
9. W menu wybierz skonfigurowane konto rozliczeniowe.
10. Kliknij Ustaw konto.

Aby uniknąć opłat, wykonaj czynności opisane w sekcji Wyczyść projekt na końcu tego ćwiczenia z programowania.

Instalowanie interfejsu wiersza poleceń Gactions

W ramach tego ćwiczenia w programie użyjesz narzędzia wiersza poleceń gactions, aby zsynchronizować projekt w Actions między konsolą Actions a lokalnym systemem plików.

Kluczowy termin:

• Interfejs wiersza poleceń gactions: narzędzie, które umożliwia m.in. inicjowanie plików projektu Action, przekazywanie aktualizacji do konsoli Actions i wdrażanie projektów Actions.

Aby zainstalować interfejs wiersza poleceń Gactions, wykonaj instrukcje podane w artykule Instalowanie narzędzia wiersza poleceń gactions.

Pobierz projekt w Actions

Aby zacząć tworzyć akcję, pobierz projekt Actions z Konsoli Actions.

Aby pobrać projekt w Actions:

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>

Informacje o strukturze pliku

Projekt w Actions pobrany z Konsoli Actions ma strukturę plików YAML. Poniższa grafika przedstawia ogólną strukturę pliku:

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

• actions/: reprezentuje Twój projekt w Actions. System wywołuje actions.yaml po wywołaniu akcji, która następnie wywołuje plik custom/global/actions.intent.MAIN.yaml.
• custom/: katalog, w którym będziesz modyfikować akcję.
• global/: ten katalog zawiera intencje systemowe, które platforma automatycznie dodaje do 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 przenieść lub które nie dotyczą konkretnego projektu. Można go 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 akcją przez wywołanie. Jeśli na przykład masz akcje o nazwie MovieTime, użytkownicy mogą wywołać je, mówiąc np. „OK Google, porozmawiaj z MovieTime”, gdzie MovieTime to wyświetlana nazwa. Akcja musi mieć wyświetlaną nazwę, jeśli chcesz ją wdrożyć w środowisku produkcyjnym. Aby przetestować działanie, nie musisz określać wyświetlanej nazwy. Zamiast tego możesz użyć wyrażenia „Talk to my test app” (Porozmawiaj z aplikacją testową) w symulatorze, aby wywołać działanie. Więcej informacji o symulatorze znajdziesz w dalszej części tej sekcji.

Musisz zmodyfikować główne wywołanie, aby zdefiniować, co się dzieje po wywołaniu akcji przez użytkownika.

Kluczowy termin:

• Główne wywołanie: punkt wejścia, w którym użytkownicy mogą rozpoczynać rozmowy z akcją. Gdy użytkownicy wypowiadają wyrażenie podobne do „OK Google, porozmawiaj z <wyświetlaną nazwą>”, uruchamia się główne wywołanie i reaguje na to użytkownika.

Domyślnie akcja wyświetla ogólny komunikat po aktywowaniu wywołania („Aby rozpocząć tworzenie akcji, definiując główne wywołanie”).

Kluczowy termin:

• Prompt: określa, co akcja wysyła do użytkowników w odpowiedzi. Mogą to być proste odpowiedzi tekstowe i głosowe lub wiadomości rozszerzone, takie jak karty i obrazy.

Możesz użyć specjalnego promptu Canvas, aby wyświetlić użytkownikowi treści wizualne na pełnym ekranie. Więcej informacji o funkcji Canvas znajdziesz w dokumentacji interaktywnego obszaru roboczego.

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

Skonfiguruj wywołanie główne

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

Aby zmodyfikować prompt, który akcja wysyła do użytkownika, gdy wywołuje działanie, 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...) następującą 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 to symulator narzędzia internetowego do testowania akcji. Interfejs symuluje sprzęt i ich ustawienia, dzięki czemu możesz rozmawiać z akcją tak, jakby działała na inteligentnym ekranie, telefonie, głośniku lub KaiOS.

Najnowsze informacje na temat korzystania z symulatora w Konsoli Actions oraz informacje o problemach występujących podczas wykonywania poniższych czynności znajdziesz na stronie Simulator.

Gdy wywołasz akcję, powinna ona zareagować przy użyciu dodanego przez Ciebie spersonalizowanego promptu („Cudowne powitanie, poszukiwacz przygód...").

Aby przetestować działanie w konsoli, możesz użyć polecenia gactions deploy preview bez aktualizowania wersji projektu Actions. Po uruchomieniu tego polecenia żadne zmiany wprowadzone w lokalnym systemie plików nie są przekazywane do wdrożonych wersji projektu Actions, ale możesz je przetestować w wersji testowej.

Aby przetestować główne wywołanie akcji w symulatorze, wykonaj te czynności:

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 ze sprawdzaniem poprawności. Jeśli Twoje pliki zostały przekazane dalej, możesz zignorować to powiadomienie.

Zostaną wyświetlone dane wyjściowe, które będą wyglądały mniej więcej tak:

✔ 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 sugestii Porozmawiaj z aplikacją testową w sekcji Sugestie, który działa tak samo jak wprowadzanie tekstu wpisywanego lub głosowego.

Aby wywołać działanie, możesz też kliknąć ikonę mikrofonu i powiedzieć „Talk to my test app” (Porozmawiaj z aplikacją testową).

Gdy aktywujesz główne wywołanie akcji, Asystent odpowie, wysyłając Twoją spersonalizowaną wiadomość powitalną. Na tym etapie rozmowa kończy się, gdy Asystent odpowie powitaniem. W następnej sekcji zmodyfikujesz działanie, aby kontynuować rozmowę.

Wyświetl logi zdarzeń

Na karcie Testowanie w Konsoli Actions zobaczysz dzienniki zdarzeń, na których historia rozmowy jest widoczna w postaci dzienników zdarzeń. W każdym dzienniku zdarzeń są wyświetlane zdarzenia, które miały miejsce podczas tego etapu rozmowy.

Akcja ma obecnie 1 dziennik zdarzeń, który zawiera dane wejściowe użytkownika („Porozmawiaj z aplikacją testową”) i odpowiedź akcji. Poniższy zrzut ekranu przedstawia dziennik zdarzeń akcji:

Jeśli klikniesz strzałkę w dół obok przycisku Talk to my test app w dzienniku zdarzeń, możesz wyświetlić uporządkowane chronologicznie zdarzenia, które miały miejsce na tym etapie rozmowy:

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

Dzienniki zdarzeń zapewniają wgląd w działanie akcji i są przydatne przy jej debugowaniu, jeśli pojawią się jakieś problemy. Aby zobaczyć szczegóły wydarzenia, kliknij strzałkę obok jego nazwy, tak jak na tym zrzucie ekranu:

4. Utwórz rozmowę dotyczącą akcji

Skoro wiesz już, co się dzieje, gdy użytkownik wywoła Twoją akcję, możesz przejść do reszty rozmowy. Zanim przejdziesz do dalszych ćwiczeń z programowania, zapoznaj się z poniższymi terminami, aby zrozumieć, jak działa rozmowa akcji:

Kluczowe terminy:

• Scena: element składowy akcji, który przetwarza dane wejściowe użytkownika i zwykle generuje dla niego odpowiedź. Niestandardowe intencje często aktywują inne sceny, ale można je też aktywować w inny sposób.
• Niestandardowa intencja: definiuje dane wejściowe użytkownika, które akcja może zrozumieć. Określasz wyrażenia na potrzeby nauki dla tych intencji. Gdy użytkownicy powiedzą coś, co pasuje do wyrażenia na potrzeby trenowania lub do niego podobne, oznacza to, że odpowiada on odpowiedniemu zamiarowi.
• Wyrażenia na potrzeby nauki: przykłady wypowiedzi użytkownika w związku z konkretnym zamiarem. Mechanizm rozumienia języka naturalnego przez Asystenta w naturalny sposób rozszerza te wyrażenia na potrzeby nauki, dodając do nich inne podobne wyrażenia.
• Przejście: określa, na którą scenę przejść po spełnieniu warunku.

Akcja może zawierać 1 scenę lub kilka i każdą z nich musisz aktywować. Akcja utworzona w tym ćwiczeniu z programowania ma tylko 1 scenę o nazwie Start. Najczęstszym sposobem aktywowania sceny jest skonfigurowanie akcji w taki sposób, aby gdy dane wejściowe użytkownika pasują do intencji w danej scenie, ta intencja powodowała przejście do innej sceny i aktywowała ją.

Wyobraź sobie na przykład hipotetyczne działanie, które dostarcza użytkownikowi faktów o zwierzętach. Gdy użytkownik wywoła tę akcję, intencja Main invocation uruchamia przejście do sceny o nazwie Facts.. To przejście aktywuje scenę Facts, która wysyła do użytkownika następujący prompt: Would you like to hear a fact about cats or dogs? W scenie Facts jest intencja niestandardowa o nazwie Cat, która zawiera frazy naukowe, które użytkownik może powiedzieć, aby usłyszeć fakty o kotach, np. „Chcę usłyszeć fakty o kotach” czy „kot”. Gdy użytkownik chce usłyszeć fakty o kotach, intencja Cat zostaje dopasowana i powoduje przejście do sceny o nazwie Cat fact.. Scena Cat fact zostaje aktywowana i wysyła do użytkownika prompt zawierający fakty o kotie.

Rysunek 1. Przebieg typowej konwersacji w akcji utworzonej za pomocą pakietu Actions SDK.

Sceny, intencje i przejścia tworzą logikę rozmowy i określają różne ścieżki, jakie może poruszać użytkownik w ramach rozmowy. W następnej sekcji utworzysz scenę i określisz sposób jej aktywacji po wywołaniu przez użytkownika akcji.

Przejście z głównego wywołania na scenę

W tej sekcji utworzysz nową scenę o nazwie Start, która wysyła użytkownikowi pytanie, czy chce opowiedzieć o wróżbie. Możesz też dodać 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) następującym fragmentem: 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

Sprawi to, że akcja będzie musiała 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 akcji:

touch custom/scenes/Start.yaml 

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

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: scena wyświetlana po aktywowaniu sceny. OnEnter określa, co się stanie, gdy użytkownik wejdzie na scenę.

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

Kluczowe terminy:

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

Dodawanie elementów z sugestią

Elementy z sugestią oferują użytkownikom klikalne sugestie, które akcja przetwarza jako dane wejściowe użytkownika. W tej sekcji dodasz elementy sugestii Yes i No wyświetlane pod właśnie skonfigurowanym promptem (Before you continue on your quest, would you like your fortune told?), aby obsługiwać użytkowników urządzeń z ekranami.

Aby dodać elementy z sugestią do promptu sceny Start, wykonaj te czynności:

1. Zaktualizuj kod w pliku Start.yaml, tak aby pasował do tego fragmentu kodu, który zawiera kod umożliwiający konfigurowanie elementów z sugestią:

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.

Przetestuj działanie w symulatorze

W tym momencie akcja powinna przejść z głównego wywołania do sceny Start i zapytać użytkownika, czy chce opowiedzieć jego wróżby. Na symulowanym wyświetlaczu powinny też pojawiać się elementy z sugestiami.

Aby przetestować akcję w symulatorze, wykonaj te czynności:

1. W terminalu uruchom to polecenie:

gactions deploy preview

Zostaną wyświetlone dane wyjściowe, które będą wyglądały mniej więcej tak:

✔ 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 Test, aby przejść do symulatora.
4. Wpisz Talk to my test app w polu Dane wejściowe i naciśnij Enter. Akcja powinna odpowiedzieć za pomocą promptu Main invocation i dodanej sceny Start: „Zanim przejdziesz dalej, czy chcesz poznać wróżby?” wraz z wyświetlonymi elementami sugestii.

Tę interakcję można zobaczyć na poniższym zrzucie ekranu:

Dzienniki zdarzeń rejestrują wszystkie interakcje z symulatorem w bieżącej sesji, dlatego dziennik zdarzeń z testów w ramach tego ćwiczenia w programie jest wyświetlany jako pierwszy. Aby wyczyścić dzienniki zdarzeń, kliknij Resetuj test.

5. Kliknij element z sugestią Tak lub Nie, aby odpowiedzieć na prompt. Możesz też powiedzieć „Tak” lub „Nie” albo wpisać Yes lub No w polu Dane wejściowe.

Gdy odpowiesz na prompt, akcja otrzyma w odpowiedzi komunikat informujący o tym, że nie może zrozumieć wprowadzonych przez Ciebie danych: „Nie rozumiem. Możesz spróbować jeszcze raz?”. Akcja nie została jeszcze skonfigurowana w taki sposób, aby rozumieła dane wejściowe „Tak” lub „Nie” i reagowała na nie, dlatego akcja pasuje do intencji NO_MATCH.

Kluczowe terminy:

• NO_MATCH: intencja zbiorcza, która jest dopasowywana, gdy użytkownik powie coś, czego nie można dopasować do innego intencji w akcji.
• Intencja systemowa: domyślnie skonfigurowana intencja, która obsługuje typowe zdarzenia systemowe, np. gdy użytkownik nie poda danych wejściowych. Przykładami intencji systemowych są intencja NO_MATCH i intencja powiązana z głównym wywołaniem.

Domyślnie intencja systemowa NO_MATCH udostępnia odpowiedzi ogólne, ale możesz je dostosować, aby wskazać użytkownikowi, że nie rozumiesz jego odpowiedzi. Asystent kończy rozmowę użytkownika z Twoją akcją, jeśli nie udało się jej dopasować 3 razy.

Dodaj intencje yes i no

Użytkownicy mogą już odpowiedzieć na pytanie, jakie stawia akcja, możesz więc skonfigurować akcję, by poznać zachowania użytkowników odpowiedzi („Tak” lub „Nie”). W kolejnych sekcjach tworzysz intencje niestandardowe, które są dopasowywane, gdy użytkownik mówi „Tak” lub „Nie”, i dodaj te intencje do sceny Start.

Utwórz intencję yes

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

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

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 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 Start scen

Akcja wie, kiedy użytkownik wyraża intencję „tak”. Możesz dodać niestandardową intencję yes do sceny Start, ponieważ użytkownik odpowiada na prompt Start („Zanim przejdziesz dalej, czy chcesz poznać wróżby?”).

Aby dodać niestandardową intencję do sceny Start, wykonaj te czynności:

1. Otwórz custom/scenes/Start.yaml w edytorze tekstu.
2. Dodaj moduły obsługi 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 intencja yes jest zgodna, do kolejki próśb dodawany jest prompt „Twoja przyszłość zależy od elementu, którego chcesz użyć w zadaniu...”. Następnie scena Start przechodzi do sceny systemowej actions.scene.END_CONVERSATION, która wyświetla prompty w kolejce promptów i kończy rozmowę.

Przetestowanie intencji yes w symulatorze

W tym momencie akcja rozumie, kiedy użytkownik chce poznać wróżby, i zwraca odpowiednią odpowiedź.

Aby przetestować tę intencję za pomocą symulatora, wykonaj te czynności:

1. W terminalu uruchom to polecenie:

gactions deploy preview

Zostaną wyświetlone dane wyjściowe, które będą wyglądały mniej więcej tak:

✔ 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 Test, aby przejść do symulatora.
4. Aby przetestować działanie w symulatorze, wpisz Talk to my test app w polu Dane wejściowe i naciśnij Enter.
5. Wpisz Yes w polu Dane wejściowe i naciśnij Enter. Możesz też kliknąć element z sugestią Tak.

Akcja reaguje na użytkownika i informuje, że jego los zależy od wybranej pomocy. Akcja kończy sesję, ponieważ skonfigurowano przejście End conversation dla intencji yes.

Utwórz intencję no

Teraz możesz utworzyć intencję no, aby akcja rozumieła użytkownika i reagowała na niego, gdy nie chce usłyszeć jego wróżby.

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

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

touch custom/intents/no.yaml

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

no.yaml

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

4. Zapisz plik.

Dodaj intencję no do Start scen

Akcja wykrywa teraz, kiedy użytkownik wypowiada „no” lub coś podobnego do „no”, na przykład „nope”. Musisz dodać niestandardową intencję no do sceny Start, ponieważ użytkownik odpowiada na prompt Start („Zanim przejdziesz dalej, czy chcesz poznać wróżby?”).

Aby dodać tę intencję do sceny Start, wykonaj te czynności:

1. Otwórz custom/scenes/Start.yaml w edytorze tekstu.
2. Dodaj ten moduł obsługi no do modułu obsługi yes w elemencie 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.

Przetestowanie intencji no w symulatorze

W tym momencie akcja rozumie, że użytkownik nie chce poznać ich wróżby, i zwraca odpowiednią odpowiedź.

Aby przetestować tę intencję za pomocą symulatora, wykonaj te czynności:

1. W terminalu uruchom to polecenie:

gactions deploy preview

Zostaną wyświetlone dane wyjściowe, które będą wyglądały mniej więcej tak:

✔ 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 Test, aby przejść do symulatora.
4. Wpisz Talk to my test app w polu Dane wejściowe i naciśnij Enter.
5. Wpisz No w polu Dane wejściowe i naciśnij Enter. Możesz też kliknąć element z sugestią No.

Akcja nie daje użytkownikowi szczęścia, tylko życzy mu powodzenia. Akcja kończy sesję, ponieważ skonfigurowano przejście End conversation dla intencji no.

5. Wdróż realizację

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

Kluczowy termin:

• Fulfillment (Realizacja): kod zawierający funkcje logiczne dotyczące akcji. Webhook wywołuje Twoją realizację na podstawie zdarzeń występujących w ramach akcji.

Realizacja określa, czy użytkownik jest powracającym czy nowym użytkownikiem, i zmienia wiadomość powitalną akcji dla powracających użytkowników. Wiadomość powitalna jest skracana dla powracających użytkowników i stanowi informację o jego powrocie: „Ciekawe powitanie, poszukiwacz przygód! Witaj ponownie w mitycznej krainie Gryffinberga”.

W ramach tego ćwiczenia w programowaniu do edytowania i wdrażania kodu realizacji możesz używać edytora Cloud Functions.

Kluczowy termin:

• Edytor Cloud Functions: zintegrowany edytor projektów Actions, którego możesz używać do edytowania i wdrażania kodu realizacji za pomocą Cloud Functions dla Firebase.

Akcja może aktywować webhooki, które powiadamiają o zrealizowaniu zdarzenia występującego podczas wywołania lub w konkretnych częściach wykonania sceny. Po aktywowaniu webhooka akcja wysyła do Twojej realizacji żądanie z ładunkiem JSON wraz z nazwą modułu obsługi, który ma być używany do przetworzenia zdarzenia. Ten moduł obsługi przeprowadza pewną logikę i zwraca odpowiednią odpowiedź JSON.

Spełnij swoje marzenia

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

Aby dodać tę funkcję do swojej realizacji, wykonaj te czynności:

1. Sprawdź w terminalu, czy 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 ActionsOnGoogleFulfillment.yaml w edytorze tekstu.
4. Dodaj moduł obsługi greeting i zawartość inlineCloudFunction do pliku ActionsOnGoogleFulfillment.yaml:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

Plik ActionsOnGoogleFulfillment.yaml definiuje moduły obsługi webhooka (takie jak greeting) i informuje Akcję, aby używała 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 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 package.json w edytorze tekstu.
12. Skopiuj kod z tego repozytorium GitHub i wklej go w pliku package.json.
13. Zapisz plik.

Zrozumienie kodu

Twoja realizacja, która korzysta z biblioteki Actions on Google Fulfillment w Node.js, odpowiada na żądania HTTP z Asystenta Google.

W poprzednim fragmencie kodu definiujesz moduł obsługi greeting, który sprawdza, czy użytkownik wcześniej skorzystał z akcji 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.

Zaktualizuj główne wywołanie, aby aktywować webhooka

Po zdefiniowaniu funkcji greeting możesz skonfigurować moduł obsługi zdarzeń greeting w głównej intencji wywołania, tak aby akcja wiedziała, że wywołuje tę funkcję, gdy użytkownik wywoła Twoją akcję.

Aby skonfigurować akcję do wywoływania nowego modułu obsługi greeting, wykonaj te czynności:

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

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. Zapisz plik.

Teraz po dopasowaniu głównej intencji wywołania wywoływany jest moduł obsługi webhooka greeting.

Testuj zaktualizowane główne wywołanie w symulatorze

Aby przetestować akcję w symulatorze, wykonaj te czynności:

1. W terminalu uruchom to polecenie:

Ponieważ to polecenie wdraża webhooka i instaluje zależności, może to potrwać dłużej niż w przypadku poprzednich poleceń.

gactions deploy preview

Jeśli wystąpi błąd 403 dotyczący interfejsu Cloud Build API lub błąd 403 dotyczący powiązania konta rozliczeniowego, zapoznaj się z sekcją Włączanie, wyłączanie i zmienianie płatności w projekcie. Aby przeprowadzić wdrożenie przy użyciu Cloud Functions, musisz powiązać konto rozliczeniowe z projektem w Google Cloud. Po powiązaniu konta rozliczeniowego uruchom ponownie gactions deploy preview. Aby uniknąć opłat, wykonaj czynności opisane w sekcji Wyczyść projekt na końcu tego ćwiczenia z programowania.

Zostaną wyświetlone dane wyjściowe, które będą wyglądały mniej więcej tak:

✔ 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 Dane wejściowe i naciśnij Enter.

Ponieważ testowałeś(-aś) swoją akcję wcześniej w ramach tego ćwiczenia z programowania, nie jesteś nowym użytkownikiem, więc otrzymujesz to skrócone powitanie: „Cudowne powitanie! Witaj ponownie w mitycznej krainie Gryffinberga!”

6. Wizualizacja działania za pomocą Actions Builder

Pakiet Actions SDK jest kompatybilny z internetowym środowiskiem IDE o nazwie Actions Builder, które jest zintegrowane z konsolą Actions. Możesz przekazać lokalny system plików do wersji roboczej akcji w konsoli za pomocą polecenia gactions push. W przeciwieństwie do interfejsu gactions deploy preview, który umożliwia testowanie akcji tylko w symulatorze, gactions push przenosi wszystkie treści z plików lokalnych do Actions Builder.

Konsola Actions to wizualna reprezentacja konfiguracji akcji. Wizualizacja akcji może być przydatna w trakcie programowania i nie ma wpływu na wersję akcji obsługiwaną do testów.

Uruchomienie gactions push zastępuje bieżącą wersję roboczą projektu w Actions, jeśli współpracujesz z innymi osobami.

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

1. W terminalu uruchom to polecenie, aby przekazać projekt do Konsoli Actions:

gactions push

Zostaną wyświetlone dane wyjściowe, które będą wyglądały mniej więcej tak:

✔ 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 działań na pasku nawigacyjnym u góry kliknij Programowanie.
4. Kliknij strzałkę w dół obok opcji Sceny i wybierz Rozpocznij. Powinna pojawić się wizualna reprezentacja sceny Start z akcji, tak jak na tym zrzucie ekranu:

Czyszczenie projektu [zalecane]

Uwaga: ćwiczenia z programowania na poziomie 2 – Tworzenie działań Asystenta Google przy użyciu pakietu SDK Actions (poziom 2), stanowią kontynuację projektu utworzonego w ramach tego ćwiczenia z programowania. Jeśli planujesz ćwiczenia z programowania na poziomie 2, nie usuwaj projektu. możesz usunąć go w sekcji „Wyczyść projekt” na końcu ćwiczenia z programowania na poziomie 2.

Aby uniknąć ewentualnych opłat, zalecamy usunięcie projektów, których nie chcesz używać. Aby usunąć projekty utworzone w ramach tego ćwiczenia z programowania, wykonaj te czynności:

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

Pamiętaj, aby na stronie Ustawienia Google Cloud Platform wybrać właściwy projekt do usunięcia.

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

7. Gratulacje!

Znasz podstawy tworzenia akcji w Asystencie Google za pomocą pakietu SDK Actions.

Co zostało omówione

• Jak skonfigurować projekt Actions w Konsoli Actions
• Jak używać pakietu Actions SDK, aby utworzyć projekt Actions w lokalnym systemie plików
• Jak dodać prompt do głównego wywołania, aby użytkownicy mogli rozpoczynać rozmowę za pomocą akcji
• Jak utworzyć interfejs konwersacyjny ze scenami, intencjami, przejściami, elementami z sugestią i realizacją
• Jak przetestować akcję za pomocą Actions Simulator (Symulatora Actions)

Więcej informacji

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

• Oficjalna strona z dokumentacją tworzenia Działań dla Asystenta Google
• Strona Actions on Google GitHub z przykładowym kodem i bibliotekami
• Oficjalna społeczność na Reddicie dla deweloperów pracujących z Asystentem

Obserwuj konto @ActionsOnGoogle na Twitterze, aby być na bieżąco z najnowszymi ogłoszeniami, a hashtag #AoGDevs informuje o swoich projektach.

Ankieta dotycząca opinii

Zanim opuścisz tę stronę, wypełnij krótką ankietę na temat swoich wrażeń.