Aktionen für Google Assistant mit dem Actions SDK erstellen (Level 1)

1. Übersicht

Warnung: Konversationsaktionen wurden am 13. Juni 2023 eingestellt. Weitere Informationen finden Sie unter Einstellung der Konversationsaktionen.

Mit der Google Assistant-Entwicklerplattform können Sie Software erstellen, um die Funktionalität von Google Assistant, einem virtuellen persönlichen Assistenten, auf über einer Milliarde Geräten zu erweitern, darunter intelligente Lautsprecher, Smartphones, Autos, Fernseher und Kopfhörer. Nutzer interagieren mit Assistant, um Dinge zu erledigen, z. B. Lebensmittel zu kaufen oder eine Fahrt zu buchen. Als Entwickler können Sie mit der Assistant-Entwicklerplattform ganz einfach ansprechende und effektive Unterhaltungen zwischen Nutzern und Ihrem eigenen Drittanbieter-Fulfillment-Dienst erstellen und verwalten.

In diesem Codelab werden Konzepte für Anfänger zur Entwicklung mit dem Actions SDK für Google Assistant behandelt. Sie benötigen keine Vorkenntnisse mit der Plattform, um es durchzuarbeiten. In diesem Codelab erstellen Sie eine einfache Action für Google Assistant, die Nutzern ihr Glück vorhersagt, wenn sie ihr Abenteuer im mystischen Land Gryffinberg beginnen. Im Codelab zum Actions SDK auf Stufe 2 wird diese Action weiter ausgebaut, um das Glück des Nutzers basierend auf seiner Eingabe anzupassen.

Aufgaben

In diesem Codelab erstellen Sie eine einfache Aktion mit den folgenden Funktionen:

• Mit einer Begrüßungsnachricht auf Nutzer reagieren
• Dem Nutzer wird eine Frage gestellt und es wird angemessen auf die Auswahl des Nutzers reagiert.
• Bietet Vorschlagschips, auf die Nutzer klicken können, um Eingaben zu machen
• Die Begrüßungsnachricht für den Nutzer wird je nachdem, ob er ein wiederkehrender Nutzer ist, angepasst.

Wenn Sie dieses Codelab abgeschlossen haben, hat Ihre fertige Action den folgenden Unterhaltungsablauf (der Text neben dem Mikrofon stellt die Eingabe des Nutzers dar, während der Text neben dem Lautsprecher die Antwort der Action darstellt):

Lerninhalte

• Projekt in der Actions Console erstellen
• Das gactions-Tool verwenden, um Ihr Action-Projekt zwischen der Actions Console und Ihrem lokalen Dateisystem zu übertragen
• Aufforderung an den Nutzer senden, nachdem er Ihre Action aufgerufen hat
• Nutzereingaben verarbeiten und eine Antwort zurückgeben
• Action mit dem Actions-Simulator testen
• Auftragsausführung mit dem Cloud Functions-Editor implementieren

Voraussetzungen

Die folgenden Tools müssen in Ihrer Umgebung vorhanden sein:

• Eine IDE oder ein Texteditor Ihrer Wahl
• Ein Terminal zum Ausführen von Shell-Befehlen für Node.js und npm
• Ein Webbrowser, z. B. Google Chrome

Wenn Sie lieber mit visuellen Tools arbeiten, um Actions zu erstellen, sollten Sie stattdessen das Codelab zum Erstellen von Actions für Google Assistant mit Actions Builder (Level 1) durcharbeiten. Dort wird dieselbe Action mit der Actions Builder IDE in der Konsole erstellt.

2. Einrichten

In den folgenden Abschnitten wird beschrieben, wie Sie Ihre Entwicklungsumgebung einrichten und Ihr Actions-Projekt erstellen.

Google-Berechtigungseinstellungen prüfen

Um die Aktion zu testen, die Sie in diesem Codelab erstellen, müssen Sie die erforderlichen Berechtigungen aktivieren, damit der Simulator auf Ihre Aktion zugreifen kann.

So aktivieren Sie Berechtigungen:

1. Rufen Sie die Aktivitätseinstellungen auf.
2. Melden Sie sich mit Ihrem Google-Konto an, falls Sie das noch nicht getan haben.
3. Aktivieren Sie die folgenden Berechtigungen:

• Web- & App-Aktivitäten
• Setzen Sie unter Web- & App-Aktivitäten ein Häkchen bei Auch den Chrome-Verlauf sowie Aktivitäten auf Websites, in Apps und auf Geräten berücksichtigen, die Google-Dienste nutzen**.**

Actions-Projekt erstellen

Ihr Actions-Projekt ist ein Container für Ihre Action.

So erstellen Sie Ihr Actions-Projekt für dieses Codelab:

1. Öffnen Sie die Actions Console.
2. Klicken Sie auf Neues Projekt.
3. Geben Sie einen Projektnamen ein, z. B. actions-codelab. Der Name dient nur zu Ihrer internen Referenz. Später können Sie einen externen Namen für Ihr Projekt festlegen.)

4. Klicken Sie auf Projekt erstellen.
5. Wählen Sie auf dem Bildschirm What kind of Action do you want to build? (Welche Art von Action möchten Sie erstellen?) die Karte Custom (Benutzerdefiniert) aus.
6. Klicken Sie auf Weiter.
7. Wählen Sie auf dem Bildschirm Wie möchten Sie das Projekt erstellen? die Karte Leeres Projekt aus.
8. Klicken Sie auf Start building (Mit der Entwicklung beginnen).

Projekt-ID für Ihre Aktion speichern

