Am 13. Juni 2023 wurden Konversationsaktionen eingestellt. Weitere Informationen finden Sie unter Einstellung von Konversationsaktionen.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Webhooks

Um Ihnen noch mehr Flexibilität bei der Entwicklung von Actions zu bieten, können Sie die Logik an HTTPS-Webdienste (Auftragsausführung) delegieren. Ihre Actions können Webhooks auslösen, die Anfragen an einen HTTPS-Endpunkt senden. Beispiele für mögliche Aktionen in der Auftragsausführung:

Dynamischen Prompt basierend auf vom Nutzer bereitgestellten Informationen generieren
Bestellung in einem externen System aufgeben und Erfolg bestätigen
Slots mit Backend-Daten validieren

**Abbildung 1.** Aufruf-Intents und Szenen können Webhooks auslösen.

Webhook-Trigger und ‑Handler

Ihre Actions können in Aufruf-Intents oder Szenen einen Webhook auslösen, der eine Anfrage an Ihren Endpunkt für die Auftragsausführung sendet. Ihre Auftragsausführung enthält Webhook-Handler, die die JSON-Nutzlast in der Anfrage verarbeiten. Sie können Webhooks in den folgenden Situationen auslösen:

Nach einer Übereinstimmung mit einem Aufruf-Intent
Während der Phase „Beim Betreten“ einer Szene
Nachdem eine Bedingung in der Bedingungsphase einer Szene „true“ ergibt
Während der Phase „Slot-Ausfüllung“ einer Szene
Nachdem in der Eingabephase einer Szene eine Übereinstimmung mit einem Intent aufgetreten ist

Wenn Sie in Ihren Actions einen Webhook auslösen, sendet Google Assistant 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. Ihr Endpunkt für die Auftragsausführung kann das Ereignis an den entsprechenden Handler weiterleiten, um die Logik auszuführen und eine entsprechende Antwort mit einer JSON-Nutzlast zurückzugeben.

Nutzlasten

Die folgenden Snippets zeigen Beispielanfragen, die Ihre Actions an die Auftragsausführung senden, und eine Antwort, die von der Auftragsausführung zurückgesendet wird. Weitere Informationen finden Sie in der Referenzdokumentation zu.

Beispielanfrage

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Beispielantwort

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello World.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Laufzeitinteraktionen

In den folgenden Abschnitten werden häufige Aufgaben beschrieben, die Sie in Ihren Webhook-Handlern ausführen können.

Prompts senden

Sie können Prompts mit einfachem Text, Rich-Text, Karten und sogar vollständigen HTML-Prompts erstellen, die von einer Web-App mit Interactive Canvas unterstützt werden. In der Dokumentation zu Prompts finden Sie umfassende Informationen zum Erstellen eines Prompts beim Verarbeiten eines Webhook-Ereignisses. Die folgenden Snippets zeigen einen Karten-Prompt:

Node.js

app.handle('rich_response', conv => {
  conv.add('This is a card rich response.');
  conv.add(new Card({
    title: 'Card Title',
    subtitle: 'Card Subtitle',
    text: 'Card Content',
    image: new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

Antwort (JSON)

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "content": {
      "card": {
        "title": "Card Title",
        "subtitle": "Card Subtitle",
        "text": "Card Content",
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      }
    },
    "firstSimple": {
      "speech": "This is a card rich response.",
      "text": ""
    }
  }
}

Intent-Parameter lesen

Wenn die Assistant-Laufzeit einen Intent zuordnet, werden alle definierten Parameter extrahiert. Die ursprüngliche Eigenschaft ist das, was der Nutzer als Eingabe angegeben hat, und die aufgelöste Eigenschaft ist das, was die NLU basierend auf der Typspezifikation in die Eingabe aufgelöst hat.

Node.js

conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved

Anfrage (JSON)

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "intent_name",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Nutzergebietsschema lesen

Dieser Wert entspricht der Gebietsschemaeinstellung des Nutzers für Google Assistant.

Node.js

conv.user.locale

JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Speicher lesen und schreiben

In der Dokumentation zum Speicher finden Sie umfassende Informationen zur Verwendung verschiedener Speicherfunktionen.

Node.js

//read
conv.session.params.key
conv.user.params.key
conv.home.params.key

// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value

Anfrage (JSON)

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    },
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Antwort (JSON)

{
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello world.",
      "text": ""
    }
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  }
}

Gerätefunktionen prüfen

Sie können die Funktionen eines Geräts prüfen, um verschiedene Nutzererlebnisse oder Unterhaltungsabläufe zu ermöglichen.

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");

Anfrage (JSON)

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO",
      "INTERACTIVE_CANVAS"
    ]
  }
}

Eine vollständige Liste der Oberflächenfunktionen finden Sie in der Capability Referenz.

Überschreibungen des Laufzeittyps

Mit Laufzeittypen können Sie Typspezifikationen zur Laufzeit ändern. Mit dieser Funktion können Sie Daten aus anderen Quellen laden, um die gültigen Werte eines Typs festzulegen. Sie können beispielsweise Überschreibungen des Laufzeittyps verwenden, um einer Umfragefrage dynamische Optionen hinzuzufügen oder einem Menü einen täglichen Artikel hinzuzufügen.

Wenn Sie Laufzeittypen verwenden möchten, lösen Sie einen Webhook aus Ihrer Action aus, der einen Handler in Ihrer Auftragsausführung aufruft. Dort können Sie den Parameter session.typeOverrides in einer Antwort an Ihre Action festlegen. Verfügbare Modi sind TYPE_MERGE, um vorhandene Typeinträge beizubehalten, oder TYPE_REPLACE, um vorhandene Einträge durch die Überschreibungen zu ersetzen.

Node.js

conv.session.typeOverrides = [{
    name: type_name,
    mode: 'TYPE_REPLACE',
    synonym: {
      entries: [
        {
          name: 'ITEM_1',
          synonyms: ['Item 1', 'First item']
        },
        {
          name: 'ITEM_2',
          synonyms: ['Item 2', 'Second item']
       },
       {
          name: 'ITEM_3',
          synonyms: ['Item 3', 'Third item']
        },
        {
          name: 'ITEM_4',
          synonyms: ['Item 4', 'Fourth item']
        },
    ]
  }
}];

Antwort (JSON)

{
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [
      {
        "name": "type_name",
        "synonym": {
          "entries": [
            {
              "name": "ITEM_1",
              "synonyms": [
                "Item 1",
                "First item"
              ]
            },
            {
              "name": "ITEM_2",
              "synonyms": [
                "Item 2",
                "Second item"
              ]
            },
            {
              "name": "ITEM_3",
              "synonyms": [
                "Item 3",
                "Third item"
              ]
            },
            {
              "name": "ITEM_4",
              "synonyms": [
                "Item 4",
                "Fourth item"
              ]
            }
          ]
        },
        "typeOverrideMode": "TYPE_REPLACE"
      }
    ]
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  }
}

Sprachbiasing bereitstellen

Mit dem Sprachbiasing können Sie der NLU Hinweise geben, um die Intent-Zuordnung zu verbessern. Sie können bis zu 1.000 Einträge angeben.

Node.js

conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'

Antwort (JSON)

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  },
  "expected": {
    "speech": "['value_1', 'value_2']",
    "language": "locale_string"
  }
}

Szenenübergänge

Neben der Definition statischer Übergänge in Ihrem Actions-Projekt können Sie auch Szenenübergänge zur Laufzeit auslösen.

Node.js

app.handle('transition_to_hidden_scene', conv => {
  // Dynamic transition
  conv.scene.next.name = "HiddenScene";
});

Antwort (JSON)

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "HiddenScene"
    }
  }
}

Szenen-Slots lesen

Während der Slot-Ausfüllung können Sie die Auftragsausführung verwenden, um den Slot zu validieren oder den Status der Slot-Ausfüllung (SlotFillingStatus) zu prüfen.

Node.js

conv.scene.slotFillingStatus  // FINAL means all slots are filled
conv.scene.slots  // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties

Angenommen, Sie möchten die Zeitzone aus einer Antwort extrahieren. In diesem Beispiel lautet der Slot-Name datetime1. So rufen Sie die Zeitzone ab:

conv.scene.slots['datetime1'].value.time_zone.id

Anfrage (JSON)

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "FINAL",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "SLOT_UNSPECIFIED",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    },
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Szenen-Slots außer Kraft setzen

Sie können Slots außer Kraft setzen und den Nutzer auffordern, einen neuen Wert anzugeben.

Node.js

conv.scene.slots['slot_name'].status = 'INVALID'

Antwort (JSON)

