Tworzenie projektów

Projekt Actions pakuje wszystkie działania w jeden kontener. Publikujesz ten projekt w Actions on Google, aby Asystent Google mógł wykrywać i wywoływać środowiska rozmów.

komponenty projektu działań
Rysunek 1. Struktura projektu Actions

Do tworzenia projektu Actions używasz tych komponentów niskiego poziomu:

  • Ustawienia i zasoby określają metadane projektu i zasoby, takie jak ikony projektów. Google używa tych informacji do publikowania akcji w katalogu Asystenta, dzięki czemu użytkownicy mogą je wyszukiwać i wywoływać.

  • Intencje reprezentują zadanie do wykonania, na przykład dane wejściowe użytkownika lub zdarzenie systemowe, które wymaga przetwarzania. Najczęściej są to zamiary użytkownika. Te intencje umożliwiają zadeklarowanie wyrażeń treningowych, które są naturalnie rozszerzane przez mechanizm rozumienia języka naturalnego przez NLU i zawierają wiele innych, podobnych wyrażeń. NLU wykorzystuje agregację tych wyrażeń, aby wytrenować model językowy, za pomocą którego Asystent dopasowuje dane wejściowe użytkownika. Jeśli w trakcie rozmowy niektóre dane wejściowe użytkownika są zgodne z modelem języka intencji, środowisko wykonawcze Asystenta wysyła intencję do akcji, aby mogło ją przetworzyć i odpowiedzieć użytkownikowi.

  • Typy umożliwiają wyodrębnianie uporządkowanych danych na podstawie danych wejściowych użytkownika. Dzięki dodaniu adnotacji do wyrażeń treningowych z typami NLU może wyodrębnić za Ciebie odpowiednie, uporządkowane dane, dzięki czemu nie musisz analizować otwartych danych wejściowych.

  • Sceny przetwarzają intencje i są głównymi wykonawcami logiki w działaniach. Umożliwiają wypełnianie przedziałów, ocenianie logiki warunkowej, zwracanie komunikatów użytkownikom, a nawet wywoływanie zewnętrznych usług internetowych w celu realizacji logiki biznesowej. W połączeniu z intencjami sceny te zapewniają zaawansowany sposób wykrywania określonych danych wejściowych użytkownika lub zdarzeń systemowych i realizowanie powiązanej z nimi logiki.

  • Prompty określają odpowiedzi statyczne lub dynamiczne, za pomocą których odpowiadasz użytkownikom.

  • Webhooki umożliwiają przekazywanie dodatkowych zadań do usług internetowych (realizacji), na przykład do weryfikowania danych lub generowania promptów. Działania komunikują się z realizacją za pomocą protokołu webhooka opartego na formacie JSON.

  • Interaktywne obszar roboczy umożliwia tworzenie bogatych i wciągających funkcji w aplikacjach internetowych, które korzystają z HTML, CSS i JavaScriptu.

Tworzenie projektu

Zanim zaczniesz tworzyć projekt dla Asystenta Google, musisz utworzyć projekt w Konsoli Actions. Aby utworzyć projekt:

  1. Otwórz Konsolę Actions.
  2. Kliknij Nowy projekt.
  3. Wpisz nazwę projektu i kliknij Utwórz projekt.
  4. Na ekranie Jakie działanie chcesz utworzyć? wybierz kategorię, która najlepiej odpowiada Twojemu projektowi, i kliknij Dalej.
  5. Na ekranie Jak chcesz ją skompilować wybierz sposób kompilacji i kliknij Rozpocznij kompilację. Możesz na przykład zacząć od pustego projektu lub przykładowego.

Tworzenie lokalnego projektu SDK Actions

Po utworzeniu projektu w Actions w Konsoli Actions możesz zainicjować projekt w lokalnym środowisku programistycznym.