Die Projekt-ID ist eine eindeutige Kennung für Ihre Aktion. Sie benötigen Ihre Projekt-ID für mehrere Schritte in diesem Codelab.

So rufen Sie Ihre Projekt-ID ab:

1. Klicken Sie in der Actions Console auf das Dreipunkt-Menü (Symbol hier einfügen).
2. Klicken Sie auf Projekteinstellungen.

3. Kopieren Sie die Projekt-ID**.**

Rechnungskonto verknüpfen

Wenn Sie noch kein Rechnungskonto haben, müssen Sie eines erstellen und es mit Ihrem Projekt in Google Cloud verknüpfen, um Ihr Fulfillment später mit Cloud Functions bereitzustellen.

So verknüpfen Sie ein Rechnungskonto mit Ihrem Projekt:

1. Rufen Sie die Seite „Abrechnung“ in der Google Cloud Platform auf.
2. Klicken Sie auf Rechnungskonto hinzufügen oder Konto erstellen.
3. Geben Sie Ihre Zahlungsinformationen ein.
4. Klicken Sie auf Jetzt kostenlos testen oder Senden und Abrechnung aktivieren.
5. Rufen Sie die Seite „Abrechnung“ in der Google Cloud Platform auf.
6. Klicken Sie auf den Tab Meine Projekte.
7. Klicken Sie neben dem Actions-Projekt für das Codelab unter Aktionen auf das Dreipunkt-Menü.
8. Klicken Sie auf Abrechnung ändern.
9. Wählen Sie im Drop-down-Menü das von Ihnen konfigurierte Rechnungskonto aus.
10. Klicken Sie auf Konto festlegen.

Folgen Sie der Anleitung im Abschnitt „Projekt bereinigen“ am Ende dieses Codelabs, um Kosten zu vermeiden.

gactions-Befehlszeilentool installieren

In diesem Codelab verwenden Sie das gactions-Befehlszeilentool (CLI), um Ihr Actions-Projekt zwischen der Actions Console und Ihrem lokalen Dateisystem zu synchronisieren.

Schlüsselbegriff:

• gactions-Befehlszeile: Ein Tool, mit dem Sie Aktionsprojektdateien initialisieren, Updates an die Actions Console senden und Aktionsprojekte bereitstellen können.

Folgen Sie der Anleitung unter gactions-Befehlszeilentool installieren, um die gactions CLI zu installieren.

Actions-Projekt herunterladen

Laden Sie Ihr Actions-Projekt aus der Actions Console herunter, um mit der Entwicklung Ihrer Aktion zu beginnen.

So laden Sie Ihr Actions-Projekt herunter:

1. Führen Sie die folgenden Befehle aus, um ein neues Verzeichnis zu erstellen und in dieses Verzeichnis zu wechseln:

mkdir myproject
cd myproject

2. Führen Sie den folgenden Befehl aus, um die Konfiguration Ihres Actions-Projekts in Ihr lokales Dateisystem zu kopieren:

gactions pull --project-id <projectID>

Dateistruktur

Das Actions-Projekt, das Sie aus der Actions Console herunterladen, wird in einer YAML-Dateistruktur dargestellt. Das folgende Bild zeigt eine allgemeine Darstellung der Dateistruktur:

Die Dateistruktur besteht aus folgenden Elementen:

• actions/: Stellt Ihr Actions-Projekt dar. Das System ruft actions.yaml auf, wenn Ihre Action aufgerufen wird. Dadurch wird dann die Datei custom/global/actions.intent.MAIN.yaml aufgerufen.
• custom/: Das Verzeichnis, in dem Sie Ihre Aktion bearbeiten.
• global/: Dieses Verzeichnis enthält System-Intents, die der Plattform automatisch zu Ihrem Projekt hinzugefügt werden. Weitere Informationen zu System-Intents finden Sie später in diesem Codelab.
• manifest.yaml: Eine Datei, die übertragbare Informationen enthält, die nicht spezifisch für ein bestimmtes Projekt sind und zwischen Projekten verschoben werden können.
• settings/: Stellt die Einstellungen eines Actions-Projekts dar, z. B. den Anzeigenamen, das Standardschema und die Kategorie.

3. Unterhaltung starten

Nutzer starten die Unterhaltung mit Ihrer Aktion über die Invocation. Wenn Sie beispielsweise eine Aktion mit dem Namen MovieTime haben, können Nutzer Ihre Aktion aufrufen, indem sie z. B. Hey Google, sprich mit MovieTime sagen. MovieTime ist dabei der Anzeigename. Ihre Action muss einen Anzeigenamen haben, wenn Sie sie in der Produktion bereitstellen möchten. Zum Testen Ihrer Action müssen Sie den Anzeigenamen jedoch nicht definieren. Stattdessen können Sie im Simulator den Satz Talk to my test app verwenden, um Ihre Aktion aufzurufen. Weitere Informationen zum Simulator finden Sie weiter unten in diesem Abschnitt.

Sie müssen den Hauptaufruf bearbeiten, um festzulegen, was passiert, nachdem ein Nutzer Ihre Action aufgerufen hat.

Schlüsselbegriff:

• Hauptaufruf: Ein Einstiegspunkt für Nutzer, um Unterhaltungen mit Ihrer Aktion zu starten. Wenn Nutzer einen ähnlichen Satz wie „Hey Google, sprich mit <Anzeigename>“ sagen, wird der Hauptaufruf ausgelöst und es wird auf den Nutzer reagiert.

