Webhooks

Damit Sie Aktionen noch flexibler erstellen können, können Sie zu HTTPS-Webdiensten (Auftragsausführung). Ihre Aktionen können Webhooks auslösen, Anfragen an einen HTTPS-Endpunkt senden. Einige Beispiele dafür, was Sie in Die Auftragsausführung umfassen Folgendes:

• Dynamische Aufforderung generieren, die auf vom Nutzer bereitgestellten Informationen basiert.
• Eine Bestellung in einem externen System aufgeben und den Erfolg bestätigen
• Slots mit Back-End-Daten werden validiert.

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

Webhook-Trigger und -Handler

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

• Nach Abgleich eines Aufruf-Intents
• Während einer Szene im Eingangsbereich
• Nachdem eine Bedingung in der Bedingungsphase einer Szene als wahr ausgewertet wurde
• Während der Slot-Füllungsphase einer Szene
• Nachdem eine Intent-Übereinstimmung in der Eingabephase einer Szene stattgefunden hat

Wenn Sie in Ihren Aktionen einen Webhook auslösen, sendet Google Assistant eine Anfrage mit einer JSON-Nutzlast zu Ihrer Auftragsausführung hinzu, die die Name des Handlers, der zum Verarbeiten des Ereignisses verwendet werden soll. Der Auftragsausführungsendpunkt kann das Ereignis an den entsprechenden Handler weiterleiten, um die Logik auszuführen und einen entsprechende Antwort mit einer JSON-Nutzlast.

Nutzlasten

Die folgenden Snippets zeigen Beispielanfragen, an die deine Aktionen gesendet werden Fulfillment und eine Antwort, die von der Auftragsausführung zurückgesendet wird. Weitere Informationen finden Sie in der Referenzdokumentation finden Sie weitere Informationen Informationen.

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

Aufforderungen senden

Du kannst Prompts mit einfachem Text, Rich-Text, Karten und sogar HTML-Prompts, die von einer Web-App unterstützt werden, mit Interactive Canvas Die prompts-Dokumentation enthält vollständige Informationen zum Erstellen eines Prompts bei der 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 mit einem Intent übereinstimmt, extrahiert sie alle definierten Parameter. Die ursprüngliche Eigenschaft entsprach der Eingabe durch den Nutzer und der „Resolved“-Attribut ist das, in das die NLU die Eingabe auf Grundlage des Typs Spezifikation zu ändern.

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

Speicher lesen und schreiben

In der Dokumentation zu Speicher finden Sie umfassende Informationen dazu, wie Sie verschiedene Speicherfunktionen nutzen.

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 Funktionen oder Gesprächsabläufe.

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 Funktionen findest du in der Capability Referenz.

Laufzeittypüberschreibungen

Mit Laufzeittypen können Sie Typspezifikationen zur Laufzeit ändern. Sie können diese -Funktion zum Laden von Daten aus anderen Quellen, um die gültigen Werte eines Typs zu füllen. Für Sie können z. B. Laufzeittypüberschreibungen verwenden, um einer Umfrage dynamische Optionen hinzuzufügen. oder um einem Menü einen täglichen Artikel hinzuzufügen.

Zur Verwendung von Laufzeittypen lösen Sie über Ihre Aktion einen Webhook aus, der eine -Handler in der Auftragsausführung. Anschließend können Sie die session.typeOverrides als Antwort auf Ihre Aktion zurückgegeben. Verfügbar Modi umfassen 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