Aby zainicjować projekt SDK Actions z istniejącego projektu Actions, wykonaj te czynności:

  1. Utwórz pusty katalog dla projektu Actions w lokalnym systemie plików.
  2. W tym pustym katalogu utwórz katalog sdk.
  3. Zmień katalog roboczy na sdk w terminalu.

Zacznij od pustego projektu

Jeśli chcesz zacząć od pustego projektu utworzonego właśnie w konsoli, uruchom gactions pull --project-id <my-project-id>.

$ mkdir myAction
$ cd myAction
$ mkdir sdk
$ cd sdk
$ gactions pull --project-id my-project-id
Pulling your project files from Draft for a project id: "my-project-id"
✔ Done. You should see the files written in path/to/myAction/sdk

Zacznij od przykładowego projektu

Jeśli chcesz zacząć od przykładowego projektu, uruchom gactions init <sample name>.

$ mkdir actions-test
$ cd actions-test
$ mkdir sdk
$ cd sdk
$ gactions init question
Writing sample files for question.
✔ Done. Please checkout the following documentation - https://developers.google.com/assistant/conversational/build on the next steps on how to get started.

Zdefiniuj informacje o projekcie

Ustawienia i zasoby projektu określają informacje o nim, takie jak obsługa funkcji i powierzchni, obsługiwane języki, wyświetlana nazwa, opis, logo itd. W tabeli poniżej opisujemy główne dostępne ustawienia i zasoby. Actions on Google używa tych informacji do wdrażania i publikowania projektu w katalogu Asystenta.

Nazwa Opis
Informacje o katalogu Zawiera informacje, dzięki którym Actions on Google może opublikować Twój projekt w katalogu Asystenta. Obejmuje metadane i części dotyczące projektu oraz zasoby graficzne związane z logo i obrazami banerów.
Kierowanie na lokalizację Konfiguruje języki, w których dostępne są akcje.
Możliwości platformy Konfiguruje platformy, na których dostępne są działania.
Informacje o firmie Zawiera dane kontaktowe Twojej firmy.
Weryfikowanie marki Połącz swoją witrynę lub aplikację na Androida, aby uzyskać dodatkowe korzyści, takie jak zarezerwowane nazwy wywołań i linki do witryn w ramach akcji.
Premiera Konfiguruje różne wersje testowe i produkcyjne akcji – w wersji testowej i produkcyjnej.
Linki Asystenta Pozwól użytkownikom wywoływać działania z Twoich usług internetowych.

Aby określić informacje o projekcie:

  1. Określ ustawienia globalne dla projektu w Actions w sdk/settings/settings.yaml. Obsługiwane wartości znajdziesz w dokumentacji referencyjnej Ustawienia.

    Ten fragment kodu zawiera przykładowy plik sdk/settings/settings.yaml:

    accountLinking:
      enableAccountCreation: true
      linkingType: GOOGLE_SIGN_IN
    category: GAMES_AND_TRIVIA
    projectId: my-project-id
    ...
    

  2. W pliku sdk/settings/<locale>/settings.yaml określ ustawienia, które mogą się różnić w zależności od języka użytkownika (np. wyrażenia wywołania w różnych językach), zastępując język swoim docelowym językiem.

    Informacje o obsługiwanych wartościach znajdziesz w dokumentacji LocalizedSettings.

    Ten fragment kodu zawiera przykładowe ustawienia w języku angielskim zdefiniowane w pliku sdk/settings/en/settings.yaml:

    localizedSettings:
      developerEmail: developer@developers.com
      developerName: Developer Name
      displayName: My Display Name
      fullDescription: full description of the action
      largeBannerImage: https://path/to/large/banner
      privacyPolicyUrl: http://path/to/privacy/policy
      sampleInvocations:
      - Talk to My Display Name
      shortDescription: short description of the action
      smallLogoImage: https://path/to/small/logo
      voice: female_1
    ...
    

Dodaj zasoby

