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 von Konversationsaktionen.

Mit der Google Assistant-Entwicklerplattform können Sie Software erstellen, um die Funktionen von Google Assistant, einem virtuellen persönlichen Assistenten, auf mehr als 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 die Assistant-Entwicklerplattform nutzen, um unkompliziert ansprechende und effektive Unterhaltungen zwischen Nutzern und Ihrem eigenen Drittanbieterdienst für die Auftragsausführung zu erstellen und zu verwalten.

Dieses Codelab behandelt Konzepte für Einsteiger zur Entwicklung mit dem Actions SDK for Google Assistant. Sie benötigen keine Vorkenntnisse mit der Plattform, um sie abzuschließen. In diesem Codelab erstellen Sie eine einfache Aktion für Google Assistant, die Nutzern ihr Glück sagt, während sie ihr Abenteuer im mythischen Land Gryffinbergs beginnen. Im Codelab für das Actions SDK Level 2 bauen Sie diese Aktion weiter aus, um das Schicksal des Nutzers basierend auf seiner Eingabe anzupassen.

Aufgaben

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

• Antwortet Nutzern mit einer Begrüßungsnachricht
• Stellt Nutzenden eine Frage und antwortet entsprechend ihrer Auswahl.
• Infofelder mit Vorschlägen, die Nutzer anklicken können, um Eingaben zu machen
• Ändert die Begrüßungsnachricht an den Nutzer abhängig davon, ob es sich um einen wiederkehrenden Nutzer handelt

Wenn du dieses Codelab abgeschlossen hast, hat die abgeschlossene Aktion den folgenden Unterhaltungsablauf: Der Text neben dem Mikrofon steht für die Eingabe des Nutzers, während der Text neben dem Sprecher die Antwort der Aktion darstellt:

Lerninhalte

• Projekt in der Actions Console erstellen
• So verwendest du das gactions-Tool, um dein Aktionsprojekt zwischen der Actions Console und deinem lokalen Dateisystem zu übertragen
• Wie du eine Aufforderung an den Nutzer sendest, nachdem er deine Aktion aufgerufen hat
• Eingabe eines Nutzers verarbeiten und eine Antwort zurückgeben
• Aktion im Actions-Simulator testen
• Auftragsausführung mit dem Cloud Functions-Editor implementieren

Voraussetzungen

Die folgenden Tools müssen sich in Ihrer Umgebung befinden:

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

Wenn Sie zum Erstellen von Aktionen lieber mit visuellen Tools arbeiten möchten, führen Sie stattdessen das Codelab zum Erstellen von Aktionen für Google Assistant mit dem Actions Builder (Level 1) durch. Dort wird dieselbe Aktion mithilfe 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

Zum Testen der Aktion, 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. Gehen Sie zu den Aktivitätseinstellungen.
2. Melden Sie sich mit Ihrem Google-Konto an, falls Sie dies noch nicht getan haben.
3. Aktivieren Sie die folgenden Berechtigungen:

• Web- & App-Aktivitäten
• Wählen Sie unter Web- und App-Aktivitäten, klicken Sie auf das Kästchen 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 Aktion.

So erstellen Sie das 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 ist als interne Referenz gedacht. Später können Sie einen externen Namen für Ihr Projekt festlegen.)

4. Klicken Sie auf Projekt erstellen.
5. Wählen Sie im Bildschirm Welche Art von Aktion möchten Sie erstellen? die Karte Benutzerdefiniert aus.
6. Klicken Sie auf Weiter.
7. Wählen Sie auf dem Bildschirm How do you want to build it? die Karte Leeres Projekt aus.
8. Klicken Sie auf Jetzt erstellen.

Projekt-ID für deine Aktion speichern

Die Projekt-ID ist eine eindeutige Kennung für deine 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 die drei vertikalen Punkte (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 ein Rechnungskonto erstellen und mit Ihrem Projekt in Google Cloud verknüpfen, um die Auftragsausführung später mit Cloud Functions bereitzustellen.

So verknüpfen Sie ein Rechnungskonto mit Ihrem Projekt:

1. Rufen Sie die Abrechnungsseite 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 Kostenlosen Test starten oder auf Senden und Abrechnung aktivieren.
5. Rufen Sie die Abrechnungsseite der Google Cloud Platform auf.
6. Klicken Sie auf den Tab Meine Projekte.
7. Klicken Sie neben dem Actions-Projekt für das Codelab auf das Dreipunkt-Menü unter Aktionen.
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 Gebühren zu vermeiden.

gactions-Befehlszeile installieren

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

Wichtiger Begriff:

• gactions-CLI: Tool, mit dem Sie unter anderem Action-Projektdateien initialisieren, Updates an die Actions Console senden und Actions-Projekte bereitstellen können.

Um die gactions-Befehlszeile zu installieren, folgen Sie der Anleitung unter gactions-Befehlszeilentool installieren.

Actions-Projekt herunterladen

Wenn du mit der Entwicklung deiner Aktion beginnen möchtest, lade dein Actions-Projekt aus der Actions Console herunter.

So laden Sie das Actions-Projekt herunter:

1. Führen Sie die folgenden Befehle aus, um ein neues Verzeichnis zu erstellen und zu diesem 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 verstehen

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

Die Dateistruktur umfasst Folgendes:

• actions/: steht für Ihr Actions-Projekt. Das System ruft actions.yaml auf, wenn deine Aktion aufgerufen wird. Dadurch wird die Datei custom/global/actions.intent.MAIN.yaml aufgerufen.
• custom/: Das Verzeichnis, in dem du deine Aktion ändern wirst.
• global/: Dieses Verzeichnis enthält System-Intents, die die Plattform Ihrem Projekt automatisch hinzufügt. Später in diesem Codelab erfahren Sie mehr über System-Intents.
• manifest.yaml: Eine Datei mit Informationen, die übertragbar oder nicht projektspezifisch sind und zwischen Projekten verschoben werden kann.
• settings/: Steht für die Einstellungen eines Actions-Projekts, z. B. den Anzeigenamen, die Standardsprache und die Kategorie.

3. Unterhaltung starten

Nutzer starten die Unterhaltung mit deiner Aktion über einen Aufruf. Wenn Sie beispielsweise eine Aktion namens MovieTime haben, können Nutzer diese aufrufen, indem sie "Hey Google, sprich mit MovieTime" sagen, wobei MovieTime der Anzeigename ist. Deine Aktion muss einen Anzeigenamen haben, wenn du sie für die Produktion bereitstellen möchtest. Zum Testen der Aktion ist jedoch kein Anzeigename erforderlich. Stattdessen können Sie die Aktion "Talk to my test app" (Mit meiner Test-App sprechen) im Simulator verwenden, um die Aktion aufzurufen. Weitere Informationen zum Simulator finden Sie weiter unten in diesem Abschnitt.

Du musst den Hauptaufruf bearbeiten, um festzulegen, was passiert, nachdem ein Nutzer deine Aktion aufgerufen hat.

Wichtiger Begriff:

• Hauptaufruf: Ein Einstiegspunkt, über den Nutzer Unterhaltungen mit deiner Aktion starten können. Wenn Nutzer eine Formulierung wie „Hey Google, sprich mit <Anzeigename>“ sagen, wird der Hauptaufruf ausgelöst und dem Nutzer geantwortet.

Standardmäßig zeigt deine Aktion eine allgemeine Aufforderung an, wenn dein Aufruf ausgelöst wird (Starte deine Aktion, indem du den Hauptaufruf definierst.).

Wichtiger Begriff:

• Prompt: Definiert, was deine Aktion als Antwort an Nutzer sendet. Prompts können einfache Text- und Sprachantworten oder Rich-Text-Nachrichten wie Karten und Bilder sein.

Sie können den speziellen Prompt Canvas verwenden, um dem Nutzer visuelle Elemente im Vollbildmodus anzuzeigen. Weitere Informationen zu Canvas finden Sie in der Dokumentation zum interaktiven Canvas.

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

Hauptaufruf einrichten

Sie können die Hauptaufruf-Prompts in der Datei actions.intent.MAIN.yaml bearbeiten.

So ändern Sie die Aufforderung, die Ihre Aktion an den Nutzer sendet, wenn er Ihre Aktion aufruft:

1. Öffnen Sie custom/global/actions.intent.MAIN.yaml in Ihrem 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 Console bietet ein Webtool zum Testen deiner Aktion, den Simulator. Die Benutzeroberfläche simuliert Hardwaregeräte und ihre Einstellungen, sodass du dich mit deiner Aktion so unterhalten kannst, als würde sie auf einem Smart Display, einem Smartphone, einem Lautsprecher oder KaiOS ausgeführt werden.

Aktuelle Informationen zur Verwendung des Actions Console-Simulators sowie Informationen zu Problemen in den folgenden Schritten finden Sie auf der Seite Simulator.

Wenn du deine Aktion aufrufst, sollte sie nun mit der von dir hinzugefügten benutzerdefinierten Aufforderung antworten ("A wundersame grüße, Abenteurer!...").

Sie können den Befehl gactions deploy preview verwenden, um Ihre Aktion in der Konsole zu testen, ohne die Version Ihres Actions-Projekts zu aktualisieren. Wenn Sie diesen Befehl ausführen, werden keine der Änderungen, die Sie in Ihrem lokalen Dateisystem vornehmen, in die bereitgestellten Versionen Ihres Actions-Projekts übernommen. 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. Solange Ihre Dateien übermittelt wurden, können Sie diesen Hinweis 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 der 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 Vorschlags-Chip Mit meiner Test-App sprechen klicken. Dieser wird auf dieselbe Weise wie gesprochene oder getippte Nutzereingaben verarbeitet.

Alternativ können Sie auf das Mikrofonsymbol klicken und „Talk to my test app“ (Mit meiner Test-App sprechen) sagen, um die Aktion aufzurufen.

Wenn du den Hauptaufruf deiner Aktion auslöst, antwortet Assistant mit deiner benutzerdefinierten Willkommensnachricht. An dieser Stelle endet die Unterhaltung, nachdem 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 auf dem Tab Test in der Actions Console befinden, werden im Bereich die Ereignisprotokolle angezeigt, in denen der Unterhaltungsverlauf als Ereignisprotokolle angezeigt wird. In jedem Ereignisprotokoll werden die Ereignisse angezeigt, die während der jeweiligen Unterhaltungsrunde eintreten.

Deine Aktion hat derzeit ein Ereignisprotokoll, das sowohl die Eingabe des Nutzers („Sprich mit meiner Test-App“)) und die Antwort deiner Aktion enthält. Der folgende Screenshot zeigt das Ereignisprotokoll deiner Aktion:

Wenn Sie im Ereignisprotokoll auf den Abwärtspfeil neben Talk to my test app klicken, sehen Sie die Ereignisse in chronologischer Reihenfolge, die in der entsprechenden Unterhaltungsrunde stattgefunden haben:

• userInput: Entspricht der Eingabe des Nutzers („Sprich mit meiner Test-App“)
• interactionMatch: Entspricht der Hauptaufrufantwort deiner 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 (A wondrous greeting, adventurer!...) hinzugefügt haben
• endConversation: Entspricht dem ausgewählten Übergang im Main invocation-Intent, der derzeit die Unterhaltung beendet. Im nächsten Abschnitt dieses Codelabs erfahren Sie mehr über Übergänge.

Ereignisprotokolle geben Einblick in die Funktionsweise deiner Aktion und sind nützliche Tools, um Fehler in deiner Aktion zu beheben. Um die Details eines Ereignisses zu sehen, klicken Sie auf den Pfeil neben dem Ereignisnamen, wie im folgenden Screenshot dargestellt:

4. Unterhaltung zu deiner Aktion erstellen

Nachdem du festgelegt hast, was passiert, nachdem ein Nutzer deine Aktion aufgerufen hat, kannst du die restliche Unterhaltung deiner Aktion ausarbeiten. Bevor du mit diesem Codelab fortfährst, solltest du dich mit den folgenden Begriffen vertraut machen, um zu verstehen, wie die Unterhaltung deiner Aktion funktioniert:

Wichtige Begriffe:

• Szene: Ein Baustein für Ihre Aktion, der Nutzereingaben verarbeitet und in der Regel die Antwort an den Nutzer generiert. Mit benutzerdefinierten Intents werden häufig andere Szenen aktiviert. Diese können aber auch auf andere Weise aktiviert werden.
• Custom Intent: Definiert Nutzereingaben, die die Aktion verstehen kann. Sie definieren die Trainingsformulierungen für diese Intents. Wenn Nutzer etwas sagen, das mit einer Trainingsformulierung übereinstimmt oder einer dieser ähnelt, wird der entsprechende Intent zugeordnet.
• Trainingsformulierungen: Beispiele dafür, was ein Nutzer sagen könnte, um einen Intent zuzuordnen. Die NLU-Engine (Natural Language Understanding) erweitert diese Trainingsformulierungen auf natürliche Weise um ähnliche Formulierungen.
• Übergang: Definiert, in welche Szene gewechselt werden soll, sobald die Bedingung erfüllt ist.

Deine Aktion kann eine oder mehrere Szenen haben. Du musst jede Szene aktivieren, bevor sie ausgeführt werden kann. Die Aktion, die Sie in diesem Codelab erstellen, hat nur eine Szene mit dem Titel Start. Die gängigste Methode zum Aktivieren einer Szene besteht darin, die Aktion so zu konfigurieren, dass, wenn die Eingabe des Nutzers mit einem Intent in einer Szene übereinstimmt, dieser Intent den Übergang zu einer anderen Szene auslöst und diesen aktiviert.

Stellen Sie sich beispielsweise eine hypothetische Aktion vor, die den Nutzenden tierische Fakten liefert. Wenn der Nutzer diese Aktion aufruft, wird der Intent Main invocation zugeordnet und löst den Übergang zu einer Szene namens Facts. aus. Dadurch wird die Facts-Szene aktiviert, wodurch der folgende Prompt an den Nutzer gesendet wird: Would you like to hear a fact about cats or dogs? In der Facts-Szene befindet sich ein benutzerdefinierter Intent mit dem Namen Cat. Er enthält Trainingsformulierungen, die der Nutzer sagen könnte, um eine Katze zu hören, z. B. „Ich möchte eine Katzenfakten hören“ oder „Katze“. Wenn der Nutzer darum bittet, einen Katzenfakt zu hören, wird der Intent Cat zugeordnet und löst einen Übergang zu einer Szene mit dem Namen Cat fact. aus. Die Cat fact-Szene wird aktiviert und an den Nutzer wird eine Aufforderung mit einem Katzenfakt gesendet.

Abbildung 1. Der Ablauf einer typischen Unterhaltungsrunde in einer Aktion, die mit dem Actions SDK erstellt wurde.

Szenen, Intents und Übergänge bilden zusammen die Logik für deine Unterhaltung und definieren die verschiedenen Pfade, die der Nutzer durch die Unterhaltung deiner Aktion gehen kann. Im folgenden Abschnitt erstellen Sie eine Szene und definieren, wie diese Szene aktiviert wird, nachdem ein Nutzer Ihre Aktion aufgerufen hat.

Übergang vom Hauptaufruf zur Szene

In diesem Abschnitt erstellen Sie eine neue Szene mit dem Namen Start, die dem Nutzer eine Aufforderung sendet, in der er gefragt wird, ob er seine Wahrnehmung teilen möchte. Außerdem fügen Sie einen Übergang vom Hauptaufruf zur neuen Start-Szene hinzu.

Gehen Sie folgendermaßen vor, um diese Szene zu erstellen und einen Übergang hinzuzufügen:

1. Öffnen Sie custom/global/actions.intent.MAIN.yaml in Ihrem Texteditor.
2. Ersetzen Sie den Text im Feld transitionToScene (actions.scene.END_CONVERSATION) durch folgenden Code: 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 deine Aktion angewiesen, vom Hauptaufruf zur Szene Start zu wechseln.

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

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 Ihrem Texteditor.
7. Fügen Sie den folgenden Code in die Datei Start.yaml ein:

Start.yaml

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

Im Dateicode Start.yaml gibt es ein Feld namens onEnter. Dies ist die erste Phase im Lebenszyklus einer Szene.

Wichtige Begriffe:

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

In diesem Fall wird die Aufforderung (Before you continue on your quest...) der Aufforderungswarteschlange hinzugefügt, wenn der Nutzer zum ersten Mal in die Start-Szene eintritt.

Wichtige Begriffe:

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

Chips für Vorschläge hinzufügen

Vorschlags-Chips bieten anklickbare Vorschläge für den Nutzer, die Ihre Aktion als Nutzereingabe verarbeitet. In diesem Abschnitt fügen Sie die Vorschlags-Chips für 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 Vorschlags-Chips hinzu:

1. Aktualisieren Sie den Code in Start.yaml so, dass er mit dem folgenden Code-Snippet übereinstimmt, das den Code zum Konfigurieren von Vorschlags-Chips enthält:

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.

Aktion im Simulator testen

An dieser Stelle sollte deine Aktion vom Hauptaufruf zur Szene Start übergehen und den Nutzer fragen, ob er seine Glückssache sagen soll. In der simulierten Anzeige sollten auch Vorschlags-Chips angezeigt werden.

So testen Sie Ihre Aktion 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. Deine Aktion sollte mit dem Main invocation-Prompt und dem hinzugefügten Start-Szenen-Prompt „Bevor du mit deiner Mission weitermachst, möchtest du dein Schicksal hören?“ antworten. Außerdem sollten die Infofelder für Vorschläge angezeigt werden.

Der folgende Screenshot zeigt diese Interaktion:

In den Ereignisprotokollen werden alle Interaktionen mit dem Simulator in der aktuellen Sitzung aufgezeichnet. Daher wird das Ereignisprotokoll aus den Tests in diesem Codelab als erstes Ereignisprotokoll angezeigt. Wenn Sie die Ereignisprotokolle löschen möchten, klicken Sie auf Test zurücksetzen.

5. Klicken Sie auf den Vorschlags-Chip Ja oder Nein, um auf die Aufforderung zu reagieren. Sie können auch „Ja“ oder „Nein“ sagen oder Yes oder No in das Feld Eingabe eingeben.

Wenn du auf die Aufforderung antwortest, antwortet deine Aktion mit einer Nachricht, dass sie deine Eingabe nicht versteht: „Das habe ich leider nicht verstanden. Können Sie es noch einmal versuchen?“ Da du deine Aktion noch nicht so konfiguriert hast, dass sie die Eingaben „Ja“ oder „Nein“ versteht und darauf reagiert, ordnet deine Aktion deine Eingabe einem NO_MATCH-Intent zu.

Wichtige Begriffe:

• NO_MATCH: Ein Catchall-Intent, der zugeordnet wird, wenn der Nutzer etwas sagt, das keinem anderen Intent in Ihrer Aktion zugeordnet werden kann.
• System-Intent: Ein standardmäßig konfigurierter Intent, der allgemeine Systemereignisse verarbeitet, z. B. wenn ein Nutzer keine Eingabe macht. NO_MATCH und der mit dem Hauptaufruf verknüpfte Intent sind Beispiele für System-Intents.

Standardmäßig liefert der System-Intent NO_MATCH allgemeine Antworten. Sie können diese Antworten jedoch anpassen, um den Nutzer zu informieren, dass Sie seine Eingabe nicht verstanden haben. Assistant beendet die Unterhaltung des Nutzers mit Ihrer Aktion, wenn nicht dreimal eine Nutzereingabe zugeordnet werden kann.

