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

Diese Seite wurde von der Cloud Translation API übersetzt.

Switch to English

Webhooks

Um noch mehr Flexibilität beim Erstellen von Aktionen zu schaffen, können Sie die Logik an HTTPS-Webdienste (Ausführung) delegieren. Deine Aktionen können Webhooks auslösen, die Anfragen an einen HTTPS-Endpunkt senden. Die Auftragsausführung kann beispielsweise Folgendes umfassen:

Generieren einer dynamischen Anfrage auf der Grundlage der vom Nutzer bereitgestellten Informationen.
Eine Bestellung wird in einem externen System aufgegeben und der Vorgang wird bestätigt.
Slots mit Back-End-Daten validieren.

**Abbildung 1.** Aufrufaufrufe und -szenen können Webhooks auslösen.

Webhook-Trigger und -Handler

Ihre Aktionen können einen Webhook in Aufruf-Intents oder -Szenen auslösen, wodurch eine Anfrage an Ihren Auftragsausführungsendpunkt gesendet wird. Die Auftragsausführung enthält Webhook-Handler, die die JSON-Nutzlast in der Anfrage verarbeiten. In den folgenden Situationen können Sie Webhooks auslösen:

Nach einem Aufruf-Intent-Abgleich
Während des Betretens einer Szene
Nachdem eine Bedingung in der Bedingungsphase einer Szene ausgewertet wird
Während der Slot-Füllphase einer Szene
Nach einer Intent-Übereinstimmung in der Eingabephase einer Szene

Wenn Sie in Ihren Aktionen einen Webhook auslösen, sendet Google Assistant eine Anfrage mit einer JSON-Nutzlast an die Auftragsausführung, die den Namen des Handlers zur Verarbeitung des Ereignisses enthält. Der Auftragsausführungsendpunkt 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 von Ihren Aktionen an die Auftragsausführung gesendet werden, und eine Antwort, die von Ihrer Auftragsausführung zurückgegeben wird. Weitere Informationen finden Sie in der Referenzdokumentation.

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"
    }
  }
}

Interaktionen zur Laufzeit

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

Vorschläge senden

Mit Interaktivem Canvas können Sie Aufforderungen mit einfachem Text, Rich Text, Karten und sogar kompletten HTML-Aufforderungen erstellen, die von einer Webanwendung unterstützt werden. In der Dokumentation zu Eingabeaufforderung finden Sie umfassende Informationen zum Erstellen einer Eingabeaufforderung für die Verarbeitung eines Webhook-Ereignisses. Die folgenden Snippets zeigen eine Kartenaufforderung:

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 abgeglichen, werden alle definierten Parameter extrahiert. Die ursprüngliche Property war, was der Nutzer als Eingabe angegeben hat. Die aufgelöste Property hat die Eingabe in Bezug auf die Typspezifikation aufgelöst.

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"
    ]
  }
}

Nutzersprache lesen

Dieser Wert entspricht der Spracheinstellung 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"
    ]
  }
}

Lese- und Schreibzugriff

Ausführliche Informationen zur Verwendung der verschiedenen Speicherfeatures finden Sie in der Speicher-Dokumentation.

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 unterschiedliche Nutzungs- oder Gesprächsablä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 während der Laufzeit ändern. Mit diesem Feature können Sie Daten aus anderen Quellen laden, um gültige Werte eines Typs zu füllen. Mit Überschreibungen der Laufzeittypen können Sie beispielsweise einer Umfrage dynamische Optionen hinzufügen oder einem Menü ein tägliches Element hinzufügen.

Wenn Sie Laufzeittypen verwenden möchten, lösen Sie einen Webhook aus Ihrer Aktion aus, der einen Handler in Ihrer Auftragsausführung aufruft. Von dort aus können Sie den Parameter session.typeOverrides in einer Antwort auf Ihre Aktion befüllen. Zu den verfügbaren Modi gehören 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."
    }
  }
}