Standardmäßig wird in Ihrer Aktion ein allgemeiner Prompt angezeigt, wenn Ihr Aufruf ausgelöst wird („Beginnen Sie mit der Entwicklung Ihrer Aktion, indem Sie den Hauptaufruf definieren.“).

Schlüsselbegriff:

• Aufforderung: Definiert, was Ihre Action als Antwort an Nutzer sendet. Prompts können einfache Text- und Sprachantworten oder Rich-Media-Nachrichten wie Karten und Bilder sein.

Mit dem speziellen Prompt Canvas können Sie dem Nutzer Vollbildgrafiken zurückgeben. Weitere Informationen zu Canvas finden Sie in der Interactive Canvas-Dokumentation.

Im nächsten Abschnitt passen Sie den Prompt für den Hauptaufruf in der Datei custom/global/actions.intent.MAIN.yaml an.

Hauptaufruf einrichten

Sie können den Hauptaufruf-Prompt in der Datei actions.intent.MAIN.yaml bearbeiten.

So ändern Sie den Prompt, den Ihre Action an den Nutzer zurücksendet, wenn er Ihre Action aufruft:

1. Öffnen Sie custom/global/actions.intent.MAIN.yaml in einem Texteditor.
2. Ersetzen Sie den Text im Feld speech (Start building your action...) durch die folgende Willkommensnachricht: 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. Speichern Sie die Datei.

Hauptaufruf im Simulator testen

Die Actions-Konsole bietet ein Webtool zum Testen Ihrer Aktion, den Simulator. Die Benutzeroberfläche simuliert Hardwaregeräte und ihre Einstellungen, sodass Sie mit Ihrer Action interagieren können, als würde sie auf einem Smart Display, Smartphone, Lautsprecher oder KaiOS ausgeführt.

Die neuesten Informationen zur Verwendung des Actions Console-Simulators und zur Fehlerbehebung bei den folgenden Schritten finden Sie auf der Seite Simulator.

Wenn Sie Ihre Action aufrufen, sollte sie jetzt mit dem benutzerdefinierten Prompt antworten, den Sie hinzugefügt haben („A wondrous greeting, adventurer!...“).

Mit dem Befehl gactions deploy preview können Sie Ihre Aktion in der Konsole testen, ohne die Version Ihres Aktionsprojekts aktualisieren zu müssen. Wenn Sie diesen Befehl ausführen, werden keine Änderungen, die Sie in Ihrem lokalen Dateisystem vornehmen, auf bereitgestellte Versionen Ihres Actions-Projekts übertragen. Sie können sie jedoch in einer Vorschauversion testen.

So testen Sie den Hauptaufruf Ihrer Aktion im Simulator:

1. Führen Sie den folgenden Befehl im Terminal aus, um Ihr Projekt zum Testen in der Actions Console bereitzustellen:

gactions deploy preview

Wenn Sie diesen Befehl ausführen, werden Sie möglicherweise über Validierungsprobleme benachrichtigt. Wenn Ihre Dateien übertragen wurden, können Sie diese Meldung ignorieren.

Die Ausgabe sollte in etwa so aussehen:

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

2. Kopieren Sie die angegebene URL und fügen Sie sie in einen Browser ein.
3. Geben Sie zum Aufrufen Ihrer Aktion im Simulator Talk to my test app in das Feld Input ein und drücken Sie Enter.

Tipp:Sie können auch unter Vorschläge auf den Vorschlagschip Mit meiner Test-App sprechen klicken. Das wird genauso verarbeitet wie gesprochene oder eingegebene Nutzereingaben.

Alternativ können Sie auf das Mikrofonsymbol klicken und Mit meiner Test-App sprechen sagen, um Ihre Aktion aufzurufen.

Wenn Sie den Hauptaufruf Ihrer Aktion auslösen, antwortet Assistant mit Ihrer benutzerdefinierten Begrüßungsnachricht. An diesem Punkt endet die Unterhaltung, nachdem der Assistant mit einer Begrüßung geantwortet hat. Im nächsten Abschnitt ändern Sie Ihre Aktion so, dass die Unterhaltung fortgesetzt wird.

Ereignisprotokolle ansehen

Wenn Sie sich in der Actions Console auf dem Tab Test befinden, werden im Bereich die Ereignisprotokolle angezeigt, in denen der Unterhaltungsverlauf als Ereignisprotokolle dargestellt wird. In jedem Ereignisprotokoll werden die Ereignisse angezeigt, die während dieser Unterhaltungsrunde stattfinden.

Ihre Action hat derzeit ein Ereignisprotokoll, in dem sowohl die Eingabe des Nutzers (Talk to my test app) als auch die Antwort Ihrer Action angezeigt werden. Der folgende Screenshot zeigt das Ereignisprotokoll Ihrer Aktion:

Wenn Sie im Ereignisprotokoll auf den Abwärtspfeil neben Talk to my test app klicken, sehen Sie die Ereignisse, die in dieser Konversationsrunde aufgetreten sind, in chronologischer Reihenfolge:

• userInput: Entspricht der Eingabe des Nutzers („Sprich mit meiner Test-App“)
• interactionMatch: Entspricht der Hauptaufrufantwort Ihrer Aktion, die durch die Eingabe des Nutzers ausgelöst wurde. Wenn Sie diese Zeile durch Klicken auf den Pfeil maximieren, sehen Sie den Prompt, den Sie für den Hauptaufruf hinzugefügt haben (A wondrous greeting, adventurer!...).
• endConversation: Entspricht dem ausgewählten Übergang im Intent Main invocation, der die Unterhaltung derzeit beendet. Im nächsten Abschnitt dieses Codelabs erfahren Sie mehr über Übergänge.