yes- und no-Intents hinzufügen

Nachdem Nutzer auf die von deiner Aktion gestellte Frage antworten können, kannst du deine Aktion so konfigurieren, dass sie die Antworten ("Yes" oder "No"). In den folgenden Abschnitten erstellen Sie benutzerdefinierte Intents, die abgeglichen werden, wenn der Nutzer "Yes" oder "No" sagt, und fügen diese Intents der Szene Start hinzu.

Intent yes erstellen

So erstellen Sie den Intent yes:

1. Erstellen Sie im Terminal ein neues Verzeichnis namens intents im Verzeichnis custom:

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 Ihrem 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.

Intent yes zur Szene Start hinzufügen

Jetzt kann die Aktion verstehen, wenn ein Nutzer den Intent Ja zum Ausdruck bringt. Sie können der Szene Start den benutzerdefinierten Intent yes hinzufügen, da der Nutzer auf die Start-Aufforderung reagiert („Möchten Sie Ihr Schicksal sagen, bevor Sie mit Ihrer Mission fortfahren?“).

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

1. Öffnen Sie custom/scenes/Start.yaml in Ihrem Texteditor.
2. Fügen Sie am Ende der Datei Start.yaml die Handler intentEvents und yes 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 zugeordnet ist, wird die Aufforderung „Your future depending on the item, you choose to use for your Quest...“ (Deine Zukunft hängt von dem Element ab, das du für deine Mission verwendest...), zur Aufforderungswarteschlange hinzugefügt. Die Start-Szene geht dann in die actions.scene.END_CONVERSATION-Systemszene über, die die Eingabeaufforderungen in der Prompt-Warteschlange liefert und die Unterhaltung beendet.

Intent „yes“ im Simulator testen