Mithilfe der Sprachgewichtung können Sie Hinweise für die NLU angeben, um die Zuordnung von Intents zu verbessern. Ich 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 führen zur Laufzeit Szenenübergänge.

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 mithilfe der Auftragsausführung den Slot validieren oder die Status der Slot-Füllung (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 In diesem Beispiel lautet der Name der Anzeigenfläche datetime1. Um die Zeitzone zu ermitteln, verwenden:

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 bringen, 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

<ph type="x-smartling-placeholder">

</ph> Actions Builder Actions SDK

Actions Builder bietet einen Inline-Editor namens Cloud Functions-Editor. mit dem Sie eine Cloud Functions-Funktion für Firebase direkt in der . Sie können die Auftragsausführung auch im Hosting Ihrer Wahl erstellen und bereitstellen und registrieren Sie den HTTPS-Auftragsausführungsendpunkt als Webhook-Handler.

Inline-Editor

Wichtig: Wenn Sie beim Erstellen und Bereitstellen der Auftragsausführung mit dem Cloud Functions-Inline-Editor Rechnungskonto mit Ihrem Projekt in Google Cloud verknüpfen. Diese Anforderung benötigt ab dem 17. August 2020. Anleitung zum Verknüpfen eines Rechnungskontos Ihrem Projekt in Google Cloud hinzufügen, finden Sie Ändern Abrechnungseinstellungen eines Projekts. Weitere Informationen finden Sie unter Kontingente und Weitere Informationen zu Preisen Informationen. Wir empfehlen dringend, ein Rechnungskonto so bald wie möglich zu verknüpfen um Dienstunterbrechungen zu vermeiden.

So entwickeln Sie mit dem Cloud Functions-Editor:

1. Öffnen Sie Ihr Actions-Projekt und rufen Sie den Tab Develop > Webhook > Ändern Auftragsausführungsmethode. Das Fenster Auftragsausführungsmethoden wird angezeigt.
2. Wählen Sie Inline Cloud Functions aus und klicken Sie auf Confirm (Bestätigen).

Tipp:Wenn Sie Änderungen an der Auftragsausführung vorgenommen haben aber noch nicht bereitgestellt haben, öffnen Sie den Simulator. werden gefragt, ob Sie die Änderungen in Ihrem Code bereitstellen oder die zuvor bereitgestellten Code.

Externer HTTPS-Endpunkt

In diesem Abschnitt wird beschrieben, wie Sie Cloud Functions for Firebase als Ausführungsdienst für Ihre Konversationsaktion. Sie können jedoch Auftragsausführung an einen Hostingdienst deiner Wahl.

Wichtig: Wenn Sie ein Produkt in einem der Auftragsausführung mit Cloud Functions für Firebase müssen Sie ein Rechnungskonto mit Ihrem Projekt in Google Cloud verknüpfen. Dieses die am 17. August 2020 in Kraft tritt. Anweisungen zum Verknüpfen ein Rechnungskonto zu Ihrem Projekt in Google Cloud hinzufügen, finden Sie unter Ändern Abrechnungseinstellungen eines Projekts. Weitere Informationen finden Sie unter Kontingente und Weitere Informationen zu Preisen Informationen. Wir empfehlen dringend, ein Rechnungskonto so bald wie möglich zu verknüpfen um Dienstunterbrechungen zu vermeiden.

Umgebung einrichten

So richten Sie Ihre Umgebung ein:

1. Laden Sie Node.js herunter und installieren Sie es.

2. Richten Sie die Firebase CLI ein und initialisieren Sie sie. Wenn der folgende Befehl fehlschlägt, einen EACCES-Fehler anzeigt, müssen Sie möglicherweise die npm-Berechtigungen ändern.

   npm install -g firebase-tools
   

3. Authentifizieren Sie das Firebase-Tool mit Ihrem Google-Konto:

   firebase login
   

4. Starten Sie das Projektverzeichnis, in dem Sie Ihr Actions-Projekt gespeichert haben. Sie werden aufgefordert, die Firebase CLI-Funktionen auszuwählen, für die Sie die Einrichtung vornehmen möchten Ihr Actions-Projekt. Wähle Functions und andere Funktionen aus, die dich interessieren könnten wie Firestore verwenden. Drücken Sie dann die Eingabetaste, um den Vorgang zu bestätigen und fortzufahren:

   $ cd <ACTIONS_PROJECT_DIRECTORY>
   $ firebase init
   

5. Verknüpfen Sie das Firebase-Tool mit Ihrem Actions-Projekt, indem Sie es über mit den Pfeiltasten durch die Projektliste:

   Hinweis: Sie können diesen Schritt überspringen, indem Sie [Richten Sie kein Standardprojekt ein], aber dann müssen Sie dies tun. Verknüpfung mit dem Befehl firebase use PROJECT_ID an.

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

7. Wählen Sie aus, ob Sie ESLint verwenden möchten, um mögliche Fehler zu erkennen und den Stil durch Eingabe von Y oder N zu erzwingen:

   ? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)

8. 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, sehen Sie in etwa folgende Ausgabe:

   ✔  Firebase initialization complete!
   

9. Installieren Sie die Abhängigkeit @assistant/conversation:

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

10. Rufen Sie die Abhängigkeiten der Auftragsausführung ab und stellen Sie die Auftragsausführungsfunktion bereit:

    $ npm install
    $ firebase deploy --only functions
    

    Die Bereitstellung dauert einige Minuten. Wenn Sie fertig sind, sehen Sie eine Ausgabe, die in etwa in das Folgende ein. Sie benötigen die Function URL (Funktions-URL), die Sie in Dialogflow eingeben.

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

11. Kopieren Sie die URL für die Auftragsausführung, die im nächsten Abschnitt verwendet werden soll.

Webhook-Handler registrieren

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

1. Klicken Sie in der Actions Console auf Develop > Webhook
2. Klicken Sie auf Auftragsausführungsmethode ändern. Das Fenster Auftragsausführungsmethoden angezeigt wird.
3. Wählen Sie Webhook aus und klicken Sie auf Confirm (Bestätigen).
4. Fügen Sie die Webdienst-URL in das Feld Webhook ein.
5. Klicken Sie auf Speichern.