Ereignisprotokolle geben Aufschluss darüber, wie Ihre Aktion funktioniert. Sie sind nützliche Tools zur Fehlerbehebung, falls Probleme auftreten. Wenn Sie die Details eines Ereignisses aufrufen möchten, klicken Sie auf den Pfeil neben dem Ereignisnamen (siehe Screenshot unten):

4. Unterhaltung für Ihre Aktion erstellen

Nachdem Sie definiert haben, was passiert, nachdem ein Nutzer Ihre Aktion aufgerufen hat, können Sie den Rest der Unterhaltung Ihrer Aktion erstellen. Bevor Sie mit diesem Codelab fortfahren, sollten Sie sich mit den folgenden Begriffen vertraut machen, um zu verstehen, wie die Unterhaltung Ihrer Action funktioniert:

Wichtige Begriffe:

• Szene: Ein Baustein für Ihre Aktion, der Nutzereingaben verarbeitet und in der Regel die Antwort an den Nutzer generiert. Benutzerdefinierte Intents aktivieren oft andere Szenen, aber Szenen können auch auf andere Weise aktiviert werden.
• Benutzerdefinierter Intent: Definiert die Nutzereingabe, die die Action verstehen kann. Sie definieren die Trainingsformulierungen für diese Intents. Wenn Nutzer etwas sagen, das mit einer Trainingsformulierung übereinstimmt oder ihr ähnelt, wird der entsprechende Intent zugeordnet.
• Trainingsformulierungen: Beispiele dafür, was ein Nutzer sagen könnte, damit ein Intent zugeordnet wird. Die NLU-Engine (Natural Language Understanding) von Assistant erweitert diese Trainingsformulierungen automatisch um ähnliche Formulierungen.
• Übergang: Definiert, zu welcher Szene gewechselt werden soll, wenn die Bedingung erfüllt ist.

Ihre Aktion kann eine oder mehrere Szenen haben. Sie müssen jede Szene aktivieren, bevor sie ausgeführt werden kann. Die Action, die Sie in diesem Codelab erstellen, hat nur eine Szene mit dem Titel Start. Die häufigste Methode zum Aktivieren einer Szene besteht darin, Ihre Aktion so zu konfigurieren, dass bei einer Nutzereingabe, die einem Intent in einer Szene entspricht, dieser Intent den Übergang zu einer anderen Szene auslöst und diese aktiviert.

Stellen Sie sich beispielsweise eine hypothetische Action vor, die dem Nutzer Fakten über Tiere liefert. Wenn der Nutzer diese Aktion aufruft, wird der Intent Main invocation abgeglichen und löst den Übergang zu einer Szene namens Facts. aus. Durch diesen Übergang wird die Szene Facts aktiviert, die den folgenden Prompt an den Nutzer sendet: Would you like to hear a fact about cats or dogs?. In der Szene Facts befindet sich ein benutzerdefinierter Intent namens Cat, der Trainingsformulierungen enthält, die der Nutzer sagen könnte, um einen Katzenfakt zu hören, z. B. „Ich möchte einen Katzenfakt hören“ oder „Katze“. Wenn der Nutzer nach einem Katzenfakt fragt, wird der Intent Cat abgeglichen und löst einen Übergang zu einer Szene namens Cat fact. aus. Die Szene Cat fact wird aktiviert und sendet einen Prompt an den Nutzer, der einen Katzenfakt enthält.

Abbildung 1. Der Ablauf eines typischen Konversationsvorgangs in einer Action, die mit dem Actions SDK erstellt wurde.

Szenen, Intents und Übergänge bilden zusammen die Logik für Ihren Dialog und definieren die verschiedenen Pfade, die Nutzer im Dialog Ihrer Aktion durchlaufen können. Im folgenden Abschnitt erstellen Sie eine Szene und definieren, wie sie aktiviert wird, nachdem ein Nutzer Ihre Action aufgerufen hat.

Übergang vom Hauptaufruf zur Szene

In diesem Abschnitt erstellen Sie eine neue Szene namens Start, in der der Nutzer gefragt wird, ob er sein Horoskop lesen lassen möchte. Außerdem fügen Sie einen Übergang vom Hauptaufruf zur neuen Start-Szene hinzu.

So erstellen Sie diese Szene und fügen ihr eine Überblendung hinzu:

1. Öffnen Sie custom/global/actions.intent.MAIN.yaml in einem Texteditor.
2. Ersetzen Sie den Text im Feld transitionToScene (actions.scene.END_CONVERSATION) durch Folgendes: 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

Dadurch wird Ihre Aktion angewiesen, vom Hauptaufruf zur Szene Start zu wechseln.

3. Speichern Sie die Datei.
4. Erstellen Sie im Terminal ein neues Verzeichnis scenes im Verzeichnis custom:

mkdir custom/scenes 

5. Erstellen Sie im Verzeichnis scenes eine neue Datei mit dem Namen Start.yaml, die die Szene start in Ihrer Aktion darstellt:

touch custom/scenes/Start.yaml 

6. Öffnen Sie Start.yaml in einem Texteditor.
7. Fügen Sie den folgenden Code in die Start.yaml-Datei ein:

Start.yaml

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

Im Code der Datei Start.yaml gibt es ein Feld namens onEnter. Dies ist die erste Phase, die im Lebenszyklus einer Szene ausgeführt wird.

Wichtige Begriffe:

• OnEnter:Die Phase, die ausgeführt wird, wenn eine Szene aktiviert wird. OnEnter definiert, was passiert, wenn der Nutzer die Szene betritt.

In diesem Fall wird der Prompt (Before you continue on your quest...) der Prompt-Warteschlange hinzugefügt, wenn der Nutzer die Start-Szene zum ersten Mal aufruft.

Wichtige Begriffe:

• Prompt-Warteschlange:Prompts werden in einer Prompt-Warteschlange aneinander angehängt. Bevor der Nutzer antworten kann, präsentiert Assistant ihm alle Prompts in der Prompt-Warteschlange.

Vorschlags-Chips hinzufügen

Vorschlagschips bieten dem Nutzer anklickbare Vorschläge, die von Ihrer Action als Nutzereingabe verarbeitet werden. In diesem Abschnitt fügen Sie die Vorschlags-Chips Yes und No hinzu, die unter dem gerade konfigurierten Prompt (Before you continue on your quest, would you like your fortune told?) angezeigt werden, um Nutzer auf Geräten mit Bildschirmen zu unterstützen.

So fügen Sie dem Prompt der Szene Start Vorschlagschips hinzu:

1. Aktualisieren Sie den Code in Start.yaml, sodass er dem folgenden Code-Snippet entspricht. Dieses enthält den Code zum Konfigurieren von Vorschlagschips:

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. Speichern Sie die Datei.

Action im Simulator testen

An diesem Punkt sollte Ihre Aktion von der Hauptaufrufung zur Start-Szene übergehen und den Nutzer fragen, ob er sein Horoskop lesen möchte. Außerdem sollten Vorschlagschips auf dem simulierten Display angezeigt werden.

So testen Sie Ihre Action im Simulator:

1. Führen Sie im Terminal den folgenden Befehl aus:

gactions deploy preview

Die Ausgabe sollte in etwa so aussehen:

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

2. Kopieren Sie die angegebene URL und fügen Sie sie in einen Browser ein.
3. Klicken Sie auf Test, um den Simulator aufzurufen.
4. Geben Sie Talk to my test app in das Feld Eingabe ein und drücken Sie Enter. Ihre Aktion sollte mit dem Prompt Main invocation und dem zusätzlichen Szenen-Prompt Start antworten: „Möchtest du, dass dir die Zukunft vorausgesagt wird, bevor du deine Suche fortsetzt?“. Außerdem sollten die Vorschlagschips angezeigt werden.

Der folgende Screenshot zeigt diese Interaktion:

Im Ereignisprotokoll wird jede Ihrer Simulatorinteraktionen in der aktuellen Sitzung aufgezeichnet. Das Ereignisprotokoll aus Ihren Tests weiter oben in diesem Codelab wird also als erstes Ereignisprotokoll angezeigt. Wenn Sie Ihre Ereignisprotokolle löschen möchten, klicken Sie auf Test zurücksetzen.

5. Klicken Sie auf den Vorschlagschip Ja oder Nein, um auf den Prompt zu antworten. Sie können auch Ja oder Nein sagen oder Yes oder No in das Feld Eingabe eingeben.

Wenn Sie auf den Prompt antworten, antwortet Ihr Action mit einer Meldung, dass es Ihre Eingabe nicht versteht: „Das habe ich nicht verstanden. Kannst du es noch einmal versuchen?“ Da Sie Ihre Aktion noch nicht so konfiguriert haben, dass sie die Eingaben Ja oder Nein versteht und darauf reagiert, wird Ihre Eingabe einem NO_MATCH-Intent zugeordnet.

Wichtige Begriffe:

• NO_MATCH: Ein Auffang-Intent, der zugeordnet wird, wenn der Nutzer etwas sagt, das keinem anderen Intent in Ihrer Action zugeordnet werden kann.
• System-Intent: Ein Intent, der standardmäßig konfiguriert ist und häufige Systemereignisse verarbeitet, z. B. wenn ein Nutzer keine Eingabe macht. NO_MATCH und der Intent, der mit dem Hauptaufruf verknüpft ist, sind Beispiele für System-Intents.

Standardmäßig werden mit dem System-Intent NO_MATCH generische Antworten bereitgestellt. Sie können diese Antworten jedoch anpassen, um dem Nutzer mitzuteilen, dass Sie seine Eingabe nicht verstanden haben. Assistant beendet die Unterhaltung des Nutzers mit Ihrer Aktion, wenn die Nutzereingabe dreimal nicht zugeordnet werden kann.

Fügen Sie die Intents yes und no hinzu.

Da Nutzer jetzt auf die Frage Ihrer Action antworten können, können Sie Ihre Action so konfigurieren, dass sie die Antworten der Nutzer („Ja“ oder „Nein“) versteht. In den folgenden Abschnitten erstellen Sie benutzerdefinierte Intents, die abgeglichen werden, wenn der Nutzer Ja oder Nein sagt, und fügen diese Intents der Start-Szene hinzu.

yes-Intent erstellen

So erstellen Sie den yes-Intent:

1. Erstellen Sie im Terminal im Verzeichnis custom ein neues Verzeichnis mit dem Namen intents:

mkdir custom/intents 

2. Erstellen Sie im Verzeichnis intents eine neue Datei mit dem Namen yes.yaml:

touch custom/intents/yes.yaml

3. Öffnen Sie yes.yaml in einem Texteditor.
4. Fügen Sie das folgende Code-Snippet mit Trainingsformulierungen in yes.yaml ein:

yes.yaml

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

5. Speichern Sie die Datei.

Füge der Szene Start die Absicht yes hinzu.

Die Action kann jetzt erkennen, wenn ein Nutzer eine „Ja“-Absicht äußert. Sie können den benutzerdefinierten yes-Intent der Start-Szene hinzufügen, da der Nutzer auf den Start-Prompt („Möchtest du, bevor du deine Suche fortsetzt, dass dir die Zukunft vorausgesagt wird?“) antwortet.

So fügen Sie diesen benutzerdefinierten Intent der Szene Start hinzu:

1. Öffnen Sie custom/scenes/Start.yaml in einem Texteditor.
2. Fügen Sie den intentEvents- und den yes-Handler am Ende der Datei Start.yaml hinzu:

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

Wenn der Intent yes erkannt wird, wird der Prompt „Your future depends on the item you choose to use for your quest...“ (Deine Zukunft hängt von dem Gegenstand ab, den du für deine Quest auswählst) der Prompt-Warteschlange hinzugefügt. Die Szene Start geht dann in die Systemszene actions.scene.END_CONVERSATION über, in der die Prompts in der Prompt-Warteschlange bereitgestellt und das Gespräch beendet wird.

yes-Intent im Simulator testen

An diesem Punkt versteht Ihre Aktion, wann der Nutzer sein Horoskop hören möchte, und gibt die entsprechende Antwort zurück.

So testen Sie diesen Intent im Simulator:

1. Führen Sie im Terminal den folgenden Befehl aus:

gactions deploy preview

Die Ausgabe sollte in etwa so aussehen:

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

2. Kopieren Sie die angegebene URL und fügen Sie sie in einen Browser ein.
3. Klicken Sie auf Test, um den Simulator aufzurufen.
4. Wenn Sie Ihre Aktion im Simulator testen möchten, geben Sie Talk to my test app in das Feld Eingabe ein und drücken Sie Enter.
5. Geben Sie Yes in das Feld Eingabe ein und drücken Sie Enter. Alternativ können Sie auf den Vorschlagschip Ja klicken.

Ihre Aktion antwortet dem Nutzer und teilt ihm mit, dass sein Glück von der gewählten Hilfe abhängt. Ihre Aktion beendet dann die Sitzung, da Sie den End conversation-Übergang für die yes-Absicht konfiguriert haben.

no-Intent erstellen

Jetzt können Sie den Intent no erstellen, damit Ihre Action den Nutzer versteht und darauf reagieren kann, wenn er sein Horoskop nicht hören möchte.

So erstellen Sie diesen Intent:

1. Erstellen Sie im Terminal eine neue Datei mit dem Namen no.yaml im Verzeichnis intents:

touch custom/intents/no.yaml

2. Öffnen Sie no.yaml in einem Texteditor.
3. Fügen Sie die folgenden Trainingsformulierungen in die Datei no.yaml ein:

no.yaml

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

4. Speichern Sie die Datei.

Füge der Szene Start die Absicht no hinzu.

Die Action kann jetzt verstehen, wenn ein Nutzer „Nein“ oder etwas Ähnliches wie „Nein“ sagt, z. B. „Nee“. Sie müssen der Start-Szene den benutzerdefinierten Intent no hinzufügen, da der Nutzer auf den Start-Prompt („Möchtest du, dass dir die Zukunft vorausgesagt wird, bevor du deine Suche fortsetzt?“) antwortet.

So fügen Sie diesen Intent für die Szene Start hinzu:

1. Öffnen Sie custom/scenes/Start.yaml in einem Texteditor.
2. Fügen Sie in Start.yaml den folgenden no-Handler unter dem yes-Handler hinzu:

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. Speichern Sie die Datei.

no-Intent im Simulator testen

An diesem Punkt versteht Ihre Aktion, wenn der Nutzer sein Horoskop nicht hören möchte, und gibt die entsprechende Antwort zurück.

So testen Sie diesen Intent im Simulator:

1. Führen Sie im Terminal den folgenden Befehl aus:

gactions deploy preview

Die Ausgabe sollte in etwa so aussehen:

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

2. Kopieren Sie die angegebene URL und fügen Sie sie in einen Browser ein.
3. Klicken Sie auf Test, um den Simulator aufzurufen.
4. Geben Sie Talk to my test app in das Feld Eingabe ein und drücken Sie Enter.
5. Geben Sie No in das Feld Eingabe ein und drücken Sie Enter. Alternativ können Sie auf den Vorschlagschip No klicken.

Anstatt dem Nutzer sein Glück vorherzusagen, wünscht deine Aktion ihm Glück auf seinem Weg. Ihre Aktion beendet dann die Sitzung, da Sie den End conversation-Übergang für die no-Absicht konfiguriert haben.

5. Auftragsausführung implementieren

Derzeit sind die Antworten Ihrer Action statisch. Wenn eine Szene mit einem Prompt aktiviert wird, sendet Ihre Action jedes Mal denselben Prompt. In diesem Abschnitt implementieren Sie die Auftragsausführung, die die Logik zum Erstellen einer dynamischen Konversationsantwort enthält.

Schlüsselbegriff:

• Fulfillment: Der Code, der die Logik für Ihre Aktion enthält. Ein Webhook löst Aufrufe an Ihre Auftragsausführung basierend auf Ereignissen aus, die in Ihren Actions auftreten.

In der Auftragsausführung wird ermittelt, ob der Nutzer ein wiederkehrender oder ein neuer Nutzer ist, und die Begrüßungsnachricht der Action wird für wiederkehrende Nutzer angepasst. Die Begrüßungsnachricht für wiederkehrende Nutzer ist kürzer und erkennt die Rückkehr des Nutzers an: „Ein wundervoller Gruß, Abenteurer! Willkommen zurück im sagenhaften Land Gryffinberg!