An diesem Punkt versteht deine Aktion, wenn der Benutzer sein Schicksal 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. Um die Aktion im Simulator zu testen, geben Sie Talk to my test app in das Feld Input (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 auch auf den Vorschlags-Chip Ja klicken.

Deine Aktion reagiert auf den Benutzer und teilt ihm mit, dass sein Schicksal von der gewählten Hilfe abhängt. Ihre Aktion beendet dann die Sitzung, da Sie den Übergang End conversation für den Intent yes konfiguriert haben.

Intent no erstellen

Jetzt kannst du den Intent no erstellen, damit deine Aktion den Nutzer versteht und darauf reagiert, wenn er seine Zukunft 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 Ihrem 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.

Intent no zur Szene Start hinzufügen

Jetzt kann die Aktion verstehen, wenn ein Nutzer „Nein“ oder etwas Ähnliches wie „Nein“, wie z. B. „Nee“, äußert. Sie müssen der Szene Start den benutzerdefinierten Intent no hinzufügen, weil der Nutzer auf die Aufforderung „Start“ reagiert („Möchten Sie Ihr Schicksal sagen, bevor Sie mit der Mission fortfahren?“).

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

1. Öffnen Sie custom/scenes/Start.yaml in Ihrem Texteditor.
2. Fügen Sie in Start.yaml unter dem yes-Handler den folgenden no-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.

Intent „no“ im Simulator testen

An diesem Punkt versteht deine Aktion, wenn der Benutzer sein Schicksal 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 Vorschlags-Chip No klicken.

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

5. Auftragsausführung implementieren

Die Antworten deiner Aktion sind derzeit statisch: Wenn eine Szene aktiviert wird, die einen Prompt enthält, sendet deine Aktion jedes Mal dieselbe Aufforderung. In diesem Abschnitt implementieren Sie die Auftragsausführung, die die Logik zum Erstellen einer dynamischen Konversationsantwort enthält.

Wichtiger Begriff:

• Fulfillment (Auftragsausführung): Der Code, der die Logik für deine Aktion enthält. Ein Webhook löst Aufrufe der Auftragsausführung anhand von Ereignissen aus, die innerhalb Ihrer Aktionen auftreten.

Die Auftragsausführung ermittelt, ob der Nutzer ein wiederkehrender oder neuer Nutzer ist, und ändert die Begrüßungsnachricht der Aktion für wiederkehrende Nutzer. Die Begrüßungsnachricht wird für wiederkehrende Nutzer gekürzt und bestätigt die Rückgabe des Nutzers: "A wundersame grüße, Abenteurer! Willkommen zurück im mythischen Land von Gryffinberg!“

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

Wichtiger Begriff:

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

Ihre Aktion kann Webhooks auslösen, um die Ausführung eines Ereignisses zu benachrichtigen, das während eines Aufrufs oder in bestimmten Teilen einer Szene ausgeführt wird. Wenn ein Webhook ausgelöst wird, sendet deine Aktion eine Anfrage mit einer JSON-Nutzlast zusammen mit dem Namen des Handlers, der zur Verarbeitung des Ereignisses verwendet werden soll, an die Auftragsausführung. Dieser Handler führt eine Logik aus und gibt eine entsprechende JSON-Antwort zurück.

Fulfillment aufbauen

In diesem Abschnitt ändern Sie die Auftragsausführung, um unterschiedliche Aufforderungen für wiederkehrende und neue Nutzer zu generieren, wenn sie Ihre Aktion aufrufen.

So fügen Sie Ihrer Auftragsausführung diese Logik hinzu:

1. Prüfen Sie im Terminal, ob Sie sich im Stammverzeichnis Ihres Projekts befinden, und erstellen Sie ein neues webhooks-Verzeichnis:

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 Ihrem Texteditor.
4. Fügen Sie der Datei ActionsOnGoogleFulfillment.yaml den Handler greeting und den Inhalt von inlineCloudFunction hinzu:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

Die Datei ActionsOnGoogleFulfillment.yaml definiert Ihre Webhook-Handler (z. B. den greeting-Handler) und weist Ihre Aktion an, Cloud Functions als Webhook-Endpunkt zu verwenden.

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

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 Ihrem 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

Die Datei package.json gibt Abhängigkeiten und andere Metadaten für den Webhook an.

11. Öffnen Sie package.json in Ihrem 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-Auftragsausführungsbibliothek für Node.js verwendet, antwortet auf HTTP-Anfragen von Google Assistant.

Im vorherigen Code-Snippet definierst du den greeting-Handler, der prüft, ob der Nutzer die Aktion zuvor mit der Eigenschaft lastSeenTime aufgerufen hat. Wenn die Eigenschaft lastSeenTime nicht definiert ist, ist der Nutzer neu und erhält die Begrüßung für neue Nutzer. Andernfalls bestätigt die Nachricht die Rückgabe des Nutzers und generiert eine geänderte Begrüßung.

Hauptaufruf zum Auslösen eines Webhooks aktualisieren

Nachdem Sie die greeting-Funktion definiert haben, können Sie den greeting-Event-Handler in Ihrem Hauptaufruf-Intent konfigurieren, damit Ihre Aktion weiß, dass diese Funktion aufgerufen wird, wenn der Nutzer Ihre Aktion aufruft.

So konfigurierst du deine Aktion für den Aufruf des neuen greeting-Handlers:

1. Öffnen Sie custom/global/actions.intent.MAIN.yaml in Ihrem 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 jetzt der Hauptaufruf-Intent zugeordnet wird, wird der greeting-Webhook-Handler aufgerufen.

Aktualisierten Hauptaufruf im Simulator testen

So testen Sie Ihre Aktion im Simulator:

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

Da dieser Befehl den Webhook bereitstellt und Abhängigkeiten installiert, kann es länger dauern als die vorherigen Befehle.

gactions deploy preview

Wenn Sie einen 403-Fehler bezüglich der Cloud Build API oder einen 403-Fehler beim Verknüpfen Ihres Rechnungskontos erhalten, lesen Sie die Informationen unter Abrechnung für ein Projekt aktivieren, deaktivieren oder ändern. Zum Bereitstellen mithilfe von Cloud Functions müssen Sie ein Rechnungskonto mit Ihrem Projekt in Google Cloud verknüpfen. Führen Sie gactions deploy preview nach dem Verknüpfen eines Rechnungskontos noch einmal aus. Folgen Sie der Anleitung im Abschnitt „Projekt bereinigen“ am Ende dieses Codelabs, um Gebühren 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. Um die Aktion im Simulator zu testen, geben Sie Talk to my test app in das Feld Input (Eingabe) ein und drücken Sie Enter.

Da du deine Aktion bereits in diesem Codelab getestet hast, bist du kein neuer Nutzer. Daher erhältst du die folgende verkürzte Begrüßung: „A wundersame grüße, Abenteurer! Willkommen zurück im mythischen Land von Gryffinberg!“

6. Aktionen mit Actions Builder visualisieren

Das Actions SDK ist mit der webbasierten IDE Actions Builder kompatibel, die in die Actions Console integriert ist. Mit dem Befehl gactions push kannst du dein lokales Dateisystem per Push in den Aktionsentwurf in der Konsole übertragen. Im Gegensatz zu gactions deploy preview, mit dem du deine Aktion nur im Simulator testen kannst, verschiebt gactions push alle Inhalte aus deinen lokalen Dateien in Actions Builder.

In der Actions Console findest du eine visuelle Darstellung der Konfiguration deiner Aktion. Die visuelle Darstellung deiner Aktion kann bei der Entwicklung nützlich sein und hat keinen Einfluss auf die Version deiner Aktion, die zum Testen bereitgestellt wird.

Wenn Sie gactions push ausführen, wird der aktuelle Entwurf Ihres Actions-Projekts überschrieben, wenn Sie mit anderen zusammenarbeiten.

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

1. Führen Sie im Terminal den folgenden Befehl aus, um Ihr Projekt an 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 Develop.
4. Klicken Sie auf den Drop-down-Pfeil neben Szenen und dann auf Starten. Du solltest eine visuelle Darstellung der Start-Szene deiner Aktion sehen, wie im folgenden Screenshot zu sehen:

Projekt bereinigen [empfohlen]

Achtung: Das Codelab zu Level 2, Build Actions for Google Assistant using Actions SDK (Level 2), baut auf dem Projekt auf, das du in diesem Codelab erstellt hast. Wenn du vorhast, Level-2-Codelab zu absolvieren, solltest du dein Projekt nicht löschen. können Sie es stattdessen im Abschnitt „Projekt bereinigen“ löschen am Ende des Level-2-Codelabs.

Um mögliche Kosten 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 im Abschnitt Projekte beenden (löschen) aufgeführten Schritte aus, um das Cloud-Projekt und die Ressourcen zu löschen.

Achten Sie darauf, dass Sie auf der Seite Einstellungen der Google Cloud Platform 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 Erstellung von Aktionen für Google Assistant mit dem Actions SDK.

Behandelte Themen

• Actions-Projekt in der Actions Console einrichten
• Actions SDK verwenden, um Actions-Projekt auf deinem lokalen Dateisystem zu erstellen
• Wie du dem Hauptaufruf eine Aufforderung hinzufügst, damit Nutzer eine Unterhaltung mit deiner Aktion starten können
• Eine dialogorientierte Schnittstelle mit Szenen, Intents, Übergängen, Vorschlags-Chips und Auftragsausführung erstellen
• Aktion mit dem Actions-Simulator testen

Weitere Informationen

In den folgenden Ressourcen erfahren Sie mehr über die Erstellung von Actions for Google Assistant:

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

Folge @ActionsOnGoogle auf Twitter, um die neuesten Ankündigungen zu erhalten, und twittere mit #AoGDevs, um deine Entwicklungen zu teilen.

Feedback-Umfrage

Bevor Sie uns verlassen, möchten wir Sie bitten, an einer kurzen Umfrage zu Ihren Erfahrungen teilzunehmen.