Integrierte Intents (Dialogflow)

Ein integrierter Intent ist eine eindeutige Kennung, die Sie angeben können, um Google Assistant mitzuteilen, dass Ihre Aktion eine bestimmte Kategorie von Nutzeranfragen erfüllen kann. Hier sind einige Beispiele für Nutzeranfragen, die Assistant mit integrierten Intents zuordnet:

  • Integrierter Intent „Play game“: „Hey Google. Spiel ein Gedächtnisspiel.“
  • Integrierter Intent für „Get horoscope“: „Hey Google. Horoskop abrufen“

Während der Aktionserkennung kann Assistant Metadaten zu deiner Aktion verwenden, einschließlich der von dir angegebenen integrierten Intents, um sie Nutzern zu empfehlen. Assistant versucht außerdem, Parameter aus den Nutzerabfragen zu scannen und an deine Aktion zu übergeben, um Conversational-Rounds zu minimieren.

Eine vollständige Liste der integrierten Intents, die von Assistant unterstützt werden, einschließlich ihrer Parameter und Beispielnutzerabfragen, finden Sie in der Referenz zu integrierten Intents.

Integrierte Intents einbinden

Je nachdem, wie Sie Ihre Aktion erstellen, gibt es verschiedene Möglichkeiten, integrierte Intents zu integrieren.

Dialogflow

Wenn Sie die Aktion mit Dialogflow erstellen, können Sie einen integrierten Intent über die Dialogflow-Konsole einbinden.

So hängen Sie einen integrierten Intent mit Dialogflow an:

  1. Öffnen Sie die Dialogflow-Konsole, wählen Sie den Agent aus und rufen Sie dann den Bildschirm Intents auf.
  2. Erstellen oder wählen Sie den Intent aus, der vom Agent ausgelöst wird, wenn er einen bestimmten integrierten Intent empfängt. Öffnen Sie den Bereich Ereignisse und klicken Sie auf Ereignis hinzufügen.

    Abbildung 1. Dialogflow-Ereignis in der Dialogflow-Konsole hinzufügen
  3. Geben Sie im Feld Events (Ereignisse) den Namen eines integrierten Intent-Ereignisses für den Agent ein (z. B. actions_intent_PLAY_GAME).

    Abbildung 2. Integrierten Intent in der Dialogflow-Konsole an den Agent anhängen.
  4. Klicken Sie auf Speichern.

Actions SDK

Wenn Sie das Actions SDK zum Erstellen Ihrer Aktion verwenden, müssen Sie die Zuordnung zwischen integrierten Intents und den Aktionen in Ihrem Aktionspaket angeben.

So hängen Sie einen integrierten Intent mit dem Actions SDK an:

  1. Geben Sie den integrierten Intent in der Definition von Action im Namensfeld an.
  2. Laden Sie das Aktionspaket mithilfe des gactions-Tools in Ihr Actions-Projekt hoch, wie unter Actions SDK – Übersicht beschrieben.

Das folgende Snippet zeigt beispielsweise, wie Sie den integrierten Intent CHECK_AIR_QUALITY hinzufügen können:

{
   "actions":[
      {
         "description":"Default Welcome Intent",
         "name":"MAIN",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.MAIN"
         }
      },
      {
         "description":"Check Air Quality",
         "name":"CHECK_AIR_QUALITY",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.CHECK_AIR_QUALITY"
         }
      }
   ],
   "conversations":{
      "conversation_1":{
         "name":"conversation_1",
         "url":"https://example.com/fulfillment",
         "fulfillmentApiVersion":2
      }
   }
}

Integrierte Intent-Parameter verarbeiten

Wenn Ihre Aktion über einen integrierten Intent aufgerufen wird, erhält die Auftragsausführung möglicherweise zusätzliche Parameter. Das Intent-Schema definiert die Namen der Parameter und ihre Typen als primitive Typen oder schema.org-Entitäten. Informationen zum Schema für integrierte Intents der Konversationsaktion finden Sie in der Referenz zu integrierten Intents.

Parameter für integrierte Intents sind optional. Assistant füllt die Parameter mit Werten, wenn diese aus dem Aufruf des integrierten Intents durch den Nutzer extrahiert werden können.