W projekcie Actions możesz przechowywać zasoby, takie jak pliki graficzne, pliki audio i ciągi tekstowe, oraz odwoływać się do nich w plikach konfiguracji (np. definicji promptów czy warunkach) za pomocą zdefiniowanej przez system zmiennej $resources.

Zasoby projektu są przechowywane w sekcji resources/, a do każdego typu zasobu jest przypisywany folder w katalogu.

Możesz lokalizować zasoby, tworząc foldery dla określonych języków w folderze typu zasobu. Na przykład możesz przechowywać hiszpańskie wersje ciągów tekstowych w folderze resources/strings/es/<filename>.yaml.

zdjęcia;

Pliki graficzne są przechowywane w usłudze resources/images/, a możesz odwoływać się do nich za pomocą atrybutu $resources.images.<name of the image file without file extension>. Dozwolone rozszerzenia plików:

  • gif
  • png
  • jpg
  • jpeg

Jeśli na przykład angielska wersja małego logo jest zapisana w polu resources/images/en/square.png, a angielska wersja dużego banera została zapisana odpowiednio w pliku resources/images/en/landscape.jpg, sdk/settings/en/settings.yaml z poprzedniego przykładu będzie wyglądać tak:

localizedSettings:
  developerEmail: developer@developers.com
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action

  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action

  smallLogoImage: $resources.images.square
  voice: female_1
...

Pliki audio

Pliki audio są przechowywane w usłudze resources/audio/, a możesz się do nich odwołać za pomocą atrybutu $resources.audio.<name of the audio file without file extension>.

Dozwolone rozszerzenia plików:

  • mp3
  • mpeg

Możesz na przykład odwoływać się do nagrań dźwiękowych z promptów:

candidates:
  - first_simple:
      variants:
        - speech: your speech response
    content:
      media:
        mediaType: audio
        mediaObjects:
          - name: media name
            description: media description
            url: $resources.audio.intro

Ciąg znaków

Ciągi tekstowe są przechowywane w usłudze resources/strings/ jako pliki .yaml. Każdy plik zawiera mapę kluczy ciągów znaków oraz powiązane z nimi wartości, którymi mogą być pojedyncze ciągi lub listy. Możesz odwoływać się do wartości za pomocą polecenia $resources.strings.<name of the image file without file extension>.<key> w przypadku pojedynczych ciągów znaków lub pobierania losowej wartości z listy oraz $resources.strings.<name of the image file without file extension>.<key>.<numerical index> dla konkretnej wartości ciągu znaków na liście.

Na przykład użycie ciągów zasobów do lokalizacji ciągów znaków sdk/settings/en/settings.yaml z poprzedniego przykładu mogłoby wyglądać tak:

localizedSettings:
  developerEmail: developer@developers.com
  developerName: $resources.strings.appinfo.developerName
  displayName: $resources.strings.appinfo.displayName
  fullDescription: $resources.strings.appinfo.fullDescription
  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: $resources.strings.appinfo.privacyPolicyUrl
  sampleInvocations:
  - $resources.strings.invocations.sample
  shortDescription: $resources.strings.appinfo.shortDescription
  smallLogoImage: $resources.images.square
  voice: female_1
...

Testowanie projektów w symulatorze

Konsola Actions zawiera symulator do wyświetlania podglądu akcji. Umożliwia on wyświetlanie danych debugowania, ustawianie możliwości urządzenia, symulowanie ustawień regionalnych i wykonywanie innych działań.

Rysunek 3. Główne obszary symulatora: (1) dane wejściowe użytkownika, (2) widok urządzenia, (3) opcje i ustawienia oraz (4) dziennik rozmów.

Aby przetestować projekt:

  1. Uruchom gactions deploy preview, aby wdrożyć akcję w trybie podglądu i włączyć testowanie w symulatorze.
  2. Aby uzyskać dostęp do symulatora, otwórz adres URL w wynikach polecenia.
$ gactions deploy preview
Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview