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

1. Przegląd

Ostrzeżenie: akcje konwersacyjne zostały wycofane 13 czerwca 2023 r. Więcej informacji znajdziesz w artykule Wycofanie akcji konwersacyjnych.

Platforma Google Assistant Developer umożliwia tworzenie oprogramowania, które rozszerza funkcjonalność Asystenta Google, wirtualnego osobistego asystenta, na ponad miliard urządzeń, w tym inteligentne głośniki, telefony, samochody, telewizory, słuchawki i inne. Użytkownicy rozmawiają z Asystentem, aby wykonywać różne zadania, np. kupować artykuły spożywcze czy rezerwować przejazdy. Jako deweloper możesz używać platformy deweloperskiej Asystenta, aby łatwo tworzyć i zarządzać atrakcyjnymi i skutecznymi rozmowami między użytkownikami a Twoją usługą realizacji zamówień.

To ćwiczenie obejmuje podstawowe pojęcia związane z tworzeniem akcji za pomocą pakietu Actions SDK dla Asystenta Google. Nie musisz mieć wcześniejszego doświadczenia z tą platformą, aby je ukończyć. W tym ćwiczeniu utworzysz prostą akcję w Asystencie Google, która będzie przepowiadać użytkownikom przyszłość, gdy rozpoczną przygodę w mitycznej krainie Gryffinberg. W tym ćwiczeniu w Codelabs dotyczącym pakietu Actions SDK na poziomie 2 rozbudujesz tę akcję, aby dostosować wróżbę do danych wejściowych użytkownika.

Co utworzysz

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

• odpowiada użytkownikom wiadomością powitalną,
• zadaje użytkownikom pytanie i odpowiednio reaguje na ich wybór;
• Udostępnia elementy z sugestią, które użytkownicy mogą kliknąć, aby podać dane wejściowe.
• modyfikuje wiadomość powitalną dla użytkownika w zależności od tego, czy jest on powracającym użytkownikiem;

Po ukończeniu tego ćwiczenia gotowa akcja będzie miała następujący przebieg rozmowy (tekst obok mikrofonu reprezentuje dane wejściowe użytkownika, a tekst obok głośnika – odpowiedź akcji):

Czego się nauczysz

• Jak utworzyć projekt w konsoli Actions
• Jak używać narzędzia gactions do przesyłania i pobierania projektu akcji między konsolą Actions a lokalnym systemem plików
• Jak wysłać prompt do użytkownika po wywołaniu akcji
• jak przetwarzać dane wejściowe użytkownika i zwracać odpowiedź,
• Jak przetestować akcję w symulatorze akcji
• Jak zaimplementować realizację zamówienia za pomocą edytora Cloud Functions

Czego potrzebujesz

W Twoim ś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ądarkę internetową, np. Google Chrome;

Jeśli wolisz tworzyć akcje za pomocą narzędzi wizualnych, wykonaj ćwiczenie Tworzenie akcji dla Asystenta Google przy użyciu kreatora akcji (poziom 1), w którym utworzysz tę samą akcję za pomocą zintegrowanego środowiska programistycznego kreatora akcji w konsoli.

2. Skonfiguruj

W sekcjach poniżej opisano, jak skonfigurować środowisko programistyczne i utworzyć projekt akcji.

Sprawdzanie ustawień uprawnień Google

Aby przetestować akcję utworzoną w tym ćwiczeniu, musisz włączyć niezbędne uprawnienia, aby symulator mógł uzyskać dostęp do akcji.

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 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 to kontener na akcję.

Aby utworzyć projekt Actions na potrzeby tego ćwiczenia, 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ć nazwę zewnętrzną projektu).

4. Kliknij Utwórz projekt.
5. Na ekranie What kind of Action do you want to build? (Jaką akcję chcesz utworzyć?) wybierz kartę Custom (Niestandardowa).
6. Kliknij Dalej.
7. Na ekranie Jak chcesz go utworzyć? wybierz kartę Pusty projekt.
8. Kliknij Zacznij tworzyć.

Zapisz identyfikator projektu akcji.

Identyfikator projektu to unikalny identyfikator akcji. Identyfikator projektu będzie potrzebny w kilku krokach tego ćwiczenia.

Aby znaleźć identyfikator projektu, wykonaj te czynności:

1. W konsoli Actions kliknij 3 pionowe kropki (wstaw tutaj ikonę).
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ę 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 tego ćwiczenia z programowania.
8. Kliknij Zmień płatności.
9. W menu wybierz skonfigurowane konto rozliczeniowe.
10. Kliknij Ustaw konto.

Aby uniknąć opłat, wykonaj czynności opisane w sekcji Czyszczenie projektu na końcu tego ćwiczenia.

Instalowanie interfejsu wiersza poleceń gactions

W tym ćwiczeniu użyjesz narzędzia wiersza poleceń gactions (CLI), aby zsynchronizować projekt 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 akcji, przekazywanie aktualizacji do konsoli Actions i wdrażanie projektów akcji.

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

Pobieranie projektu w Actions

Zacznij tworzyć akcję, pobierając projekt akcji 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>

Struktura pliku

Projekt Actions pobrany z konsoli Actions ma strukturę plików YAML. Poniższy obraz przedstawia ogólną strukturę pliku:

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

• actions/: reprezentuje Twój projekt Actions. Gdy akcja zostanie wywołana, system wywoła funkcję actions.yaml, która następnie wywoła plik custom/global/actions.intent.MAIN.yaml.
• custom/: katalog, w którym będziesz pracować nad modyfikacją akcji.
• 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.
• manifest.yaml: plik zawierający informacje, które można przenosić lub które nie są powiązane z konkretnym projektem i można je przenosić między projektami.
• settings/: reprezentuje ustawienia projektu działań, takie jak wyświetlana nazwa, domyślne ustawienia regionalne i kategoria.

3. Rozpoczynanie rozmowy

Użytkownicy rozpoczynają rozmowę z akcją przez wywołanie. Jeśli na przykład masz akcję o nazwie MovieTime, użytkownicy mogą ją wywołać, mówiąc „OK Google, porozmawiaj z MovieTime”, gdzie MovieTime to wyświetlana nazwa. Jeśli chcesz wdrożyć akcję w środowisku produkcyjnym, musisz podać jej wyświetlaną nazwę. Nie musisz jednak tego robić, aby przetestować akcję. Zamiast tego możesz użyć w symulatorze wyrażenia „Porozmawiaj z moją aplikacją testową”, aby wywołać akcję. Więcej informacji o symulatorze znajdziesz w dalszej części tej sekcji.

Musisz zmodyfikować główne wywołanie, aby określić, co się stanie, gdy użytkownik wywoła Twoją akcję.

Kluczowy termin:

• Główne wywołanie: punkt wejścia, który umożliwia użytkownikom rozpoczynanie rozmów z akcją. Gdy użytkownicy wypowiedzą frazę podobną do „OK Google, porozmawiaj z <wyświetlana nazwa>”, zostanie wywołane główne wywołanie, które odpowie użytkownikowi.

Domyślnie akcja wyświetla ogólny prompt po wywołaniu („Start building your Action by defining main invocation.”).

Kluczowy termin:

• Prompt: określa, co akcja wysyła użytkownikom w odpowiedzi. Prompty mogą być prostymi odpowiedziami tekstowymi i głosowymi lub wiadomościami multimedialnymi, takimi 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 Canvas znajdziesz w dokumentacji Interactive Canvas.

W następnej sekcji dostosujesz prompt 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ć komunikat, który akcja wysyła do użytkownika po jej wywołaniu, 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 akcji, które nazywa się symulatorem. Interfejs symuluje urządzenia i ich ustawienia, dzięki czemu możesz rozmawiać z akcją tak, jakby działała na inteligentnym ekranie, telefonie, głośniku lub systemie KaiOS.

Najnowsze informacje o korzystaniu z symulatora w konsoli Actions oraz rozwiązania problemów, które mogą wystąpić podczas wykonywania poniższych czynności, znajdziesz na stronie Symulator.

Gdy wywołasz akcję, powinna ona teraz odpowiedzieć dodanym przez Ciebie niestandardowym promptem („Witaj, poszukiwaczu przygód!…”).

Możesz użyć polecenia gactions deploy preview, aby przetestować akcję w konsoli bez aktualizowania wersji projektu akcji. Po uruchomieniu tego polecenia żadne zmiany wprowadzone w lokalnym systemie plików nie zostaną przeniesione do wdrożonych wersji projektu akcji, 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 na potrzeby testowania, 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ć to powiadomienie.

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ć akcję w symulatorze, wpisz Talk to my test app w polu Dane wejściowe i naciśnij Enter.

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

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

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

Wyświetlanie dzienników zdarzeń

Gdy jesteś na karcie Test (Testuj) w konsoli Actions, w panelu wyświetlane są dzienniki zdarzeń, które pokazują historię rozmów w formie dzienników zdarzeń. Każdy dziennik zdarzeń wyświetla zdarzenia, które miały miejsce podczas danej tury rozmowy.

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 klikniesz strzałkę w dół obok Talk to my test app w dzienniku zdarzeń, zobaczysz zdarzenia, które wystąpiły w tej turze rozmowy, uporządkowane chronologicznie:

• userInput: odpowiada danym wejściowym użytkownika („Porozmawiaj z moją aplikacją testową”).
• interactionMatch: odpowiada głównej odpowiedzi wywołania 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 do głównego wywołania (A wondrous greeting, adventurer!...).
• endConversation: odpowiada wybranemu przejściu w intencji Main invocation, która obecnie kończy rozmowę. Więcej informacji o przejściach znajdziesz w następnej sekcji tego ćwiczenia.

Dzienniki zdarzeń dają wgląd w działanie akcji i są przydatnymi narzędziami do debugowania akcji w razie problemów. Aby zobaczyć szczegóły zdarzenia, kliknij strzałkę obok nazwy zdarzenia, jak pokazano na zrzucie ekranu poniżej:

4. Tworzenie rozmowy z akcją

Teraz, gdy masz już zdefiniowane, co dzieje się po wywołaniu akcji przez użytkownika, możesz utworzyć resztę rozmowy z akcją. Zanim przejdziesz dalej, zapoznaj się z poniższymi terminami, aby zrozumieć, jak działa rozmowa z akcją:

Kluczowe terminy:

• Scena: element składowy akcji, który przetwarza dane wejściowe użytkownika i zwykle generuje odpowiedź dla użytkownika. Niestandardowe intencje często aktywują inne sceny, ale sceny można też aktywować na inne sposoby.
• Niestandardowi odbiorcy o podobnych zamiarach: definiuje dane wejściowe użytkownika, które akcja może zrozumieć. Dla tych intencji definiujesz frazy do trenowania. Gdy użytkownicy mówią coś, co pasuje do frazy uczącej 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ę. Mechanizm rozumienia języka naturalnego (NLU) Asystenta rozszerza te wyrażenia uczące o inne podobne wyrażenia.
• Przejście: określa, do której sceny ma nastąpić przejście po spełnieniu warunku.

Akcja może mieć jedną lub wiele scen, a każdą z nich musisz aktywować, zanim będzie mogła się uruchomić. Akcja, którą utworzysz w tym ćwiczeniu, ma tylko jedną scenę o nazwie Start. Najczęstszym sposobem aktywowania sceny jest skonfigurowanie akcji tak, aby po dopasowaniu danych wejściowych użytkownika do intencji w scenie ta intencja wywoływała przejście do innej sceny i ją aktywowała.

Wyobraź sobie na przykład hipotetyczną akcję, która dostarcza użytkownikowi informacji o zwierzętach. Gdy użytkownik wywołuje tę akcję, dopasowywana jest intencja Main invocation, która aktywuje 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 znajduje się intencja niestandardowa o nazwie Cat, która zawiera wyrażenia uczące, które 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 dopasowana intencja Cat, która wywoła przejście do sceny Cat fact.. Scena Cat fact zostanie aktywowana i wyśle do użytkownika prompta z 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 definiują różne ścieżki, którymi użytkownik może podążać podczas rozmowy z akcją. W następnej sekcji utworzysz scenę i określisz, jak ma być aktywowana po wywołaniu akcji przez użytkownika.

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

W tej sekcji utworzysz nową scenę o nazwie Start, która będzie wysyłać użytkownikowi prośbę z pytaniem, czy chce, aby mu powróżyć. Dodasz 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 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

To polecenie informuje akcję, ż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. W katalogu scenes utwórz nowy plik o nazwie Start.yaml, który reprezentuje scenę start w 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 onEnter, które jest pierwszym etapem uruchamianym w cyklu życia sceny.

Kluczowe terminy:

• OnEnter: etap, który jest uruchamiany po aktywacji 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 do sceny Start.

Kluczowe terminy:

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

Dodawanie elementów z sugestiami

Elementy z sugestią zawierają klikalne sugestie dla użytkownika, które akcja przetwarza jako dane wejściowe użytkownika. W tej sekcji dodasz elementy z sugestią Yes i No, które pojawią się pod skonfigurowanym przez Ciebie promptem (Before you continue on your quest, would you like your fortune told?), aby pomóc użytkownikom urządzeń z ekranem.

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

1. Zaktualizuj kod w pliku Start.yaml, aby odpowiadał poniższemu fragmentowi kodu, który zawiera kod do konfigurowania 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.

Testowanie akcji w symulatorze

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

Aby przetestować akcję 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 Test (Testuj), aby przejść do symulatora.
4. Wpisz Talk to my test app w polu Dane wejściowe i naciśnij Enter. Akcja powinna odpowiedzieć promptem Main invocation i dodatkowym promptem sceny Start: „Zanim wyruszysz w dalszą drogę, czy chcesz poznać swoją przyszłość?”, wyświetlając elementy z sugestią.

Ten zrzut ekranu pokazuje 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 ćwiczeniu z programowania pojawia się jako pierwszy dziennik zdarzeń. Aby wyczyścić dzienniki zdarzeń, kliknij Resetuj test.

5. Aby odpowiedzieć na prośbę, kliknij element z sugestią Tak lub Nie. (Możesz też powiedzieć „Tak” lub „Nie” albo wpisać Yes lub No w polu Dane wejściowe).

Gdy odpowiesz na prośbę, akcja odpowie komunikatem, że nie rozumie Twoich danych wejściowych: „Nie rozumiem. Możesz spróbować jeszcze raz?”. Akcja nie została jeszcze skonfigurowana tak, aby rozumiała i reagowała na dane wejściowe „Tak” lub „Nie”, więc dopasowuje je do intencji NO_MATCH.

Kluczowe terminy:

• NO_MATCH: intencja ogólna, która jest dopasowywana, gdy użytkownik mówi coś, czego nie można dopasować do innej intencji w Twojej akcji.
• Intencja systemowa: intencja, która jest skonfigurowana domyślnie i obsługuje typowe zdarzenia systemowe, np. gdy użytkownik nie podaje 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 dostarcza 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 nie może dopasować danych wejściowych użytkownika 3 razy.

Dodawanie intencji yes i no

Teraz, gdy użytkownicy mogą odpowiadać na pytanie zadane przez akcję, możesz skonfigurować akcję tak, aby rozumiał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”, i dodasz je 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 plik yes.yaml w edytorze tekstu.
4. Wklej do pliku yes.yaml ten fragment kodu zawierający wyrażenia uczące:

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 zrozumieć, kiedy użytkownik wyraża intencję „tak”. Możesz dodać intencję niestandardową yes do sceny Start, ponieważ użytkownik odpowiada na prompt Start („Zanim wyruszysz w dalszą drogę, czy chcesz poznać swoją przyszłość?”).

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

1. Otwórz plik custom/scenes/Start.yaml w edytorze tekstu.
2. Dodaj moduł 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 zostanie dopasowana, prompt „Twoja przyszłość zależy od przedmiotu, który wybierzesz do misji…” zostanie dodany do kolejki promptów. Następnie scena Start przechodzi w scenę systemową actions.scene.END_CONVERSATION, która dostarcza prompty z kolejki i kończy rozmowę.

Testowanie intencji yes w symulatorze

Na tym etapie akcja rozumie, kiedy użytkownik chce usłyszeć swoją wróżbę, i zwraca odpowiednią odpowiedź.

Aby przetestować tę intencję 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 Test (Testuj), aby przejść do symulatora.
4. Aby przetestować akcję w symulatorze, wpisz Talk to my test app w polu Input (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 odpowiada użytkownikowi i informuje go, że jego przyszłość zależy od wybranej pomocy. Następnie 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 mogła zrozumieć użytkownika i odpowiedzieć mu, gdy nie będzie chciał usłyszeć swojej wróżby.

Aby utworzyć tę 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 plik no.yaml w edytorze tekstu.
3. Wklej do pliku no.yaml te wyrażenia uczące:

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 chcę”. Musisz dodać intencję niestandardową no do sceny Start, ponieważ użytkownik odpowiada na prompt Start („Zanim wyruszysz w dalszą drogę, chcesz poznać swoją przyszłość?”).

Aby dodać tę intencję 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 akcja rozumie, kiedy użytkownik nie chce usłyszeć wróżby, i zwraca odpowiednią odpowiedź.

Aby przetestować tę intencję 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 Test (Testuj), 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.

Zamiast przepowiadać użytkownikowi przyszłość, akcja życzy mu powodzenia w podróży. Następnie akcja kończy sesję, ponieważ skonfigurowano przejście End conversation dla intencji no.

5. Wdrażanie 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 odpowiedź, która zawiera logikę tworzenia dynamicznej odpowiedzi konwersacyjnej.

Kluczowy termin:

• Realizacja: kod zawierający logikę akcji. Webhook wywołuje wywołania realizacji na podstawie zdarzeń, które występują w Akcjach.

Twoja realizacja określa, czy użytkownik jest powracający czy nowy, i modyfikuje wiadomość powitalną akcji dla powracających użytkowników. Wiadomość powitalna jest skrócona dla powracających użytkowników i zawiera informację o ich powrocie: „Witaj, poszukiwaczu przygód! Witaj ponownie w mitycznej krainie Gryffinberg!

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

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ą realizację zamówienia o zdarzeniu występującym podczas wywołania lub określonych części wykonywania sceny. Gdy webhook zostanie aktywowany, akcja wysyła do realizacji żądanie z ładunkiem JSON wraz z nazwą modułu obsługi, który ma zostać użyty do przetworzenia zdarzenia. Ten moduł obsługi wykonuje pewne operacje logiczne i zwraca odpowiednią odpowiedź JSON.

Tworzenie realizacji

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

Aby dodać tę logikę do realizacji, 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 moduł obsługi greeting i treść inlineCloudFunction do pliku ActionsOnGoogleFulfillment.yaml:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

Plik ActionsOnGoogleFulfillment.yaml definiuje moduły obsługi webhooka (takie jak moduł obsługi greeting) i informuje 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 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(&#>39;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

user.

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

Twoja 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 moduł obsługi greeting, który sprawdza, czy użytkownik odwiedził wcześniej akcję 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 aktywowania webhooka

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

Aby skonfigurować akcję tak, aby wywoływała 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.

Teraz, gdy główne wywołanie intencji zostanie dopasowane, zostanie wywołany moduł obsługi webhooka greeting.

Testowanie zaktualizowanego wywołania głównego w symulatorze

Aby przetestować akcję 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 pojawi się 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 ramach projektu. 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ąć opłat, wykonaj czynności opisane w sekcji Czyszczenie projektu 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ć akcję w symulatorze, wpisz Talk to my test app w polu Input (Dane wejściowe) i naciśnij Enter.

Akcja została już przetestowana we wcześniejszej części tego ćwiczenia, więc nie jesteś nowym użytkownikiem i otrzymasz skrócone powitanie: „Witaj, poszukiwaczu przygód! Witamy ponownie w mitycznej krainie Gryffinberg!…

6. Wizualizacja akcji za pomocą Kreatora akcji

Pakiet Actions SDK współpracuje ze środowiskiem IDE o nazwie Actions Builder, które jest zintegrowane z konsolą Actions. Możesz przesłać lokalny system plików do wersji roboczej akcji w konsoli za pomocą polecenia gactions push. W odróżnieniu od polecenia gactions deploy preview, które umożliwia testowanie akcji tylko w symulatorze, polecenie gactions push przenosi całą zawartość z plików lokalnych do kreatora akcji.

Konsola Actions udostępnia wizualną reprezentację konfiguracji akcji. Wizualne przedstawienie akcji może być przydatne podczas jej tworzenia i nie ma wpływu na wersję akcji, która jest udostępniana do testowania.

Uruchomienie polecenia gactions push zastępuje bieżącą wersję roboczą projektu akcji, jeśli pracujesz nad nim wspólnie z innymi osobami.

Aby przesłać projekt akcji 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 kliknij Develop (Programowanie) na górnym pasku nawigacyjnym.
4. Kliknij strzałkę w dół obok opcji Sceny i wybierz Rozpocznij. Powinna pojawić się wizualna reprezentacja sceny Start akcji, jak na tym zrzucie ekranu:

Czyszczenie projektu [zalecane]

Uwaga: ćwiczenie na poziomie 2, Tworzenie akcji dla Asystenta Google przy użyciu pakietu Actions SDK (poziom 2), bazuje na projekcie utworzonym w tym ćwiczeniu. Jeśli planujesz wykonać ćwiczenie na poziomie 2, nie usuwaj projektu. Możesz go usunąć w sekcji „Czyszczenie projektu” na końcu ćwiczenia 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 ćwiczeniu, wykonaj te czynności:

1. Aby usunąć projekt w chmurze i zasoby, wykonaj czynności opisane w sekcji Zamykanie (usuwanie) projektów.

Upewnij się, że na stronie Ustawienia Google Cloud Platform wybierasz 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, projekt zostanie automatycznie usunięty po około 30 dniach.

7. Gratulacje!

Znasz podstawy tworzenia akcji dla Asystenta Google przy użyciu pakietu Actions SDK.

Omówione kwestie

• Jak skonfigurować projekt w konsoli Actions
• jak używać pakietu Actions SDK do tworzenia projektu akcji w lokalnym systemie plików;
• Jak dodać prompta do głównego wywołania, aby użytkownicy mogli rozpocząć rozmowę z akcją.
• Jak utworzyć interfejs konwersacyjny ze scenami, intencjami, przejściami, elementami z sugestią i realizacją.
• Jak przetestować akcję za pomocą symulatora akcji

Więcej informacji

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

• Oficjalna witryna z dokumentacją dotyczącą tworzenia akcji dla Asystenta Google
• Strona Actions on Google na GitHubie, na której znajdziesz przykładowy kod i biblioteki.
• Oficjalna społeczność Reddit dla deweloperów pracujących z Asystentem

Obserwuj konto @ActionsOnGoogle na Twitterze, aby otrzymywać najnowsze ogłoszenia, i tweetuj z hasztagiem #AoGDevs, aby dzielić się swoimi projektami.

Ankieta dotycząca opinii

Zanim skończysz, wypełnij krótką ankietę o swoich wrażeniach.