Im Schema des integrierten Intents actions.intent.CHECK_AIR_QUALITY sind beispielsweise vier optionale Parameter definiert:

Parametername Typ
attributes Ein String-Wert.
location Ein schema.org/Place-Objekt.
temporalCoverage Ein schema.org/Duration-Objekt.
timeIndicator Eine EnumeratedDuration (Google-spezifische Erweiterung).

Das folgende Code-Snippet zeigt ein Beispiel für die JSON-Anfrage (Unterhaltungs-Webhook), wenn ein Nutzer Ihre Aktion aufruft, indem er "What's the Air quality in San Francisco today?" (Wie hoch ist die Luftqualität in San Francisco morgen)?

"inputs":[
      {
         "intent":"actions.intent.CHECK_AIR_QUALITY",
         "rawInputs":[
            {
               "inputType":"VOICE",
               "query":"what is the air quality in san francisco tomorrow"
            }
         ],
         "arguments":[
            {
               "name":"location",
               "structuredValue":{
                  "geo":{
                     "longitude":-122.41941550000001,
                     "latitude":37.7749295
                  },
                  "@context":"https://schema.org",
                  "@type":"Place",
                  "name":"san francisco"
               }
            },
            {
               "name":"temporalCoverage",
               "rawText":"2018-04-25",
               "textValue":"2018-04-25"
            }
         ]
      }
   ]

In diesem Beispiel verwenden die Parameter die folgenden Werte:

  • Der Parameter location enthält den Wert schema.org/Place für „San Francisco“.
  • Der Parameter temporalCoverage enthält den Wert schema.org/Duration für das morgige Datum in Bezug auf die Uhrzeit des Aufrufs.
  • Für die Parameter attributes und timeIndicator sind keine Werte vorhanden, da die Aufrufwortgruppe des Nutzers solche Informationen nicht enthielt.

Wenn Sie die Actions on Google-Clientbibliothek für Node.js verwenden, können Sie den Wert der Parameter wie im folgenden Snippet sehen:

app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
  const attributes = conv.arguments.get('attributes');
  const location = conv.arguments.get('location');
  const temporal_coverage = conv.arguments.get('temporalCoverage');
  Const time_indicator = conv.arguments.get('timeIndicator')

  // Your Action logic. If you need to use any of the parameter values,
  // you should check first that it is defined. Arguments.get returns
  // undefined if it can't find a value for a parameter.

});

Integrationen mit integrierten Intents testen

So testen Sie die Integration:

  1. Öffne den Actions-Simulator mit aktivierter Testaktion oder öffne Assistant auf deinem Gerät.
  2. Sprechen oder geben Sie eine Abfrage ein, die mit diesem integrierten Intent verknüpft ist. Beispiel: "Ich möchte ein Spiel spielen."
  3. Suche im angezeigten Dialogfeld zur App-Auswahl nach deiner Aktion.
  4. Wählen Sie Ihre App aus, um einen Intent an Ihre App zu senden.
Abbildung 3. Das Dialogfeld zur Aktionsauswahl, das
aus einer integrierten Intent-Wortgruppe resultiert.
Abbildung 4. Durch Aufrufen einer Aktion, die mit einem integrierten Intent verknüpft ist.

Best Practices für die Verwendung von integrierten Intents

Bei Verwendung von integrierten Intents sollten Sie die folgenden Best Practices befolgen:

  • Eingebundene Intents bestimmten Aktionen zuordnen: Wenn ein bestimmter integrierter Intent eine Aktion auslöst, leiten Sie den Nutzer so reibungslos wie möglich zum spezifischen Intent und zur jeweiligen Funktionalität Ihrer Aktion weiter. Wenn deine Aktion beispielsweise den integrierten Intent PLAY_GAME unterstützt und diesen erhält, solltest du den Nutzer sofort zur Spielfunktion deiner Aktion weiterleiten. Fragen Sie den Nutzer nicht noch einmal, ob er ein Spiel spielen möchte.
  • Integrierte Intent-Parameter verarbeiten: Verwenden Sie unbedingt die integrierten Intent-Parameterwerte, die Assistant an die Auftragsausführung sendet. Fordern Sie den Nutzer nicht noch einmal zur Eingabe dieser Werte auf.