In diesem Codelab verwenden Sie den Cloud Functions-Editor, um Ihren Auftragsausführungscode zu bearbeiten und bereitzustellen.

Schlüsselbegriff:

• Cloud Functions-Editor: Ein integrierter Editor für Actions-Projekte, mit dem Sie Ihren Auftragsausführungscode mit Cloud Functions für Firebase bearbeiten und bereitstellen können.

Ihre Action kann Webhooks auslösen, die Ihr Fulfillment über ein Ereignis informieren, das während eines Aufrufs oder bestimmter Teile der Ausführung einer Szene auftritt. Wenn ein Webhook ausgelöst wird, sendet Ihre Aktion eine Anfrage mit einer JSON-Nutzlast an Ihre Auftragsausführung. Diese enthält den Namen des Handlers, der zum Verarbeiten des Ereignisses verwendet werden soll. Dieser Handler führt eine bestimmte Logik aus und gibt eine entsprechende JSON-Antwort zurück.

Auftragsausführung erstellen

In diesem Abschnitt ändern Sie die Auftragsausführung so, dass für wiederkehrende und neue Nutzer unterschiedliche Aufforderungen generiert werden, wenn sie Ihre Action aufrufen.

So fügen Sie diese Logik Ihrem Fulfillment hinzu:

1. Achten Sie darauf, dass Sie sich im Terminal im Stammverzeichnis Ihres Projekts befinden, und erstellen Sie ein neues Verzeichnis mit dem Namen webhooks:

mkdir webhooks 

2. Erstellen Sie im Verzeichnis webhooks eine neue Datei mit dem Namen ActionsOnGoogleFulfillment.yaml:

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. Öffnen Sie ActionsOnGoogleFulfillment.yaml in einem Texteditor.
4. Fügen Sie der Datei ActionsOnGoogleFulfillment.yaml den Handler greeting und den Inhalt inlineCloudFunction hinzu:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

In der Datei ActionsOnGoogleFulfillment.yaml werden Ihre Webhook-Handler (z. B. der greeting-Handler) definiert und Ihrer Action wird mitgeteilt, dass Cloud Functions als Webhook-Endpunkt verwendet werden soll.

5. Erstellen Sie im Verzeichnis webhooks ein neues Verzeichnis ActionsOnGoogleFulfillment:

mkdir webhooks/ActionsOnGoogleFulfillment

6. Erstellen Sie im Verzeichnis ActionsOnGoogleFulfillment eine neue Datei mit dem Namen index.js:

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. Öffnen Sie index.js in einem Texteditor.
8. Fügen Sie den folgenden Code zu index.js hinzu:

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);

Mit diesem Code wird der greeting-Handler definiert, der die entsprechende Begrüßung an den

Nutzer.

9. Speichern Sie die Datei.
10. Erstellen Sie im Verzeichnis ActionsOnGoogleFulfillment eine neue Datei mit dem Namen package.json:

touch webhooks/ActionsOnGoogleFulfillment/package.json

In der Datei package.json werden Abhängigkeiten und andere Metadaten für Ihren Webhook angegeben.

11. Öffnen Sie package.json in einem Texteditor.
12. Kopieren Sie den Code aus diesem GitHub-Repository und fügen Sie ihn in die Datei package.json ein.
13. Speichern Sie die Datei.

Code verstehen

Ihre Auftragsausführung, die die Actions on Google-Bibliothek zur Auftragsausführung für Node.js verwendet, antwortet auf HTTP-Anfragen von Google Assistant.

Im vorherigen Code-Snippet definieren Sie den greeting-Handler, der prüft, ob der Nutzer die Action zuvor mit der lastSeenTime-Eigenschaft besucht hat. Wenn die Eigenschaft lastSeenTime nicht definiert ist, ist der Nutzer neu und erhält die für neue Nutzer vorgesehene Begrüßung. Andernfalls wird die Rückkehr des Nutzers bestätigt und eine angepasste Begrüßung generiert.

Hauptaufruf aktualisieren, um einen Webhook auszulösen

Nachdem Sie die greeting-Funktion definiert haben, können Sie den greeting-Ereignishandler in Ihrem Hauptaufruf-Intent konfigurieren, damit Ihre Action weiß, dass sie diese Funktion aufrufen muss, wenn der Nutzer Ihre Action aufruft.

So konfigurieren Sie Ihre Aktion, um den neuen greeting-Handler aufzurufen:

1. Öffnen Sie custom/global/actions.intent.MAIN.yaml in einem Texteditor.
2. Ersetzen Sie den Code in actions.intent.MAIN.yaml durch den folgenden Code:

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. Speichern Sie die Datei.

Wenn Ihr Haupt-Intent für den Aufruf abgeglichen wird, wird der greeting-Webhook-Handler aufgerufen.

Aktualisierten Hauptaufruf im Simulator testen

So testen Sie Ihre Action im Simulator:

1. Führen Sie im Terminal den folgenden Befehl aus:

Da mit diesem Befehl der Webhook bereitgestellt und Abhängigkeiten installiert werden, kann er länger als die vorherigen Befehle dauern.

gactions deploy preview