Sprachgewichtung bereitstellen

Mit der Sprachgewichtung können Sie Hinweise auf den NLU angeben, um den Intent-Abgleich 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"
  }
}

Übergangsszenen

Neben der Definition statischer Übergänge in Ihrem Actions-Projekt können Sie Übergänge für die Szene zur Laufzeit durchführen.

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"
    }
  }
}

Szenenslots lesen

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

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 Slotname 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"
    ]
  }
}

Szenenslots entwerten

Sie können Slots entwerten und den Nutzer dazu bewegen, 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 Functions for Firebase-Funktion direkt in der Console erstellen und bereitstellen können. Sie können die Auftragsausführung auch in Ihrem bevorzugten Hosting erstellen und bereitstellen und Ihren HTTPS-Auftragsausführungsendpunkt als Webhook-Handler registrieren.

Inline-Editor

So entwickeln Sie mit dem Cloud Functions-Editor:

Öffnen Sie Ihr Actions-Projekt und klicken Sie auf den Tab Develop > Webhook > Change fulfillment method. Das Fenster Auftragsausführungsmethoden wird angezeigt.
Wählen Sie Inline-Cloud Functions aus und klicken Sie auf Bestätigen.

Externer HTTPS-Endpunkt

In diesem Abschnitt wird beschrieben, wie Sie Cloud Functions for Firebase als Auftragsausführungsdienst für Ihre Unterhaltungsaktion 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 die Anwendung.
Firebase CLI einrichten und initialisieren Wenn der folgende Befehl mit dem Fehler EACCES fehlschlägt, müssen Sie möglicherweise 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 Firebase CLI-Features auszuwählen, die Sie für das Actions-Projekt einrichten möchten. Wählen Sie Functions und andere Features aus, die Sie eventuell verwenden möchten, z. B. Firestore. Drücken Sie zum Bestätigen und Fortfahren die Eingabetaste:
```
$ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init
```
Verknüpfen Sie das Firebase-Tool mit Ihrem Actions-Projekt, indem Sie es mithilfe der Pfeiltasten in der Projektliste auswählen:

Hinweis: Sie können diesen Schritt überspringen, indem Sie [kein Standardprojekt einrichten] auswählen. Diese Verknüpfung müssen Sie später mit dem Befehl firebase use PROJECT_ID durchführen.

Nachdem Sie das Projekt ausgewählt haben, startet das Firebase-Tool die Einrichtung der Funktion und fragt Sie, welche Sprache Sie verwenden möchten. Verwenden Sie die Pfeiltasten 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

Wählen Sie aus, ob Sie ESLint verwenden möchten, um wahrscheinliche Fehler abzufangen, und den Stil erzwingen, indem Sie Y oder N eingeben:
```
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
```
Rufen Sie die Projektabhängigkeiten ab, indem Sie Y in die Eingabeaufforderung eingeben:
```
? Do you want to install dependencies with npm now? (Y/n)
```
Sobald die Einrichtung abgeschlossen ist, sollte die Ausgabe in etwa so aussehen:
```
✔  Firebase initialization complete!
```

Installieren Sie die Abhängigkeit @assistant/conversation:

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

Rufen Sie die Auftragsausführungsabhängigkeiten ab und stellen Sie die Auftragsausführungsfunktion bereit:

$ npm install
$ firebase deploy --only functions

Die Bereitstellung dauert einige Minuten. Die Ausgabe sollte in etwa so aussehen: 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 im nächsten Abschnitt verwendet werden soll.

Webhook-Handler registrieren

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

Klicken Sie in der Actions Console auf Develop > Webhook.
Klicken Sie auf Methode für die Auftragsausführung ändern. Das Fenster Auftragsausführungsmethoden wird angezeigt.
Wählen Sie Webhook aus und klicken Sie auf Bestätigen.
Fügen Sie Ihre Webdienst-URL in das Feld Webhook ein.
Klicken Sie auf Speichern.