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 mehr als 1 Milliarde Geräte zu erweitern, darunter Smart Speaker, Smartphones, Autos, Fernseher, Kopfhörer und mehr. Nutzer können mit Assistant sprechen, um Dinge zu erledigen, z. B. Lebensmittel zu kaufen oder eine Fahrt zu buchen. Als Entwickler können Sie die Assistant-Entwicklerplattform verwenden, um ganz einfach ansprechende und effektive Konversationsmodi zwischen Nutzern und Ihrem eigenen Drittanbieter-Fulfillment-Dienst zu erstellen und zu verwalten.

In diesem Codelab werden grundlegende Konzepte für die Entwicklung mit dem Actions SDK für Google Assistant behandelt. Sie benötigen keine Vorkenntnisse mit der Plattform, um es zu absolvieren. In diesem Codelab erstellen Sie eine einfache Aktion für Google Assistant, die Nutzern die Zukunft voraussagt, wenn sie ihr Abenteuer im fiktiven Land Gryffinberg beginnen. Im Codelab „Actions SDK – Level 2“ erweitern Sie diese Aktion, um die Vorhersage für den Nutzer 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 Nutzern eine Frage und reagiert angemessen auf die Auswahl des Nutzers
• Stellt Vorschlags-Chips bereit, auf die Nutzer klicken können, um Eingaben zu machen
• Ändert die Begrüßungsnachricht für den Nutzer, je nachdem, ob er ein wiederkehrender Nutzer ist

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

Lerninhalte

• Projekt in der Actions Console erstellen
• Wie Sie das gactions-Tool verwenden, um Ihr Aktionsprojekt zwischen der Actions-Konsole und Ihrem lokalen Dateisystem zu übertragen und abzurufen
• Wie Sie dem Nutzer einen Prompt senden, nachdem er Ihre Aktion aufgerufen hat
• Nutzereingaben verarbeiten und eine Antwort zurückgeben
• Aktion im Aktionssimulator testen
• Fulfillment mit dem Cloud Functions-Editor implementieren

Voraussetzungen

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

• 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 lieber mit visuellen Tools arbeiten, um Aktionen zu erstellen, können Sie stattdessen das Codelab Aktionen für Google Assistant mit Actions Builder erstellen (Stufe 1) absolvieren. Dort wird dieselbe Aktion mit der Actions Builder-IDE in der Console erstellt.

2. Einrichten

In den folgenden Abschnitten wird beschrieben, wie du deine Entwicklungsumgebung einrichtest und dein Actions-Projekt erstellst.

Google-Berechtigungseinstellungen prüfen

Wenn Sie die in diesem Codelab erstellte Aktion testen möchten, 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. Falls noch nicht geschehen, melde dich mit deinem Google-Konto an.
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 Aktion.

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

1. Öffne 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 Aktion 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 Jetzt erstellen.

Projekt-ID für Ihre Aktion speichern

Die Projekt-ID ist eine eindeutige Kennung für Ihre Aktion. Sie benötigen die 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 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“ 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 Testzeitraum starten oder Senden und Abrechnung aktivieren.
5. Rufen Sie die Seite „Abrechnung“ der Google Cloud Platform auf.
6. Klicken Sie auf den Tab Meine Projekte.
7. Klicken Sie unter Aktionen neben dem Actions-Projekt für das Codelab 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.

Wenn Sie Gebühren vermeiden möchten, folgen Sie der Anleitung im Abschnitt „Projekt bereinigen“ am Ende dieses Codelabs.

gactions-Befehlszeile installieren

In diesem Codelab verwenden Sie das gactions-Befehlszeilentool, 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, Aktionsprojekte bereitstellen und mehr können.

Folgen Sie der Anleitung unter gactions-Befehlszeilentool installieren, um die gactions-Befehlszeile 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 Aktionsprojekts 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. Die folgende Abbildung zeigt eine allgemeine Darstellung der Dateistruktur:

Die Dateistruktur besteht aus Folgendem:

• actions/: Stellt Ihr Actions-Projekt dar. Das System ruft actions.yaml auf, wenn deine Aktion aufgerufen wird. Dadurch wird dann die Datei custom/global/actions.intent.MAIN.yaml aufgerufen.
• custom/: Das Verzeichnis, in dem Sie Ihre Aktion ändern.
• global/: Dieses Verzeichnis enthält System-Intents, die die Plattform Ihrem Projekt automatisch hinzufügt. Mehr zu System-Intents erfahren Sie später in diesem Codelab.
• manifest.yaml: Eine Datei, die Informationen enthält, die übertragbar oder nicht projektspezifisch sind und zwischen Projekten verschoben werden können.
• settings/: Stellt die Einstellungen eines Actions-Projekts dar, z. B. den Anzeigenamen, die Standardsprache und die Kategorie.

3. Unterhaltung starten

Nutzer starten die Unterhaltung mit deiner Aktion durch einen Aufruf. Wenn Sie beispielsweise eine Aktion mit dem Namen MovieTime haben, können Nutzer Ihre Aktion mit einem Befehl wie „Hey Google, sprich mit MovieTime“ aufrufen, wobei MovieTime der Anzeigename ist. Ihre Aktion muss einen Anzeigenamen haben, wenn Sie sie in der Produktion bereitstellen möchten. Zum Testen Ihrer Aktion müssen Sie den Anzeigenamen jedoch nicht definieren. Stattdessen können Sie im Simulator die Wortgruppe „Mit meiner Test-App sprechen“ verwenden, um Ihre Aktion aufzurufen. Mehr über den Simulator erfahren Sie später in diesem Abschnitt.

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

Schlüsselbegriff:

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

Standardmäßig stellt deine Aktion eine allgemeine Aufforderung bereit, wenn dein Aufruf ausgelöst wird („Beginne mit der Erstellung deiner Aktion, indem du den Hauptaufruf definierst.“).

Schlüsselbegriff:

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

Sie können einen speziellen Prompt, Canvas, verwenden, um dem Nutzer Vollbild-Visualisierungen zurückzugeben. Weitere Informationen zu Canvas findest du in der Dokumentation zu Interactive Canvas.

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 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 Ihrer Aktion, den Simulator. Die Benutzeroberfläche simuliert Hardwaregeräte und deren Einstellungen, sodass Sie mit Ihrer Aktion so interagieren können, als würde sie auf einem Smart Display, Smartphone, Lautsprecher oder KaiOS ausgeführt.

Aktuelle Informationen zur Verwendung des Simulators der Actions Console oder bei Problemen mit den folgenden Schritten finden Sie auf der Seite Simulator.

Wenn Sie Ihre Aktion aufrufen, sollte sie jetzt mit der von Ihnen hinzugefügten benutzerdefinierten Aufforderung („Seid gegrüßt, Abenteurer!…“) antworten.

Mit dem Befehl gactions deploy preview können Sie Ihre Aktion in der Konsole 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, an bereitgestellte Versionen Ihres Actions-Projekts weitergegeben. Sie können sie jedoch in einer Vorabversion testen.

So testen Sie den Hauptaufruf Ihrer Aktion im Simulator:

1. Führen Sie im Terminal den folgenden Befehl 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 übertragen wurden, können Sie diese Benachrichtigung 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. Wenn Sie Ihre Aktion im Simulator aufrufen möchten, geben Sie Talk to my test app in das Feld Eingabe 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 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 Willkommensnachricht. An dieser Stelle endet die Unterhaltung, nachdem Assistant mit einer Begrüßung geantwortet hat. Im nächsten Abschnitt ändern Sie Ihre Aktion, damit die Unterhaltung fortgesetzt wird.

Ereignisprotokolle ansehen

Wenn Sie sich in der Actions Console auf dem Tab Test befinden, werden im Bereich die Ereignisprotokolle angezeigt, die den Unterhaltungsverlauf als Ereignisprotokolle enthalten. In jedem Ereignisprotokoll werden die Ereignisse angezeigt, die während dieses Gesprächsabschnitts auftreten.

Ihre Aktion hat derzeit ein Ereignisprotokoll, das sowohl die Eingabe des Nutzers („Mit meiner Test-App sprechen“) als auch die Antwort Ihrer Aktion enthält. Der folgende Screenshot zeigt das Ereignisprotokoll Ihrer Aktion:

Wenn Sie im Ereignisprotokoll auf den Abwärtspfeil neben Talk to my test app klicken, werden die Ereignisse, die in diesem Gesprächsabschnitt aufgetreten sind, chronologisch angeordnet:

• userInput: Entspricht der Nutzereingabe („Mit meiner Test-App sprechen“)
• interactionMatch: Entspricht der Antwort auf den Hauptaufruf 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 (A wondrous greeting, adventurer!...) hinzugefügt haben.
• 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 deine Aktion funktioniert, und sind nützliche Tools zum Debuggen deiner Aktion, wenn Probleme auftreten. Wenn Sie die Details eines Ereignisses aufrufen möchten, klicken Sie auf den Pfeil neben dem Ereignisnamen, wie im folgenden Screenshot gezeigt:

4. Unterhaltung für die Aktion erstellen

Nachdem Sie definiert haben, was passiert, wenn ein Nutzer Ihre Aktion aufruft, 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 Aktion 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 Nutzereingaben, die die Aktion verstehen kann. Sie definieren die Trainingsformulierungen für diese Intents. Wenn Nutzer etwas sagen, das mit einem Trainingssatz übereinstimmt oder ihm ähnelt, wird der entsprechende Intent zugeordnet.
• Trainingsformulierungen: Beispiele dafür, was ein Nutzer sagen könnte, um einen Intent auszulösen. Die NLU-Engine (Natural Language Understanding) von Assistant erweitert diese Trainingsformulierungen auf natürliche Weise um andere ä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 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, Ihre Aktion so zu konfigurieren, dass die Nutzereingabe mit einem Intent innerhalb einer Szene übereinstimmt und dieser Intent den Übergang zu einer anderen Szene auslöst und diese aktiviert.

Stellen Sie sich zum Beispiel eine hypothetische Aktion vor, die dem Nutzer Fakten über Tiere liefert. Wenn der Nutzer diese Aktion aufruft, wird die Intent-Übereinstimmung Main invocation gefunden und der Übergang zu einer Szene namens Facts. ausgelöst. Durch diesen Übergang wird die Szene Facts aktiviert, die die folgende Aufforderung 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 Fakt über Katzen zu hören, z. B. „Ich möchte einen Fakt über Katzen hören“ oder „Katze“. Wenn der Nutzer nach einem Fakt über Katzen fragt, wird die Intent Cat ausgelöst und ein Übergang zur Szene Cat fact. wird ausgelöst. Die Szene Cat fact wird aktiviert und sendet eine Aufforderung an den Nutzer, die einen Fakt über Katzen enthält.

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

Szenen, Intents und Übergänge bilden zusammen die Logik für Ihre Unterhaltung und definieren die verschiedenen Pfade, die Nutzer in der Unterhaltung Ihrer Aktion einschlagen können. 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 eine Aufforderung an den Nutzer sendet, in der er gefragt wird, ob er sich die Zukunft vorhersagen lassen möchte. Außerdem fügen Sie einen Übergang vom Hauptaufruf zur neuen Szene Start hinzu.

So erstellen Sie diese Szene und fügen einen Übergang hinzu:

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 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 die Aktion angewiesen, vom Hauptaufruf zur Szene Start zu wechseln.

3. Speichern Sie die Datei.
4. Erstellen Sie im Terminal ein neues scenes-Verzeichnis im custom-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 Code der Datei Start.yaml gibt es ein Feld namens onEnter. Das 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 Szene Start zum ersten Mal betritt.

Wichtige Begriffe:

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

Vorschlags-Chips hinzufügen

Vorschlags-Chips bieten anklickbare Vorschläge für den Nutzer, die deine Aktion als Nutzereingabe verarbeitet. In diesem Abschnitt fügen Sie die Vorschlags-Chips Yes und No hinzu, die unter der gerade konfigurierten Aufforderung (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 der Aufforderung der Szene Start Vorschlags-Chips hinzu:

1. Aktualisieren Sie den Code in Start.yaml so, dass er dem folgenden Code-Snippet entspricht, 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 Ihre Aktion vom Hauptaufruf zur Szene Start wechseln und den Nutzer fragen, ob er sich die Zukunft vorhersagen lassen möchte. Vorschlags-Chips sollten auch im simulierten Display 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 Testen, um den Simulator zu öffnen.
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 hinzugefügten Szenen-Prompt Start antworten: „Möchtest du dir die Zukunft vorhersagen lassen, bevor du deine Suche fortsetzt?“. Dabei werden die Vorschlags-Chips angezeigt.

Der folgende Screenshot zeigt diese Interaktion:

In den Ereignisprotokollen werden alle Simulatorinteraktionen in der aktuellen Sitzung aufgezeichnet. Das Ereignisprotokoll aus dem vorherigen Test in diesem Codelab wird also 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 antworten. (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: „Tut mir leid, das habe ich nicht verstanden. Kannst du es noch einmal versuchen?“ Da Sie Ihre Aktion noch nicht so konfiguriert haben, dass sie die Eingabe Ja oder Nein versteht und darauf reagiert, ordnet Ihre Aktion die Eingabe einem NO_MATCH-Intent zu.

Wichtige Begriffe:

• NO_MATCH: Ein Catch-all-Intent, der ausgelöst wird, wenn der Nutzer etwas sagt, das keinem anderen Intent in deiner Aktion zugeordnet werden kann.
• System-Intent: Ein Intent, der standardmäßig konfiguriert ist und gängige Systemereignisse verarbeitet, z. B. wenn ein Nutzer keine Eingabe macht. NO_MATCH und die mit dem Hauptaufruf verknüpfte Absicht sind Beispiele für System-Intents.

Standardmäßig liefert der System-Intent NO_MATCH generische Antworten. 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 deiner Aktion, wenn er die Nutzereingabe dreimal nicht zuordnen kann.

Intents yes und no hinzufügen

Nachdem Nutzer jetzt auf die Frage Ihrer Aktion antworten können, können Sie Ihre Aktion so konfigurieren, dass sie die Antworten der Nutzer (Ja oder Nein) versteht. In den folgenden Abschnitten erstellen Sie benutzerdefinierte Intents, die ausgelöst werden, wenn der Nutzer „Ja“ oder „Nein“ 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 mit dem Namen 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 erkennen, wenn ein Nutzer eine „Ja“-Absicht äußert. Du kannst die benutzerdefinierte Absicht yes der Szene Start hinzufügen, da der Nutzer auf die Aufforderung Start (Möchtest du dir die Zukunft vorhersagen lassen, bevor du deine Suche fortsetzt?) antwortet.

So fügen Sie diese benutzerdefinierte Intent-Anweisung der Szene Start hinzu:

1. Öffnen Sie custom/scenes/Start.yaml in Ihrem Texteditor.
2. Fügen Sie die Handler intentEvents und yes 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 die Intent-Anfrage yes übereinstimmt, wird der Prompt „Deine Zukunft hängt von dem Gegenstand ab, den du für deine Suche auswählst…“ der Prompt-Warteschlange hinzugefügt. Die Szene Start wechselt dann zur Systemszene actions.scene.END_CONVERSATION, die die Prompts in der Prompt-Warteschlange liefert und die Unterhaltung beendet.

yes-Intent im Simulator testen

An dieser Stelle versteht Ihre Aktion, wenn der Nutzer seine Zukunft vorhergesagt bekommen 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 Testen, um den Simulator zu öffnen.
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 Vorschlags-Chip Ja klicken.

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

Intent no erstellen

Jetzt können Sie den Intent no erstellen, damit Ihre Aktion die Nutzeranfrage versteht und darauf reagieren kann, wenn der Nutzer seine Zukunft nicht erfahren 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“ sagt, z. B. „Nö“. Du musst die benutzerdefinierte Intent-Anweisung no zur Szene Start hinzufügen, da der Nutzer auf die Aufforderung Start („Möchtest du dir die Zukunft vorhersagen lassen, 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 Ihrem Texteditor.
2. Fügen Sie den folgenden no-Handler unter dem yes-Handler in Start.yaml 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 dieser Stelle versteht Ihre Aktion, wenn der Nutzer seine Zukunft 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 Testen, um den Simulator zu öffnen.
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 die Zukunft vorherzusagen, wünscht deine Aktion ihm Glück auf seiner Reise. Ihre Aktion beendet dann die Sitzung, weil Sie den Übergang End conversation für den Intent no konfiguriert haben.

5. Auftragsausführung implementieren

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

Schlüsselbegriff:

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

In der Auftragsausführung wird ermittelt, ob es sich um einen wiederkehrenden oder einen neuen Nutzer handelt, und die Begrüßungsnachricht der Aktion für wiederkehrende Nutzer wird angepasst. Die Begrüßungsnachricht wird für wiederkehrende Nutzer gekürzt und die Rückkehr des Nutzers wird bestätigt: „Sei gegrüßt, Abenteurer! Willkommen zurück im mystischen Land Gryffinberg!

In diesem Codelab verwenden Sie den Cloud Functions-Editor, um Ihren Fulfillment-Code 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 for Firebase bearbeiten und bereitstellen können.

Ihre Aktion kann Webhooks auslösen, die Ihre Auftragsausführung über ein Ereignis benachrichtigen, 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, zusammen mit dem Namen des Handlers, der zum Verarbeiten des Ereignisses verwendet werden soll. Dieser Handler führt eine Logik aus und gibt eine entsprechende JSON-Antwort zurück.

Fulfillment erstellen

In diesem Abschnitt ändern Sie Ihren Auftragsausführungscode, damit wiederkehrende und neue Nutzer unterschiedliche Prompts erhalten, wenn sie Ihre Aktion aufrufen.

So fügen Sie diese Logik Ihrem Fulfillment 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 inlineCloudFunction hinzu:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

In der Datei ActionsOnGoogleFulfillment.yaml werden die Webhook-Handler (z. B. der Handler greeting) definiert und die Aktion wird angewiesen, Cloud Functions als Webhook-Endpunkt zu verwenden.

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 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(&#>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);

Dieser Code definiert den Handler greeting, 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 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 definieren Sie den Handler greeting, der prüft, ob der Nutzer die Aktion mit dem Attribut lastSeenTime bereits besucht hat. Wenn das Attribut lastSeenTime nicht definiert ist, ist der Nutzer neu und erhält die Begrüßung für neue Nutzer. Andernfalls wird die Rückkehr des Nutzers bestätigt und eine geänderte Begrüßung generiert.

Hauptaufruf aktualisieren, um einen Webhook auszulösen

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

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

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 erkannt wird, wird der Webhook-Handler greeting aufgerufen.

Aktualisierten Hauptaufruf im Simulator testen

So testen Sie Ihre Aktion 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 es länger dauern als bei den vorherigen Befehlen.

gactions deploy preview

Wenn Sie einen 403-Fehler im Zusammenhang mit der Cloud Build API oder einen 403-Fehler im Zusammenhang mit der Verknüpfung Ihres Rechnungskontos erhalten, lesen Sie den Hilfeartikel Abrechnung für ein Projekt aktivieren, deaktivieren oder ändern. Wenn Sie die Bereitstellung mit Cloud Functions vornehmen möchten, müssen Sie Ihrem Projekt in Google Cloud ein Rechnungskonto zuweisen. Führen Sie gactions deploy preview nach dem Verknüpfen eines Rechnungskontos noch einmal aus. Um Kosten zu vermeiden, folgen Sie der Anleitung im Abschnitt „Projekt bereinigen“ am Ende dieses Codelabs.

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 in diesem Codelab getestet haben, sind Sie kein neuer Nutzer und erhalten die folgende verkürzte Begrüßung: „Sei gegrüßt, Abenteurer! Willkommen zurück im mystischen Land Gryffinberg!…“

6. Aktion 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 Aktion in der Console übertragen. Im Gegensatz zu gactions deploy preview, womit Sie Ihre Aktion nur im Simulator testen können, werden mit gactions push alle Inhalte aus Ihren lokalen Dateien in Actions Builder verschoben.

Die Actions Console bietet eine visuelle Darstellung der Konfiguration Ihrer Aktion. Eine visuelle Darstellung Ihrer Aktion kann während der Entwicklung nützlich sein und hat keinen Einfluss auf die Version Ihrer Aktion, die für Tests bereitgestellt wird.

Wenn Sie gemeinsam an einem Projekt arbeiten, wird durch das Ausführen von gactions push der aktuelle Entwurf Ihres Actions-Projekts überschrieben.

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 Develop (Entwickeln).
4. Klicken Sie auf den Drop-down-Pfeil neben Szenen und dann auf Starten. Sie sollten eine visuelle Darstellung der Szene Start Ihrer Aktion sehen, wie im folgenden Screenshot gezeigt:

Projekt bereinigen [empfohlen]

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

Um mögliche Kosten zu vermeiden, sollten Sie Projekte entfernen, die Sie nicht verwenden möchten. So löschen Sie die in diesem Codelab erstellten Projekte:

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 zum Erstellen von Aktionen für Google Assistant mit dem Actions SDK.

Was Sie behandelt haben

• Actions-Projekt in der Actions Console einrichten
• Wie Sie das Actions SDK verwenden, um Ihr Actions-Projekt in Ihrem lokalen Dateisystem zu erstellen
• Wie Sie dem Hauptaufruf einen Prompt hinzufügen, damit Nutzer eine Unterhaltung mit Ihrer Aktion starten können
• Konversationsschnittstelle mit Szenen, Intents, Übergängen, Vorschlags-Chips und Auftragsausführung erstellen
• Aktion mit dem Aktionssimulator testen

Weitere Informationen

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

• Die offizielle Dokumentationswebsite für die Entwicklung von Aktionen für Google Assistant
• Actions on Google-Seite auf GitHub für 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 tweete mit #AoGDevs, um deine Entwicklungen zu teilen.

Feedback-Umfrage

Bevor du gehst, fülle bitte eine kurze Umfrage zu deinen Erfahrungen aus.