Wenn Sie einen 403-Fehler zur Cloud Build API oder einen 403-Fehler zum Verknüpfen Ihres Rechnungskontos erhalten, lesen Sie den Abschnitt Abrechnung für ein Projekt aktivieren, deaktivieren oder ändern. Wenn Sie Cloud Functions für die Bereitstellung verwenden möchten, müssen Sie Ihrem Projekt in Google Cloud ein Rechnungskonto zuordnen. Führen Sie gactions deploy preview noch einmal aus, nachdem Sie ein Rechnungskonto verknüpft haben. Folgen Sie der Anleitung im Abschnitt „Projekt bereinigen“ am Ende dieses Codelabs, um Kosten zu vermeiden.

Die Ausgabe sollte in etwa so aussehen:

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

2. Kopieren Sie die angegebene URL und fügen Sie sie in einen Browser ein.
3. Wenn Sie Ihre Aktion im Simulator testen möchten, geben Sie Talk to my test app in das Feld Eingabe ein und drücken Sie Enter.

Da Sie Ihre Aktion bereits früher in diesem Codelab getestet haben, sind Sie kein neuer Nutzer. Daher erhalten Sie die folgende verkürzte Begrüßung: Ein herzliches Hallo, Abenteurer! Willkommen zurück im sagenumwobenen Land Gryffinberg!…“

6. Aktionen mit Actions Builder visualisieren

Das Actions SDK ist mit einer webbasierten IDE namens Actions Builder kompatibel, die in die Actions Console integriert ist. Mit dem Befehl gactions push können Sie Ihr lokales Dateisystem in den Entwurf Ihrer Action in der Console übertragen. Im Gegensatz zu gactions deploy preview, mit dem Sie Ihre Action nur im Simulator testen können, werden mit gactions push alle Inhalte aus Ihren lokalen Dateien in Actions Builder übertragen.

In der Actions Console wird die Konfiguration Ihrer Aktion visuell dargestellt. Es kann hilfreich sein, sich Ihre Aktion während der Entwicklung visuell darstellen zu lassen. Das hat keine Auswirkungen auf die Version Ihrer Aktion, die für Tests bereitgestellt wird.

Wenn Sie gactions push ausführen, wird der aktuelle Entwurf Ihres Actions-Projekts überschrieben, wenn Sie gemeinsam daran arbeiten.

So übertragen Sie Ihr Actions-Projekt und rufen es in der Actions Console auf:

1. Führen Sie im Terminal den folgenden Befehl aus, um Ihr Projekt in die Actions Console zu übertragen:

gactions push

Die Ausgabe sollte in etwa so aussehen:

✔ 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. Kopieren Sie die angegebene URL und fügen Sie sie in einen Browser ein.
3. Klicken Sie in der Actions Console in der oberen Navigationsleiste auf Entwickeln.
4. Klicken Sie auf den Drop-down-Pfeil neben Szenen und dann auf Starten. Sie sollten eine visuelle Darstellung der Start-Szene Ihrer Action sehen, wie im folgenden Screenshot dargestellt:

Projekt bereinigen [empfohlen]

Achtung: Das Codelab für Stufe 2, Actions für Google Assistant mit dem Actions SDK erstellen (Stufe 2), basiert auf dem Projekt, das Sie in diesem Codelab erstellt haben. Wenn Sie das Codelab für Level 2 durchführen möchten, löschen Sie Ihr Projekt nicht. Sie können es stattdessen am Ende des Codelabs für Level 2 im Abschnitt „Projekt bereinigen“ löschen.

Um mögliche Gebühren zu vermeiden, sollten Sie Projekte entfernen, die Sie nicht verwenden möchten. So löschen Sie die Projekte, die Sie in diesem Codelab erstellt haben:

1. Führen Sie die Schritte im Abschnitt Projekte beenden (löschen) aus, um das Cloud-Projekt und die Ressourcen zu löschen.

Achten Sie darauf, dass Sie auf der Seite Google Cloud Platform-Einstellungen das richtige Projekt zum Löschen auswählen.

2. Optional: Wenn Sie Ihr Projekt sofort aus der Actions Console entfernen möchten, führen Sie die Schritte im Abschnitt Projekt löschen aus. Wenn Sie diesen Schritt nicht ausführen, wird Ihr Projekt nach etwa 30 Tagen automatisch entfernt.

7. Glückwunsch!

Sie kennen die Grundlagen der Entwicklung von Actions für Google Assistant mit dem Actions SDK.

Behandelte Themen

• Actions-Projekt in der Actions Console einrichten
• So erstellen Sie Ihr Actions-Projekt mit dem Actions SDK in Ihrem lokalen Dateisystem
• So fügen Sie dem Hauptaufruf einen Prompt hinzu, damit Nutzer eine Unterhaltung mit Ihrer Aktion starten können
• Kommunikationsschnittstelle mit Szenen, Intents, Übergängen, Vorschlagschips und Auftragsausführung erstellen
• Aktion mit dem Actions-Simulator testen

Weitere Informationen

In den folgenden Ressourcen finden Sie weitere Informationen zum Erstellen von Actions für Google Assistant:

• Offizielle Dokumentationswebsite für die Entwicklung von Actions für Google Assistant
• Actions on Google-GitHub-Seite mit Beispielcode und Bibliotheken
• Offizielle Reddit-Community für Entwickler, die mit Assistant arbeiten

Folgen Sie @ActionsOnGoogle auf Twitter, um die neuesten Ankündigungen zu erhalten, und teilen Sie Ihre Projekte mit dem Hashtag #AoGDevs.

Feedback-Umfrage

Bevor Sie gehen, füllen Sie bitte eine kurze Umfrage zu Ihren Erfahrungen aus.