{
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "INVALID",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Entwicklungsoptionen

Actions Builder bietet einen Inline-Editor namens Cloud Functions-Editor, mit dem Sie eine Cloud Function für Firebase direkt in der Konsole erstellen und bereitstellen können. Sie können die Auftragsausführung auch in Ihrem bevorzugten Hosting erstellen und bereitstellen und Ihren HTTPS-Endpunkt für die Auftragsausführung als Webhook-Handler registrieren.

Inline-Editor

So entwickeln Sie mit dem Cloud Functions-Editor:

Öffnen Sie Ihr Actions-Projekt und rufen Sie den Tab Entwickeln > Webhook > Methode für die Auftragsausführung ändern auf. Das Fenster Methoden für die Auftragsausführung wird angezeigt.
Wählen Sie Inline-Cloud-Funktionen aus und klicken Sie auf Bestätigen.

Externer HTTPS-Endpunkt

In diesem Abschnitt wird beschrieben, wie Sie Cloud Functions für Firebase als Dienst für die Auftragsausführung für Ihre Conversational Action einrichten. Sie können die Auftragsausführung jedoch in einem Hostingdienst Ihrer Wahl bereitstellen.

Umgebung einrichten

So richten Sie Ihre Umgebung ein:

Laden Sie Node.js herunter und installieren Sie es.
Richten Sie die Firebase CLI ein und initialisieren Sie sie. Wenn der folgende Befehl mit einem EACCES Fehler fehlschlägt, müssen Sie möglicherweise die npm-Berechtigungen ändern.
```
npm install -g firebase-tools
```
Authentifizieren Sie das Firebase-Tool mit Ihrem Google-Konto:
```
firebase login
```
Starten Sie das Projektverzeichnis, in dem Sie Ihr Actions-Projekt gespeichert haben. Sie werden aufgefordert, die Features der Firebase CLI auszuwählen, die Sie für Ihr Actions-Projekt einrichten möchten. Wählen Sie Functions und andere Features aus, die Sie verwenden möchten, z. B. Firestore, und drücken Sie die Eingabetaste, um zu bestätigen und fortzufahren:
```
$ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init
```
Verknüpfen Sie das Firebase-Tool mit Ihrem Actions-Projekt, indem Sie es mit den Pfeiltasten in der Projektliste auswählen:

Hinweis: Sie können diesen Schritt überspringen, indem Sie [don't setup a default project] auswählen. Sie müssen diese Verknüpfung dann aber später mit dem Befehl firebase use PROJECT_ID vornehmen.

Nachdem Sie das Projekt ausgewählt haben, startet das Firebase-Tool die Einrichtung von Functions und fragt Sie nach der gewünschten Sprache. Wählen Sie mit den Pfeiltasten aus und drücken Sie die Eingabetaste , um fortzufahren.

=== Functions Setup
A functions directory will be created in your project with a Node.js
package pre-configured. Functions can be deployed with firebase deploy.

? What language would you like to use to write Cloud Functions? (Use arrow keys)
> JavaScript
TypeScript

Geben Sie Y oder N ein, um festzulegen, ob Sie ESLint verwenden möchten, um wahrscheinliche Fehler zu erkennen und den Stil zu erzwingen:
```
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
```
Rufen Sie die Projektabhängigkeiten ab, indem Sie in der Eingabeaufforderung Y eingeben:
```
? Do you want to install dependencies with npm now? (Y/n)
```
Nach Abschluss der Einrichtung sehen Sie eine Ausgabe ähnlich der folgenden:
```
✔  Firebase initialization complete!
```

Installieren Sie die Abhängigkeit @assistant/conversation:

$ cd <ACTIONS_PROJECT_DIRECTORY>/functions
$ npm install @assistant/conversation --save

Rufen Sie die Abhängigkeiten für die Auftragsausführung ab und stellen Sie die Funktion für die Auftragsausführung bereit:
```
$ npm install
$ firebase deploy --only functions
```
Die Bereitstellung dauert einige Minuten. Nach Abschluss des Vorgangs sehen Sie eine Ausgabe ähnlich der folgenden. Sie benötigen die Funktions-URL , um sie in Dialogflow einzugeben.
```
✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview
Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>
```
Kopieren Sie die URL für die Auftragsausführung, die Sie im nächsten Abschnitt verwenden möchten.

Webhook-Handler registrieren

So registrieren Sie Ihren Cloud Functions-Endpunkt als Webhook-Handler:

Klicken Sie in der Actions-Konsole auf Entwickeln > Webhook.
Klicken Sie auf Methode für die Auftragsausführung ändern. Das Fenster Methoden für die Auftragsausführung wird angezeigt.
Wählen Sie Webhook aus und klicken Sie auf Bestätigen.
Fügen Sie die URL Ihres Webdienstes in das Feld Webhook ein.
Klicken Sie auf Speichern.

Webhooks Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Webhook-Trigger und ‑Handler

Nutzlasten

Beispielanfrage

Beispielantwort

Laufzeitinteraktionen

Prompts senden

Node.js

Antwort (JSON)

Intent-Parameter lesen

Node.js

Anfrage (JSON)

Nutzergebietsschema lesen

Node.js

JSON

Speicher lesen und schreiben

Node.js

Anfrage (JSON)

Antwort (JSON)

Gerätefunktionen prüfen

Node.js

Anfrage (JSON)

Überschreibungen des Laufzeittyps

Node.js

Antwort (JSON)

Sprachbiasing bereitstellen

Node.js

Antwort (JSON)

Szenenübergänge

Node.js

Antwort (JSON)

Szenen-Slots lesen

Node.js

Anfrage (JSON)

Szenen-Slots außer Kraft setzen

Node.js

Antwort (JSON)

Entwicklungsoptionen

Inline-Editor

Externer HTTPS-Endpunkt

Umgebung einrichten

Webhook-Handler registrieren

Webhooks