Metadateneigenschaft in gemeinsamen Antwortkomponenten

Mit der Eigenschaft "Metadaten" in Komponenten für gemeinsame Antworten definieren Sie, wie Nachrichten Benutzern angezeigt werden.

Sie definieren die Metadaten auf zwei Ebenen: auf der Root-Ebene, auf der Sie die Ausgabe und Aktionen definieren, die für die Komponente selbst spezifisch sind, und auf der Antwortebene, auf der Sie die Anzeige und das Verhalten für die von dieser Komponente ausgegebenen Text-, Listen-, Karten- oder Anhangsnachrichten definieren.
metadata:
  responseItems:
  - text: "To which location do you want the pizza to be delivered?"
    type: "text"
    name: "What location"
    separateBubbles: true
  globalActions:
  - label: "Send Location"
    type: "location"
    name: "SendLocation"
Eigenschaft Beschreibung Erforderlich?
responseItems Eine Liste mit Antwortelementen, die jeweils dazu führen, dass eine neue Nachricht an den Chatclient gesendet wird (oder mehrere Nachrichten, wenn Sie die Iteration für das Reaktionselement mit der Eigenschaft iteratorVariable oder einer Kombination der Eigenschaften iteratorVariable und iteratorExpression festlegen). Definieren Sie diese Antwortelemente anhand der folgenden Werte:
  • text - Textblasen (die Eigenschaft text), die eine Liste mit Schaltflächen enthalten können, die normalerweise als Schaltflächen angezeigt werden.

    Bei Mischentitys (d.h. die Eigenschaft variable benennt eine Mischentityvariable) können Sie einen FreeMarker-Ausdrucks-Prompt für einen Wert für die aktuelle Entity ( “${system.entityToResolve.value.prompt}”) verwenden.

  • cards - Eine Reihe von Karten, die horizontal oder vertikal scrollen.

  • attachment - Ein Bild-, Audio-, Video- oder Dateianhang, den Benutzer hochladen oder herunterladen können.

  • editForm - Ein interaktives Formular.
  • form
  • dataSet
Ja
globalActions Eine Liste mit globalen, d.h. für keine der Antwortelemente spezifischen Aktionen. Diese Aktionen werden normalerweise unten im Chatfenster angezeigt. In Facebook Messenger werden diese Optionen beispielsweise als Schnellantworten bezeichnet. Nein
keywords Eine Liste mit Schlüsselwörtern, die mit den Schlüsselwörtern übereinstimmen, die von einem Benutzer für eine entsprechende Postback-Payload eingegeben wurden. Schlüsselwörter unterstützen Nur-Text-Kanäle, bei denen Aktionsschaltflächen nicht gut dargestellt werden können. Nein
Außerdem konfigurieren Sie die Metadaten für die verschiedenen Antwortelemente, wie Text, Karten oder Anhangsnachrichten.
Eigenschaft Beschreibung Erforderlich?
type Der Typ des Antwortelements, das das Nachrichtenformat bestimmt. Sie können eine Nachricht als text, attachment oder cards festlegen. Ja
name Ein Name für das Antwortelement, der intern verwendet wird. Er wird nicht zur Laufzeit verwendet. Nein
iteratorVariable Fügt der Antwort dynamisch mehrere Text-, Anhangs- oder Schlüsselwortelemente hinzu, indem die Variablenelemente durchlaufen werden. Nein
iteratorExpression Ein FreeMarker-Ausdruck, mit dem Werte aus einem Array angezeigt werden, das innerhalb der Variablen verschachtelt ist, die mit der Eigenschaft iteratorVariable angegeben wird.

Beispiel: Wenn Sie den Wert der Eigenschaft iteratorVariable auf "team" gesetzt haben und diese Variable ein Element mit dem Namen members enthält, dessen Werte Sie anzeigen möchten, verwenden Sie den Ausdruck ${team.value.members}.

Nein
visible Bestimmt, wie Nachrichten pro Benutzereingabe und Kanal angezeigt werden. Siehe Die sichtbare Eigenschaft. Nein
rangeStart Wenn Sie eine iteratorVariable angegeben haben, können Sie eine Teilmenge von Antwortelementen ausschließen, indem Sie die Eigenschaft rangeStart in Verbindung mit der Eigenschaft rangeSize angeben. Sie können einen hartcodierten Wert eingeben oder einen FreeMarker-Ausdruck verwenden, der auf eine Dialogablaufvariable verweist, die den Anfang des Bereichs enthält. Wenn Sie eine rangeStart-Variable verwenden, können Sie zur nächsten Gruppe von Daten blättern, indem Sie die Variable rangeStart in der Payload der Durchsuchen-Option festlegen. Ein Beispiel der Eigenschaften rangeStart und rangeSize finden Sie im StatusOrderPizza von CrcPizzaBot. Nein
rangeSize Die Anzahl der Antwortelemente, die wie in den Eigenschaften iteratorVariable und rangeStart angegeben angezeigt werden. Nein
channelCustomProperties Eine Liste der Eigenschaften, die kanalspezifische Funktionen auslösen. Da diese Funktionen plattformspezifisch sind, befinden sie sich außerhalb der Komponente "Allgemeine Antwort" und können daher nicht von den Eigenschaften auf Root-Ebene der Komponente oder auf Elementebene der Antwort gesteuert werden. Ein Beispiel für diese Eigenschaft finden Sie im Status OrderPizza von CrcPizzaBot.
channelCustomProperties:
          - channel: "facebook"
            properties:
              top_element_style: "large"
Einzelheiten zur Verwendung von channelCustomProperties sowie zu den verfügbaren Eigenschaften für jeden Kanal finden Sie unter Kanalspezifische Erweiterungen.
Nein

Eigenschaften von Schlüsselwortmetadaten

Sie können Verknüpfungen für Aktionen erstellen, indem Sie das Schlüsselwort und die Labeleigenschaften definieren. Beispiel: Benutzer können K für Klein eingeben.

Das folgende Snippet veranschaulicht, wie eine Gruppe von Schlüsselwörtern aus einer pizzaSize-Variablen generiert werden kann, in der die für eine PizzaSize-Entity definierte Werteliste enthalten ist.
      
responseItems:         
- type: "text"  
  text: "What size of pizza do you want?" 
  actions: 
  - label: "(${enumValue[0]?upper_case})${enumValue?keep_after(enumValue[0])}"
    type: "postback"
    keyword: "${enumValue[0]?upper_case},${(enumValue?index)+1}"
    payload: 
      variables: 
        pizzaSize: "${enumValue}" 
    iteratorVariable: "pizzaSize.type.enumValues"
Eigenschaft Beschreibung Erforderlich?
keyword Eine Liste mit Schlüsselwörtern, die die Postback-Payload auslösen, die durch die Eigenschaft payload definiert wird. Sie können einen FreeMarker-Ausdruck verwenden, um Schlüsselwörter zurückzugeben, die die Eigenschaft interatorVariable aus Wertelistenentitys generiert, indem Sie die Eigenschaften type und enumValues (iteratorVariable: "pizzaSize.type.enumValues") verwenden. Ja
label Das Label für die Aktion. Dabei kann es sich um eine Textzeichenfolge oder einen Apache FreeMarker-Ausdruck handeln. Beispiel: Ein Ausdruck, der ein Schlüsselwort aus zwei Buchstaben angibt, sieht folgendermaßen aus:

label: "(${enumValue[0]?upper_case}${enumValue[1]?upper_case})${enumValue?keep_after(enumValue[1])}"

Verwenden Sie für die Unterstützung mehrerer Sprachen einen Apache FreeMarker-Ausdruck, der auf ein Resource Bundle verweist.
Nein
skipAutoNumber Setzen Sie diese Eigenschaft auf true, um die automatische Nummerierung für ein Schlüsselelement zu unterdrücken, wenn die Option Automatische Nummerierung auf Karten aktivieren auf der Ebene des digitalen Assistenten oder des Skills festgelegt ist. Nein
visible Bestimmt, wie Textnachrichten pro Benutzereingabe und Kanal angezeigt werden. Siehe Die sichtbare Eigenschaft Nein
iteratorVariable Fügt mehrere Schlüsselwörter dynamisch hinzu, indem die Elemente, die in der angegebenen Variablen gespeichert sind, iteriert werden. Beispiel: iteratorVariable: "pizzaSize.type.enumValues". Nein
iteratorExpression Ein FreeMarker-Ausdruck, mit dem Werte aus einem Array angezeigt werden, das innerhalb der Variablen verschachtelt ist, die mit der Eigenschaft iteratorVariable angegeben wird.

Beispiel: Wenn Sie den Wert der Eigenschaft iteratorVariable auf "team" gesetzt haben und diese Variable ein Element mit dem Namen members enthält, dessen Werte Sie anzeigen möchten, verwenden Sie den Ausdruck ${team.value.members}.

payload Die Postback-Payload mit den folgenden Eigenschaften.
  • action - Die Zielaktion.
  • <variable names> - Legt Werte für Variablen fest.
Sie müssen mindestens eine dieser Eigenschaften definieren. Siehe Die Payload-Eigenschaften.
 

Schlüsselwörter aus Nachrichten extrahieren

Wenn die Komponente einen Postback auslöst, wenn Benutzer eine Nummer eingeben, können Sie Ihren Skill erweitern, um eine umfassende Eingabe wie Erste, oder 1. Artikel ausprobieren zu unterstützen. Erstellen Sie dazu eine Arrayvariable für die Schlüsselwortgruppen (z. B. erste,1.,eine, zweite, 2., zwei usw.)

Referenzieren Sie dann die Variable in der Eigenschaft keyword in den Metadaten. So könnte es beispielsweise in einem Ablauf für die Bestellung einer Pizza aussehen.
- keyword: "${pizzas.name},<#if pizzas?index <KEYWORDS_VAR.value?size>${numberKeywords.value[pizzas?index].keywords}</#if>,<#if pizzas?index==cardsRangeStart?number+[cardsRangeStart?number+3,pizzaCount.value?number-cardsRangeStart?number-1]?min>last</#if>"
In dieser Definition basiert das letzte Schlüsselwort auf dem Anfang des aktuellen Bereichs. Sie ist auf die letzte Pizza gesetzt, die derzeit angezeigt wird, basierend auf der Häufigkeit, mit der der Kunde "Mehr" eingegeben hat.

Die sichtbare Eigenschaft

Legen Sie die Anzeige entsprechend der Benutzereingabe und dem Kanal fest, indem Sie die optionale Eigenschaft visible verwenden.
Eigenschaft Beschreibung Erforderlich?
expression Die Apache FreeMarker-Anweisung, mit der Text, Karten oder Anhänge bedingt angezeigt oder ausgeblendet werden. Beispiel: Der Status OrderPizza von CrcPizzaBot verwendet ""<#if cardsRangeStart?number+4 < pizzas.value?size && textOnly=='false'>true<#else>false</#if>". Nein
channels:
 include:
 exclude:
Geben Sie für include und exclude eine durch Komma getrennte Liste der Kanaltypen ein, für die Text, Karte oder Anhang angezeigt (include) oder ausgeblendet (exclude) werden sollen. Gültige Kanalwerte sind:
  • facebook

  • webhook

  • websdk

  • androidsdk

  • iossdk

  • twilio

  • slack

  • msteams

  • cortana

  • test

metadata:
  responseItems:
  - type: "text"
    text: "This text is only shown in Facebook Messenger"
    visible:
      channels:
        include: "facebook"             
  - type: "text"
    text: "This text is NOT shown in Facebook Messenger and Twilio"
    visible:
      channels:
        exclude: "facebook, twilio"
    actions:
    - label: "This action is only shown on web channel"
      type: "postback"
      payload:
        action: "someAction"
      visible:
        channels:
          include: "websdk"
Nein
onInvalidUserInput Ein boolesches Flag, das das Textelement oder den Anhang anzeigt, wenn der Benutzer eine gültige Eingabe eingibt (value=false) oder wenn der Benutzer eine ungültige Eingabe eingibt (value=true). Nein
onDisambiguation Wenn true verwendet wird, werden nur das Antwortelement, die Karte oder die Aktion angezeigt, wenn ein Disambiguierungs-Prompt angezeigt wird. Nein
entitiesToResolve Mit dieser Eigenschaft können Sie benutzerdefinierte Nachrichten für jedes Mischentityelement erstellen. Fügen Sie eine durch Komma getrennte Liste mit Mischentityelementnamen hinzu, für die das Antwortelement angezeigt (include) oder ausgeblendet (exclude) werden soll.
visible:
           entitiesToResolve:
           include: "Amount"
Nein

Eigenschaften der Aktionsmetadaten

Sie können Aktionen für eine Karte oder Listen, einen Antworttyp oder globale Aktionen für eine Komponente definieren (wie die Schnellantwortaktionen auf Facebook). Sie können keine Aktionen für Anhangsnachrichten konfigurieren.

Eigenschaft Beschreibung Erforderlich?
type Aktionstyp:
  • postback: Gibt ein JSON-Objekt zurück, das den Status, die Aktion und Variablen enthält.

  • share - Öffnet ein Dialogfeld zum Teilen im Messenger-Client, in dem Benutzer Nachrichtenblasen mit ihren Freunden teilen können.

  • call - Ruft die in der Payload angegebene Telefonnummer an.

  • url - Öffnet die URL, die in der Payload im Browser angegeben wird. Für Facebook Messenger können Sie die Eigenschaft channelCustomProperties mit webview_height_ratio, messenger_extensions und fallback_url angeben.

  • location - Übermittelt die aktuelle Position. In Facebook Messenger wird der aktuelle Standort für Text- oder Kartenantworten nicht unterstützt. Dies wird nur mit einer Kurzantwort unterstützt. Weitere Informationen finden Sie in der Dokumentation zur Facebook Messenger-Plattform.

Ja
label Ein Label für die Aktion. Um dieses Label zu lokalisieren, können Sie einen FreeMarker-Ausdruck verwenden, um einen Eintrag im Resource Bundle des Bots zu referenzieren. Ja
iteratorVariable Mit dieser Option können Sie mehrere Aktionen hinzufügen, indem Sie die in der angegebenen Variablen gespeicherten Elemente iterieren. Sie können diese Eigenschaft nicht mit den Aktionen "Teilen" und "Standort" verwenden. Nein
iteratorExpression Ein FreeMarker-Ausdruck, mit dem Werte aus einem Array angezeigt werden, das innerhalb der Variablen verschachtelt ist, die mit der Eigenschaft iteratorVariable angegeben wird.

Beispiel: Wenn Sie den Wert der Eigenschaft iteratorVariable auf "team" gesetzt haben und diese Variable ein Element mit dem Namen members enthält, dessen Werte Sie anzeigen möchten, verwenden Sie den Ausdruck ${team.value.members}.

Nein
imageUrl Die URL des Bildes, das für ein Symbol verwendet wird, das eine Aktion identifiziert. Mit dieser Eigenschaft können Sie ein Symbol für die Facebook-Schaltfläche "Kurzantwort" anzeigen (dies ist eine globale Aktion). Nein
skipAutoNumbering Wenn diese Eigenschaft auf true gesetzt ist, wird eine einzelne Postback-Aktion davon ausgenommen, dass die automatische Nummerierung auf sie angewendet wird. Sie können diese Eigenschaft für eine Text- oder Kartenantwort verwenden. Nein
channelCustomProperties Eine Liste der Eigenschaften, die bestimmte kanalspezifische Funktionen auslösen, die nicht von den Standardaktionseigenschaften gesteuert werden. Ein Beispiel hierzu finden Sie im Status OrderPizza von CrcPizzaBot. Nein
name Ein Name, der die Aktion auf der Digital Assistant-Plattform identifiziert. Dieser Name wird intern verwendet und nicht in der Nachricht angezeigt. Nein
visible Bestimmt, wie Anhänge pro Benutzereingabe und Kanal angezeigt werden. Siehe Die sichtbare Eigenschaft. Nein
payload Ein Payload-Objekt für die Antwortelemente call, url und postback. Siehe Die Payload-Eigenschaften. Nein

Die Payload-Eigenschaften

Eigenschaft Beschreibung Erforderlich?
action Ein action-Übergang, der ausgelöst wird, wenn der Benutzer diese Aktion auswählt. Nein
variables Legt die Werte für Variablen fest, wenn Sie den Aktionstyp auf postback setzen, und fügen Sie Payload-Eigenschaften hinzu, die für die Variablen benannt sind. Wenn der Benutzer auf die Aktion tippt, werden die Variablen auf die Werte gesetzt, die von dieser Eigenschaft angegeben werden. Nein
url Die URL der Website, die geöffnet wird, wenn Benutzer auf diese Aktion tippen. Diese Eigenschaft ist für den Aktionstyp url erforderlich.
phoneNumber Die Telefonnummer, die angerufen wird, wenn ein Benutzer auf diese Aktion tippt. Diese Eigenschaft ist für den Aktionstyp call erforderlich.

Wie werden Nicht-Postback-Aktionen in Nur-Text-Kanälen angezeigt?

Für diese Aktionsmetadateneigenschaften für gemeinsame Antwortkomponenten sind einige Punkte zu beachten.

  • Wenn der Nur-Text-Kanal Hyperlinks unterstützt, können Sie diese anstelle von Schaltflächen verwenden, wenn der globale Aktionstyp url oder call ist.

  • Die Aktionstypen share und location werden ignoriert oder nicht angezeigt.

Tipp:

Nicht-Postback-Aktionen wie url und call können nicht nummeriert werden, da sie nicht an die Dialog-Engine übergeben werden und daher nicht durch Schlüsselwörter ausgelöst werden können. Wenn Sie also die beiden Aktionstypen mischen, kann die Nachricht Ihres Bots inkonsistent aussehen, da nur einige Optionen nummeriert werden.
Ein Laufzeitbild einer Nicht-Postback- und einer Postback-Nummerierung.
Mit dem SDK können Sie eine konsistentere Ausgabe erstellen, indem Sie die automatische Nummerierung für das Postback deaktivieren. Beispiel:
{
  "type": "text",
  "text": "Please choose one of the following options",
  "actions": [
    {
      "type": "url",
      "label": "Check out our website",
      "url": "http://www.oracle.com"
    },
    {
      "type": "postback",
      "label": "<#if autoNumberPostbackActions.value>Enter 1 to Order pizza<#else>Order Pizza<#if>"
      "skipAutoNumber": true
      "keyword": "1"
      "postback": { ...}
    }
  ]
}

Das Textantwortelement

Im Folgenden werden die Eigenschaften für Textreaktionselemente in gemeinsamen Antwortkomponenten aufgeführt.

Eigenschaft Beschreibung Erforderlich?
text Der Text der Benutzereingabeaufforderung. Ja
iteratorExpression Ein FreeMarker-Ausdruck, mit dem Werte aus einem Array angezeigt werden, das innerhalb der Variablen verschachtelt ist, die mit der Eigenschaft iteratorVariable angegeben wird.

Beispiel: Wenn Sie den Wert der Eigenschaft iteratorVariable auf "team" gesetzt haben und diese Variable ein Element mit dem Namen members enthält, dessen Werte Sie anzeigen möchten, verwenden Sie den Ausdruck ${team.value.members}.

 
iteratorVariable Fügt der Antwort dynamisch mehrere Text-, Anhangs- oder Schlüsselwortelemente hinzu, indem die Variablenelemente durchlaufen werden. Nein
footerText Text, der unten in der Nachricht angezeigt wird (unter den Text- und Schaltflächenaktionen, sofern vorhanden). Fügen Sie einen Footer hinzu, um die Ausgabe in textbasierten Kanälen zu erweitern. Wie unter Footer beschrieben, können Sie FreeMarker-Ausdrücke verwenden, um den Footertext für Nur-Text-Kanäle bedingt zu formatieren. Nein
separateBubbles Sie können diese Eigenschaft definieren, wenn Sie auch die Eigenschaft iteratorVariable definieren. Wenn Sie diese Eigenschaft auf true setzen, wird jedes Textelement als separate Nachricht gesendet, wie Pizzas und Pasta in den Status ShowMenu und OrderPizza von CrcPizzaBot. Wenn Sie diesen Wert auf false setzen, wird eine einzelne Textnachricht gesendet, in der jedes Textelement in einer neuen Zeile beginnt. Nein
visible Bestimmt, wie Textnachrichten pro Benutzereingabe und Kanal angezeigt werden. Siehe Die sichtbare Eigenschaft. Nein
actions Die Postback-Aktion. Für die Nur-Text-Unterstützung können Sie Schlüsselwörter definieren. Nein
Ein Beispiel für eine Textantwort mit Aktionen finden Sie in den Metadaten für den Status showMenu von CrcPizzaBot: Da er postback als Aktion benennt, kann der Skill ein unerwartetes Benutzerverhalten verarbeiten, wie das Auswählen eines Elements aus einer älteren Nachricht statt eines aus der letzten Nachricht.
metadata:
  responseItems:
    - type: "text"
      text: "Hello ${profile.firstName}, this is our menu today:"
      footerText: "${(textOnly.value=='true')?then('Enter number to make your choice','')}"
      name: "hello"
      separateBubbles: true
      actions:
        - label: "Pizzas"
          type: "postback"
          keyword: "${numberKeywords.value[0].keywords}"
          payload:
            action: "pizza"
          name: "Pizzas"
        - label: "Pastas"
          keyword: "${numberKeywords.value[1].keywords}"
          type: "postback"
          payload:
            action: "pasta"
          name: "Pastas"

Das Kartenantwortelement

Im Folgenden werden die Eigenschaften für Kartenreaktionselemente in Common Response-Komponenten aufgeführt.

Eigenschaft Beschreibung Erforderlich?
cardLayout Das Kartenlayout: horizontal (Standard) und vertical. Ja
headerText Headertext. Beispiel: headerText: "<#if cardsRangeStart?number == 0>Diese Pizzas haben wir heute für Sie im Angebot:<#else>Noch mehr Pizzas für Sie:</#if>". Nein
title Der Kartentitel Ja
description Die Kartenbeschreibung, die als Untertitel angezeigt wird. Nein
imageUrl Die URL des Bildes, das unter dem Untertitel angezeigt wird. Nein
cardUrl Die URL einer Website. Sie wird als Hyperlink auf der Karte angezeigt, auf den Benutzer tippen können, um die Website zu öffnen. Nein
iteratorExpression Ein FreeMarker-Ausdruck, mit dem Werte aus einem Array angezeigt werden, das innerhalb der Variablen verschachtelt ist, die mit der Eigenschaft iteratorVariable angegeben wird.

Beispiel: Wenn Sie den Wert der Eigenschaft iteratorVariable auf "team" gesetzt haben und diese Variable ein Element mit dem Namen members enthält, dessen Werte Sie anzeigen möchten, verwenden Sie den Ausdruck ${team.value.members}.

 
iteratorVariable Fügt der Antwort mehrere Karten dynamisch hinzu, indem die Elemente, die in der Variablen gespeichert sind, die Sie für diese Eigenschaft angeben, iteriert werden. Obwohl Sie die Variable als Zeichenfolge definieren, enthält sie ein JSON-Array, wenn sie als Iteratorvariable verwendet wird. Sie können Eigenschaften in einem Objekt des Arrays mit einem Ausdruck wie ${iteratorVarName.propertyName} referenzieren. Beispiel: Mit einer Iteratorvariablen mit dem Namen pizzas kann die Namenseigenschaft einer Pizza mit dem Ausdruck ${pizzas.name} referenziert werden. Nein
rangeStart Wenn Sie eine iteratorVariable angegeben haben, können Sie eine Teilmenge von Karten ausschließen, indem Sie die Eigenschaft rangeStart in Verbindung mit der Eigenschaft rangeSize angeben. Sie können einen hartcodierten Wert eingeben oder einen FreeMarker-Ausdruck verwenden, der auf eine Variable verweist, die den Anfang des Bereichs enthält. Wenn Sie eine Variable rangeStart verwenden, können Sie zur nächsten Gruppe von Daten blättern, indem Sie die Variable rangeStart in der Payload einer Suchoption festlegen. Nein
rangeSize Die Anzahl der Karten, die wie mit den Eigenschaften iteratorVariable und rangeStart angegeben angezeigt werden. Nein
visible Bestimmt, wie Aktionslabels pro Benutzereingabe und Kanal angezeigt werden. Siehe Die sichtbare Eigenschaft. Nein

Sie können eine Gruppe von Aktionen zuweisen, die für eine bestimmte Karte spezifisch sind, oder eine Liste von Aktionen, die am Ende der Kartenliste angehängt sind.

Der Status OrderPizza von CrcPizzaBot enthält eine Definition eines Kartenantwortelements, wie im folgenden Snippet dargestellt:
responseItems:
  - type: "cards"
    headerText: "<#if cardsRangeStart?number == 0>Here are our pizzas you can order today:<#else>Some more pizzas for you:</#if>"
    cardLayout: "vertical"
    name: "PizzaCards"
    actions:
      - label: "More Pizzas"
        keyword: "more"
        type: "postback"
        skipAutoNumber: true
        visible:
          expression: "<#if cardsRangeStart?number+4 < pizzas.value?size && textOnly=='false'>true<#else>false</#if>"
        payload:
          action: "more"
          variables:
            cardsRangeStart: "${cardsRangeStart?number+4}"
        name: "More"
    cards:
      - title: "${(textOnly=='true')?then((pizzas?index+1)+'. ','')}${pizzas.name}"
        description: "${pizzas.description}"
        imageUrl: "${pizzas.image}"
        name: "PizzaCard"
        iteratorVariable: "pizzas"
        rangeStart: "${cardsRangeStart}"
        rangeSize: "4"
        actions:
          - label: "Order Now"
            type: "postback"
            payload:
              action: "order"
              variables:
                orderedPizza: "${pizzas.name}"
                orderedPizzaImage: "${pizzas.image}"
            name: "Order"
            visible:
              expression: "${(textOnly=='true')?then('false','true')}"

Wie werden Karten in Nur-Text-Kanälen wiedergegeben?

Gemeinsame Antwortkomponenten geben Antworten als Karten wieder. Wenn Ihr Skill in einem Nur-Text-Kanal ausgeführt wird, verhalten sich die Eigenschaften des Kartenantwortelements anders. Dabei sollten Sie einige Punkte beachten.

  • Es ist kein vertikaler oder horizontaler Bildlauf möglich (Verhalten wird mit der Option cardLayout festgelegt). Alle Karten werden in einer einzigen Nachrichtenblase wiedergegeben, die einen Header und einen Footer enthalten kann. Die Eigenschaften title und description der Karte sind durch ein Zeilenvorschubzeichen voneinander getrennt. Sie können die Titeleigenschaft der Karte nummerieren.

  • Hyperlinks werden weiterhin in Nur-Text-Kanälen unterstützt, wobei die für die Eigenschaft cardUrl konfigurierte Adresse innerhalb der Blase zusammen mit den Eigenschaften title und description wiedergegeben wird, die durch ein Zeilenvorschubzeichen voneinander getrennt sind.

  • Bilder, die in der Eigenschaft imageURL angegeben sind, werden wiedergegeben.

  • Der Labeltext für Aktionsschaltflächen wird angezeigt (auch wenn die Schaltflächen selbst nicht wiedergegeben werden). Benutzer können den Text eingeben. Wenn die automatische Nummerierung aktiviert ist, können sie stattdessen die entsprechende Nummer eingeben.


Karten in Nur-Text-Kanälen mit Schlüsselwörtern optimieren

Die meisten Karten umfassen eine einzelne Aktion, wie die CRCPizzaBot-Schaltfläche "Jetzt bestellen", und eine globale Aktion wie "Mehr" zum Laden der nächsten Karte im Karussell. Wie unter Wie werden Karten in Nur-Text-Kanälen wiedergegeben? dargestellt, wird das Label für jede Aktion automatisch nummeriert, wenn der Skill in SMS-/Nur-Text-Kanälen ausgeführt wird. In diesen Kanälen wird eine Gruppe von Karten in einer einzigen Blase dargestellt, die sehr lang und somit schwer zu lesen sein kann. Dies kann vermieden werden, indem Sie Postback-Aktionen konfigurieren, die nicht mit den Aktionslabels verknüpft sind, jedoch von Benutzerschlüsselwörtern ausgeführt werden (z.B. 1, 2, 3, Käse oder Mehr).


Beschreibung von cards-text-only.png folgt
Beschreibung der Abbildung cards-text-only.png

Sie können die Aktionslabels ausblenden, wenn Ihr Skill mit diesen allgemeinen Richtlinien in Nur-Text-Kanälen ausgeführt wird.

In der Metadateneigenschaft:
  • Definieren Sie die Eigenschaft keywords. Im folgenden CRCPizzaBot-Snippet definiert der für die Schlüsselworteigenschaft festgelegte Ausdruck ${pizza.name} ein Schlüsselwort für jeden Pizzanamen fest:
    
    metadata:
      keywords:
        - keyword: "${pizzas.name},<#if pizzas?index <numberKeywords.value?size>${numberKeywords.value[pizzas?index].keywords}</#if>,<#if pizzas?index==cardsRangeStart?number+[cardsRangeStart?number+3,pizzaCount.value?number-cardsRangeStart?number-1]?min>last</#if>"
          visible:
            expression: "${textOnly.value}"
    ...

    Diese Schlüsselwörter werden nur hinzugefügt, wenn textOnly "true" ist.

In den card-Metadaten:
  • Definieren Sie die Eigenschaft title. Im folgenden Snippet verwendet ein Ausdruck die FreeMarker-Variable index, um dem Titel eine Nummer als Präfix voranzustellen (die von ${pizzas.name} zurückgegeben wird, wenn der Wert der Variablen textOnly true ist). Das heißt, wenn ein Kunde Mehr eingibt, lädt der Skill eine weitere Nachrichtenblase mit der nächsten Gruppe von Pizzas, die bei Nummer 5 (rangeSize: "4") beginnt.
    cards:
            - title: "${(textOnly=='true')?then((pizzas?index+1)+'. ','')}${pizzas.name}"
              description: "${pizzas.description}"
              imageUrl: "${pizzas.image}"
              name: "PizzaCard"
              iteratorVariable: "pizzas"
              rangeStart: "${cardsRangeStart}"
              rangeSize: "4"
  • Im folgenden Snippet werden die Kartenaktionen ("Order" und "More Pizzas") nur angezeigt, wenn der Wert der Variablen textOnly auf false gesetzt ist:
            - label: "More Pizzas"
              keyword: "more"
              type: "postback"
              skipAutoNumber: true
              visible:
                expression: "<#if cardsRangeStart?number+4 < pizzas.value?size && textOnly=='false'>true<#else>false</#if>"
  • Fügen Sie einen Footer hinzu, der nur angezeigt wird, wenn der Wert der Variablen textOnly auf true gesetzt ist.
    footerText: "<#if textOnly=='true'>Enter a pizza number to make your choice<#if cardsRangeStart?number+4 < pizzas.value?size>, or type 'more' to see more pizzas</#if></#if>"

Das Anhangsantwortelement

Das Antwortelement attachment enthält die folgenden Eigenschaften.

Eigenschaft Beschreibung Erforderlich?
attachmentType Der Anhangstyp: image, audio, video und file. Ja
attachmentURL Die Download-URL oder Quelle des Anhangs. Ja
Der Status Confirmation von CrcPizzaBot verwendet ein Anhangsantwortelement, um ein Bild der Bestellung anzuzeigen, das sich von dem im Menü dargestellten Element unterscheidet.
metadata:
  responseItems:
  - text: "Thank you for your order, your ${pizzaSize} ${orderedPizza} pizza\
      \ will be delivered in 30 minutes at GPS position ${location.value.latitude},${location.value.longitude}!"
    type: "text"
    name: "conf"
    separateBubbles: true
  - type: "attachment"
    attachmentType: "image"
    name: "image"
    attachmentUrl: "${orderedPizzaImage}"

Aktion

Eine Aktion steht für ein Element, das der Benutzer auswählen kann.
Name Beschreibung Typ Erforderlich?
type Aktionstyp Zeichenfolge Ja
label Der beschreibende Labeltext für die Aktion. Zeichenfolge Mindestens ein label- oder imageUrl-Wert muss angegeben werden.
imageUrl Das Bild für die Aktion Zeichenfolge Mindestens eine einzelne label- oder imageUrl-Eigenschaft muss enthalten sein.
style Der Rendering-Stil der Schaltfläche "primary", "danger", "default" Nein
displayType Das Rendering für den Typ des Aktionselements (Schaltfläche, Link oder Symbol) "button", "link", "icon" Nein
channelExtensions Die der Aktion zugeordneten kanalspezifischen Erweiterungseigenschaften JSONObject Nein

Feld

Ein Field-Element enthält die folgenden Eigenschaften:
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp String Nein
label Das Feldlabel String Ja
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Map<ChannelType, JSONObject> Nein
marginTop Der vertikale Abstand zwischen diesem Feld und dem vorherigen Feld in derselben Spalte. Zulässige Werte sind none, medium (Standard) und large. String Nein
labelFontSize Die für das Feldlabel verwendete Schriftgröße. Zulässige Werte sind small, medium (Standard) und large. String Nein
labelFontWeight Die Schriftstärke, die für das Feldlabel verwendet wird. Zulässige Werte sind light, medium (Standardwert) und fett. String Nein
displayInTable Ein boolescher FreeMarker-Ausdruck, mit dem Sie ein Feld bedingt in das Tabellenlayout in ein dataSet-Antwortelement aufnehmen können. String Nein (Standard ist true)
displayInForm Ein boolescher FreeMarker-Ausdruck, mit dem Sie ein Feld bedingt in ein Antwortelement editForm oder in das Formularlayout in einem dataSet-Antwortelement aufnehmen können String Nein (Standard ist true)

ReadOnly-Feld

Stellt ein schreibgeschütztes Feld dar. Alle schreibgeschützten Felder erben die Field-Eigenschaften und verfügen über die folgenden zusätzlichen Eigenschaften:
Name Beschreibung Typ Erforderlich?
value Der Feldwert Zeichenfolge Ja
width Der vorgeschlagene Prozentsatz der gesamten verfügbaren Breite, die das Feld in einem Tabellenlayout belegen soll. Zahl Nein
alignment Die Ausrichtung des Wertes in einer Tabellenspalte. Die Standardausrichtung ist right. "left", "center" und "right" Nein
Hinweis

In Release 23.06 von Oracle Digital Assistant werden schreibgeschützte Felder nicht in Eingabeformularen wiedergegeben, selbst wenn sie in der Nachrichten-Payload empfangen werden.
TextField
Das Element TextField erbt alle Eigenschaften des Feldes ReadOnly. Die displayType für dieses Element ist "text". Es verfügt über die folgenden zusätzlichen Eigenschaften:
Name Beschreibung Typ Erforderlich?
truncateAt Die Position, an der langwieriger Text abgeschnitten und Auslassungspunkte hinzugefügt werden, um anzugeben, dass der Wert abgeschnitten wurde. Eine Ganzzahl Nein
fontSize Die Schriftgröße, die für den Wert field verwendet wird. Zulässige Werte sind small, medium (Standard) und large. Zeichenfolge Nein
fontWeight Die Schriftstärke, die für den Wert field verwendet wird. Zulässige Werte sind hell, mittel (Standardwert) und fett. Zeichenfolge Nein
LinkField
Das Element LinkField erbt alle Eigenschaften des Feldes ReadOnly. Es verfügt über die folgenden zusätzlichen Eigenschaften:
Name Beschreibung Typ Erforderlich?
linkLabel Das Label, das für den Hyperlink verwendet wird Zeichenfolge Nein
imageUrl Die URL des Bildes, das einen Link öffnet, wenn Sie darauf klicken. Zeichenfolge Nein
MediaField
Das Element MediaField erbt alle Eigenschaften des Feldes ReadOnly. Es verfügt über die folgenden zusätzlichen Eigenschaften:
Name Beschreibung Typ Erforderlich?
mediaType Der Feldmedientyp ("video", "audio", "image") String Ja
ActionField
Das Element ActionField erbt alle Eigenschaften des Feldes ReadOnly. Es verfügt über die folgenden zusätzlichen Eigenschaften:
Name Beschreibung Typ Erforderlich?
action Die Aktion, die ausgeführt werden soll, wenn der Benutzer auf die Aktionsschaltfläche klickt. Maßnahme Ja

Formular

Stellt ein Array von Feldern zusammen mit einem Titel dar.
Name Beschreibung Typ Erforderlich?
title Der Titel, der über dem Formularlayout angezeigt wird Zeichenfolge Nein
fields Eine Liste schreibgeschützter Felder im Formular Liste<ReadOnlyField> Ja
formRows Eine Liste der im Formular angezeigten Zeilen. Liste<FormRow>  
actions Eine Liste mit Aktionen Liste<Aktion> Nein
selectAction Die Aktion, die ausgeführt wird, wenn das Formular ausgewählt wurde. Wenn Benutzer den Mauszeiger über das Formular bewegen, wird das Label der Aktion als QuickInfo (sofern vom Kanal unterstützt) angezeigt. Aktion Nein
channelExtensions Die der Nachricht zugeordneten kanalspezifischen Erweiterungseigenschaften JSONObject Nein

FormRow

Name Beschreibung Typ Erforderlich?
columns Eine Liste der Spalten, die in der Formularzeile angezeigt werden. <Spalte> auflisten Ja
selectAction Die Aktionen, die ausgeführt werden, wenn das Formular ausgewählt wurde. Wenn Benutzer den Mauszeiger über das Formular, das Label der Aktion, bewegen, wird es als QuickInfo angezeigt (wenn es vom Kanal unterstützt wird). Aktion Nein
separator Wenn Sie diese Eigenschaft auf "true" setzen, wird eine Trennlinie über dem Inhalt in der Formularzeile eingefügt. Boolean Nein
channelExtensions Die der Nachricht zugeordneten kanalspezifischen Erweiterungseigenschaften JSONObject Nein

Spalte

Name Beschreibung Typ Erforderlich?
fields Eine Liste von Feldern, die vertikal in der Spalte angezeigt werden. Diese Felder müssen ReadOnlyField-Instanzen sein, wenn die Spalte in einer FormRow innerhalb einer Form verwendet wird. Die Felder können sowohl schreibgeschützte als auch bearbeitbare Felder sein, wenn die FormRow in einer EditFormMessagePayload verwendet wird. Liste<Feld> Ja
verticalAlignment Die vertikale Ausrichtung der Spalte gegenüber den anderen Spalten in derselben Formularzeile. Zeichenfolge Nein
width Bestimmt die Breite der Spalte innerhalb der Formularzeile. Zulässige Werte sind auto (Standard) und stretch. Wenn diese Option auf stretch gesetzt ist, nimmt die Spalte die gesamte verbleibende Breite an, nachdem alle Spalten mit automatischer Breite gerendert wurden. Wenn mehrere Spalten auf stretch gesetzt sind, teilen sie die verbleibende Breite gleichmäßig auf. Zeichenfolge Nein
channelExtensions Die der Nachricht zugeordneten kanalspezifischen Erweiterungseigenschaften JSONObject Nein

Das editForm-Antwortelement

Dieses Antwortelement bildet die EditFormMessagePayload, die über einen Kanal an den Client weitergeleitet wird.
Name Beschreibung Typ Erforderlich?
type Der Typ des Antwortelements. editform Ja
title Der Formulartitel Zeichenfolge Nein
items Eine Liste mit Feldern, die schreibgeschützt und bearbeitbar sind. Liste<field> Ja
formColumns Die Anzahl der Spalten, die für das Formularlayout verwendet werden. Der Standardwert ist eine Spalte. Ganzzahl Nein
actions Eine Liste kartenbezogener Aktionen. Liste<Action> Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Feld textInput

Ein Feld zur Eingabe von Freitext. Sie können die Mindest- und Höchstzeichen für dieses Feld festlegen und die Formatierung mit regulären Ausdrücken erzwingen.

Dieses Snippet veranschaulicht das Erfassen von Benutzereingaben, indem die generierte Variable submittedFields (eine Map) referenziert wird.
      - displayType: textInput
        multiLine: true
        defaultValue: "${(submittedFields.value.Description)!''}"
        minLength: 10
        name: Description
        label: Description
        placeholder: What is the expense justification?
        clientErrorMessage: "Description must be 10 characters minimum, 50 characters maximum."
        maxLength: 50
        required: true
      - displayType: textInput
        multiLine: true
        defaultValue: "${(submittedFields.value.Notes)!''}"
        minLength: 10
        name: Notes
        inputStyle: email
        label: Notes
        placeholder: Expense notes (optional)
        maxLength: 50
        required: false
Dieses Snippet veranschaulicht das Erfassen der Benutzereingabe durch Referenzieren einer Mischentityvariablen.
Hinweis

Das referenzierte Mischentityelement kann ein STRING sein.
      - displayType: textInput
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Tip'])!''}"
        defaultValue: "${(expense.value.Tip.originalString)!''}"
        displayInForm: "${(((expense.value.TipIncluded.yesno)!'') == 'NO')?then(true, false)}"
        name: Tip
        label: Tip
        placeholder: Enter the tip
        clientErrorMessage: Tip is required
        required: true
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp. textInput (eine Zeichenfolge) Ja
name Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
label Das Feldlabel Zeichenfolge Nein
defaultValue Der Ausgangswert. Pro FreeMarker-Ausdruck in der Vorlage ist der Wert eine Zeichenfolge, wenn das referenzierte Mischentityelement (repräsentiert durch myText) keinen Wert ("${(submittedFields.value.myText)!''}") hat. Zeichenfolge Nein
validationRegularExpression Ein regulärer Ausdruck, der das Format für die Texteingabe angibt. Zeichenfolge Nein
multiline Wenn Sie diese Eigenschaft auf true setzen, können Benutzer mehrere Textzeilen eingeben. Boolean Nein
minlength Die Mindestanzahl von Zeichen, die zum Validieren des Feldes erforderlich sind. Benutzer erhalten eine Fehlermeldung, wenn sie zu wenige Zeichen eingeben. Ganzzahl Nein
maxLength Die Höchstanzahl oder Begrenzung der Zeichen. Ganzzahl Nein
inputStyle Das Format, das für den Client durchgesetzt wird. Folgende Formate werden verwendet:
  • text
  • email
  • url
  • tel
  • password
Das Standardformat ist Text, wenn diese Eigenschaft nicht definiert wurde.
Zeichenfolge Nein
placeholder Ein Hinweis, der beschreibt, wie dieses Feld verwendet wird. Dieser Text wird angezeigt, wenn Benutzer noch keine Eingabe eingegeben haben. Beispiel:
What is the expense justification? Enter between 10 and 50 characters.
Zeichenfolge Nein
autoSubmit Wenn der Wert auf true gesetzt ist, wird das Formular teilweise weitergeleitet, wenn der Benutzer einen Wert für das Feld eingegeben hat. In FormSubmissionMessagePayload wird partialSubmitField auf den Namen des Feldes gesetzt, in dem autoSubmit auf true gesetzt ist. Es wird empfohlen, die automatische Weiterleitung für bedingt abhängige Felder zu konfigurieren. Beispiel: Legen Sie diese Eigenschaft fest, wenn ein Feld basierend auf dem Wert eines anderen Feldes angezeigt oder ausgeblendet werden soll oder wenn die zulässigen Werte eines Feldes vom in einem anderen Feld festgelegten Wert abhängen. Durch die automatische Weiterleitung eines Felds, von dem andere Felder abhängen, kann das Formular sofort mit den relevanten Änderungen an den abhängigen Feldern aktualisiert werden. Zeichenfolge Nein
required Gibt an, ob die Formularweiterleitung Benutzereingaben in diesem Feld erfordert boolean Nein
clientErrorMessage Die Nachricht, die von einigen Clients (MS Teams, Apple Business Messaging) verwendet wird, wenn die clientseitige Validierung nicht erfolgreich verläuft. In Slack wird diese Eigenschaft nur verwendet, wenn das bearbeitbare Formular auf der Konversationsseite angezeigt wird. Es wird nicht in einem modalen Dialog angezeigt. Zeichenfolge Nein
serverErrorMessage Eine Fehlermeldung, die an den Client gesendet wird, wenn die serverseitige Validierung eines Formularfeldwerts nicht erfolgreich ist. Wenn serverseitige Fehler dieser Art auftreten, wird empfohlen, dass die aktuelle Formularnachricht ersetzt wird und nicht eine neue Nachricht, die der Unterhaltung hinzugefügt wird, indem die Eigenschaft channelExtensions so konfiguriert wird, dass die letzte Formularnachricht ersetzt werden soll. Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Feld datePicker

Ein Feld mit einem Dropdown-Kalender, in dem Benutzer einen Tag, einen Monat und ein Jahr auswählen können. Die Eigenschaften maxDate und minDate der Komponente validieren die Benutzereingabe.
Hinweis

Diese Mindest- und Höchstwertvalidierung wird vom Slack-Kanal nicht unterstützt.
Dieses Code-Snippet veranschaulicht, wie die Benutzereingabe mit der generierten Variablen submittedFields (eine Karte) erfasst wird.
 - displayType: datePicker
        defaultValue: "${(submittedFields.value.Date)!''}"
        name: Date
        maxDate: "${.now?iso_utc[0..9]}"
        label: Expense Date
        placeholder: Pick a date in the past
        clientErrorMessage: Expense date is required and must be in the past.
        required: true
Dieses Snippet veranschaulicht, wie Benutzereingaben durch Referenzieren einer Mischentityvariablen erfasst werden.
     - displayType: datePicker
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Date'])!''}"
        defaultValue: "${(expense.value.Date.date?number_to_date?iso_utc)!''}"
        name: Date
        maxDate: "${.now?iso_utc[0..9]}"
        label: Expense Date
        placeholder: Pick a date in the past
        clientErrorMessage: Expense date is required and must be in the past.
        required: true
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp datePicker (eine Zeichenfolge) Ja
id Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
label Ein beschreibendes Label. Zeichenfolge Nein
defaultValue Der Standardwert für das Feld im Format JJJJ-MM-TT. Die Vorlage definiert diese Zeichenfolge als einen Apache FreeMarker-Ausdruck, der eine leere Zeichenfolge zurückgibt, wenn das referenzierte Mischentityelement (repräsentiert durch myDate) einen Nullwert aufweist.
"${(submittedFields1.value.myDate)!''}"
Zeichenfolge Nein
minDate Das erste Datum im Bereich zulässiger Tage. Der Slack-Kanal unterstützt diese clientseitige Validierung nicht. Zeichenfolge Nein
maxDate Das letzte Datum im Bereich zulässiger Tage. Die Vorlage definiert diese Zeichenfolge als den aktuellen Tag ("${.now?iso_utc[0..9]}"). Der Slack-Kanal unterstützt diese clientseitige Validierung nicht. Zeichenfolge Nein
placeholder Eine Beschreibung der erwarteten Eingabe, die angezeigt wird, wenn der Benutzer noch kein Datum ausgewählt hat. Zeichenfolge Nein
autoSubmit Wenn der Wert auf true gesetzt ist, wird das Formular teilweise weitergeleitet, wenn der Benutzer einen Wert für das Feld eingegeben hat. In FormSubmissionMessagePayload wird partialSubmitField auf den Namen des Feldes gesetzt, in dem autoSubmit auf true gesetzt ist. Es wird empfohlen, die automatische Weiterleitung für bedingt abhängige Felder zu konfigurieren. Beispiel: Legen Sie diese Eigenschaft fest, wenn ein Feld basierend auf dem Wert eines anderen Feldes angezeigt oder ausgeblendet werden soll oder wenn die zulässigen Werte eines Feldes vom in einem anderen Feld festgelegten Wert abhängen. Durch die automatische Weiterleitung eines Felds, von dem andere Felder abhängen, kann das Formular sofort mit den relevanten Änderungen an den abhängigen Feldern aktualisiert werden. Zeichenfolge Nein
required Gibt an, ob die Formularweiterleitung Benutzereingaben in diesem Feld erfordert boolean Nein
clientErrorMessage Die Nachricht, die von einigen Clients (MS Teams, Apple Business Messaging) verwendet wird, wenn die clientseitige Validierung nicht erfolgreich verläuft. In Slack wird diese Eigenschaft nur verwendet, wenn das bearbeitbare Formular auf der Konversationsseite angezeigt wird. Es wird nicht in einem modalen Dialog angezeigt. Zeichenfolge Nein
serverErrorMessage Eine Fehlermeldung, die an den Client gesendet wird, wenn die serverseitige Validierung eines Formularfeldwerts nicht erfolgreich ist. Wenn serverseitige Fehler dieser Art auftreten, wird empfohlen, dass die aktuelle Formularnachricht ersetzt wird und nicht eine neue Nachricht, die der Unterhaltung hinzugefügt wird, indem die Eigenschaft channelExtensions so konfiguriert wird, dass die letzte Formularnachricht ersetzt werden soll. Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Feld timePicker

Ermöglicht es dem Benutzer, einen Zeitwert innerhalb eines angegebenen Bereichs einzugeben. Die Eigenschaften maxTime und minTime der Komponente validieren die Benutzereingabe.
Hinweis

Der Slack-Kanal unterstützt keine Mindest- und Höchstwertvalidierung.
Das Zeitauswahlfeld liest und schreibt den Wert im 24-Stunden-Format. Das Anzeigeformat im Clientkanal kann ein 12-Stunden-Format mit einer AM/PM-Anzeige verwenden, sollte jedoch immer eine 24-Stunden-formatierte Zeit zurückschreiben.
Das folgende Snippet veranschaulicht, wie die Benutzereingabe mit der generierten Variablen submittedFields (eine Karte) erfasst wird.
      - displayType: timePicker
        defaultValue: "${(submittedFields.value.Time.value?time.xs?string['hh:mm a'])!''}"
        maxTime: "23:00"
        minTime: "13:00"
        name: Time
        label: Expense Time
        placeholder: What time was the expense?
        clientErrorMessage: This time is outside the limits.
        required: true
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp timePicker (eine Zeichenfolge) Ja
id Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
label Ein Label, das die Zeitauswahlparameter beschreibt. Zeichenfolge Ja
defaultValue Der Anfangswert für dieses Feld im 24-Stunden-Format. Die Vorlage definiert diese Zeichenfolge als einen Apache FreeMarker-Ausdruck, der eine leere Zeichenfolge zurückgibt, wenn das referenzierte Mischentityelement (repräsentiert durch myTime) einen Nullwert aufweist.
"${(submittedFields.value.myTime)!''}"
Zeichenfolge Nein
minTime Definiert die früheste zulässige Zeit, die als HH:MM im 24-Stunden-Format eingegeben wurde. Beispiel, 00:00 Zeichenfolge Nein
maxTime Definiert die letzte zulässige Zeit, die als HH:MM im 24-Stunden-Format eingegeben wurde. Beispiel: 13:00. Zeichenfolge Nein
placeholder Ein Hinweis für die Eingabe. Pro Vorlage lautet das Beispiel placeholder Pick a time in the morning, das die Beispielwerte minTime und maxTime der Vorlage 00:00 und 12:00 widerspiegelt. Zeichenfolge Nein
autoSubmit Wenn der Wert auf true gesetzt ist, wird das Formular teilweise weitergeleitet, wenn der Benutzer einen Wert für das Feld eingegeben hat. In FormSubmissionMessagePayload wird partialSubmitField auf den Namen des Feldes gesetzt, in dem autoSubmit auf true gesetzt ist. Es wird empfohlen, die automatische Weiterleitung für bedingt abhängige Felder zu konfigurieren. Beispiel: Legen Sie diese Eigenschaft fest, wenn ein Feld basierend auf dem Wert eines anderen Feldes angezeigt oder ausgeblendet werden soll oder wenn die zulässigen Werte eines Feldes vom in einem anderen Feld festgelegten Wert abhängen. Durch die automatische Weiterleitung eines Felds, von dem andere Felder abhängen, kann das Formular sofort mit den relevanten Änderungen an den abhängigen Feldern aktualisiert werden. Zeichenfolge Nein
required Gibt an, ob die Formularweiterleitung Benutzereingaben in diesem Feld erfordert boolean Nein
clientErrorMessage Die Nachricht, die von einigen Clients (MS Teams, Apple Business Messaging) verwendet wird, wenn die clientseitige Validierung nicht erfolgreich verläuft. Beispiel: Time must be in the morning. In Slack wird diese Eigenschaft nur verwendet, wenn das bearbeitbare Formular auf der Konversationsseite angezeigt wird. Es wird nicht in einem modalen Dialog angezeigt. Zeichenfolge Nein
serverErrorMessage Eine Fehlermeldung, die an den Client gesendet wird, wenn die serverseitige Validierung eines Formularfeldwerts nicht erfolgreich ist. Wenn serverseitige Fehler dieser Art auftreten, wird empfohlen, dass die aktuelle Formularnachricht ersetzt wird und nicht eine neue Nachricht, die der Unterhaltung hinzugefügt wird, indem die Eigenschaft channelExtensions so konfiguriert wird, dass die letzte Formularnachricht ersetzt werden soll. Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Feld numberInput

Erfasst die in einem angegebenen Bereich eingegebene Zahl.
      - displayType: numberInput
        minValue: 5
        serverErrorMessage: "${(amountError.value)!''}"
        maxValue: 500
        defaultValue: "${(submittedFields.value.Amount)!''}"
        name: Amount
        label: Amount
        placeholder: Enter the expense amount (do not include currency symbol)
        clientErrorMessage: Amount is required and must be between 5 and 500 characters
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp numberInput (eine Zeichenfolge) Ja
name Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
label Ein beschreibendes Label für den vom Benutzer erforderlichen Datumswert. Zeichenfolge Nein
defaultValue Der Ausgangswert. Die Vorlage definiert diese Zeichenfolge als einen Apache FreeMarker-Ausdruck, der eine leere Zeichenfolge zurückgibt, wenn das referenzierte Mischentityelement (repräsentiert durch myNumber) einen Nullwert aufweist. "${(submittedFields.value.myNumber)!''}" Zeichenfolge Nein
maxvalue Die maximal zulässige Anzahl. Der Slack-Kanal unterstützt keine Mindest- oder Höchstwertvalidierung. Ganzzahl Nein
minvalue Kleinste zulässige Anzahl Ganzzahl Nein
placeholder Ein Hinweis, der die Verwendung des Feldes beschreibt. Dieser Text wird angezeigt, wenn der Benutzer noch keine Zahl eingegeben hat. Zeichenfolge Nein
autoSubmit Wenn der Wert auf true gesetzt ist, wird das Formular teilweise weitergeleitet, wenn der Benutzer einen Wert für das Feld eingegeben hat. In FormSubmissionMessagePayload wird partialSubmitField auf den Namen des Feldes gesetzt, in dem autoSubmit auf true gesetzt ist. Es wird empfohlen, die automatische Weiterleitung für bedingt abhängige Felder zu konfigurieren. Beispiel: Legen Sie diese Eigenschaft fest, wenn ein Feld basierend auf dem Wert eines anderen Feldes angezeigt oder ausgeblendet werden soll oder wenn die zulässigen Werte eines Feldes vom in einem anderen Feld festgelegten Wert abhängen. Durch die automatische Weiterleitung eines Felds, von dem andere Felder abhängen, kann das Formular sofort mit den relevanten Änderungen an den abhängigen Feldern aktualisiert werden. Zeichenfolge Nein
required Gibt an, ob die Formularweiterleitung Benutzereingaben in diesem Feld erfordert boolean Nein
clientErrorMessage Die Nachricht, die von einigen Clients (MS Teams, Apple Business Messaging) verwendet wird, wenn die clientseitige Validierung nicht erfolgreich verläuft. In Slack wird diese Eigenschaft nur verwendet, wenn das bearbeitbare Formular auf der Konversationsseite angezeigt wird. Es wird nicht in einem modalen Dialog angezeigt. Zeichenfolge Nein
serverErrorMessage Eine Fehlermeldung, die an den Client gesendet wird, wenn die serverseitige Validierung eines Formularfeldwerts nicht erfolgreich ist. Wenn serverseitige Fehler dieser Art auftreten, wird empfohlen, dass die aktuelle Formularnachricht ersetzt wird und nicht eine neue Nachricht, die der Unterhaltung hinzugefügt wird, indem die Eigenschaft channelExtensions so konfiguriert wird, dass die letzte Formularnachricht ersetzt werden soll. Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Feld singleSelect

Ermöglicht es Benutzern, einen einzelnen Wert aus einer vordefinierten Liste auszuwählen. Sie können dieses Steuerelement als Liste formatieren, die Benutzer abfragen und auswählen können, oder als Gruppe von Optionsfeldern. Dieses Element verfügt über kanalspezifisches Rendering:
  • Im Microsoft Teams-Kanal wird dieses Element immer als Liste wiedergegeben (auch wenn layoutStyle auf radioGroup gesetzt ist), da adaptive Karten keine Optionsfelder unterstützen.
  • Im Slack-Kanal wird dieses Element als Liste anstelle einer Optionsgruppe gerendert, wenn mehr als zehn Optionen vorhanden sind.
Das folgende Snippet veranschaulicht das Auffüllen der Liste mit der generierten Variablen submittedFields (eine Zuordnungsvariable)
 - displayType: singleSelect
        defaultValue: "${(submittedFields.value.Type)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Expense Type
        placeholder: Select expense type
        clientErrorMessage: Expense type is required
        required: true

Tipp:

Obwohl clientErrorMessage ein optionales Attribut ist, wird empfohlen, es für Skills zu definieren, die im Microsoft Teams-Kanal ausgeführt werden, da Adaptive Cards keine Meldung generieren, wenn die clientseitige Validierung nicht erfolgreich verläuft.
Dieses Snippet veranschaulicht, wie die Liste durch Referenzieren einer Mischentity aufgefüllt wird:
     - autoSubmit: true
        displayType: singleSelect
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Type'])!''}"
        defaultValue: "${(expense.value.Type.value)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Expense Type
        placeholder: Select expense type
        clientErrorMessage: Expense type is required
        required: true
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp singleSelect (eine Zeichenfolge) Ja
name Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
label Der Feldlabeltext, der den Inhalt der Einfachauswahlliste beschreibt. Zeichenfolge Ja
defaultValue Die Standardauswahl. Die Vorlage definiert diesen Zeichenfolgenwert als einen Apache FreeMarker-Ausdruck, der eine leere Zeichenfolge zurückgibt, wenn das referenzierte Mischentityelement (dargestellt durch mySingleSelect)) einen Nullwert aufweist. "${(submittedFields.value.mySingleSelect)!''}" Zeichenfolge Nein
options Ein Array der verfügbaren Optionen. Die Vorlage definiert diese Optionen statisch mit einzelnen label- und value-Paaren mit Zeichenfolgenwerten. Sie können die Auswahloptionen jedoch mit den Eigenschaften iteratorVariable und iteratorExpression dynamisch auffüllen:
        defaultValue: "${(submittedFields.value.Type)!''}"
        name: Type
        options:
          - iteratorVariable: option
            iteratorExpression: "${expenseType.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
In diesem Snippet werden die von den Eigenschaften type und enum zurückgegebenen Spesentypwerte mit dem integrierten split in der Liste sequenziert.
Liste<Option> Ja
layoutStyle Wie die Einzelauswahloptionen in der Form dargestellt werden. Sie können als Liste (layoutStyle: list) oder als Optionsfelder (layoutStyle: radioGroup) gruppiert werden. Zeichenfolge  
placeholder Ein Hinweis, der die Verwendung des Feldes beschreibt. Wird angezeigt, wenn der Benutzer die Auswahl noch nicht getroffen hat. Beispiel:
label: 
        placeholder: Select an expense type. You can pick only one.
Dieser Platzhalter wird nur für das Rendering des Listenlayouts angezeigt.
Zeichenfolge Nein
autoSubmit Wenn der Wert auf true gesetzt ist, wird das Formular teilweise weitergeleitet, wenn der Benutzer einen Wert für das Feld eingegeben hat. In FormSubmissionMessagePayload wird partialSubmitField auf den Namen des Feldes gesetzt, in dem autoSubmit auf true gesetzt ist. Es wird empfohlen, die automatische Weiterleitung für bedingt abhängige Felder zu konfigurieren. Beispiel: Legen Sie diese Eigenschaft fest, wenn ein Feld basierend auf dem Wert eines anderen Feldes angezeigt oder ausgeblendet werden soll oder wenn die zulässigen Werte eines Feldes vom in einem anderen Feld festgelegten Wert abhängen. Durch die automatische Weiterleitung eines Felds, von dem andere Felder abhängen, kann das Formular sofort mit den relevanten Änderungen an den abhängigen Feldern aktualisiert werden. Zeichenfolge Nein
required Gibt an, ob die Formularweiterleitung Benutzereingaben in diesem Feld erfordert boolean Nein
clientErrorMessage Die Nachricht, die von einigen Clients (MS Teams, Apple Business Messaging) verwendet wird, wenn die clientseitige Validierung nicht erfolgreich verläuft. In Slack wird diese Eigenschaft nur verwendet, wenn das bearbeitbare Formular auf der Konversationsseite angezeigt wird. Es wird nicht in einem modalen Dialog angezeigt. Zeichenfolge Nein
serverErrorMessage Eine Fehlermeldung, die an den Client gesendet wird, wenn die serverseitige Validierung eines Formularfeldwerts nicht erfolgreich ist. Wenn serverseitige Fehler dieser Art auftreten, wird empfohlen, dass die aktuelle Formularnachricht ersetzt wird und nicht eine neue Nachricht, die der Unterhaltung hinzugefügt wird, indem die Eigenschaft channelExtensions so konfiguriert wird, dass die letzte Formularnachricht ersetzt werden soll. Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Feld multiSelect

Ermöglicht es Benutzern, einen oder mehrere Werte aus einer vordefinierten Liste auszuwählen. Sie können dies als Auswahlliste verwenden, die Benutzer abfragen können, oder als eine Gruppe von Kontrollkästchen. Dieses Element verfügt über kanalspezifisches Rendering:
  • Im Microsoft Teams-Kanal wird dieses Element immer als Liste wiedergegeben (auch wenn layoutStyle auf checkboxes gesetzt ist), da adaptive Karten keine Kontrollkästchen mit Mehrfachauswahl unterstützen.
  • Im Slack-Kanal wird dieses Element als Liste anstelle einer Gruppe von Kontrollkästchen mit Mehrfachauswahl gerendert, wenn mehr als zehn Optionen vorhanden sind.
Dieses Snippet veranschaulicht, wie die Liste aufgefüllt wird, indem die generierte Variable submittedFields (eine Map) referenziert wird.
 - displayType: multiSelect
        defaultValue: "${(submittedFields.value.Attendees?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Attendees
        placeholder: Select one or more attendees

Dieses Snippet veranschaulicht die Referenzierung einer Mischentity zum Auffüllen der Liste.
     - displayType: multiSelect
        serverErrorMessage: "${(system.entityToResolve.value.validationErrors['Attendees'])!''}"
        displayInForm: "${(((expense.value.Type.value)!'') == 'Meal')?then(true, false)}"
        defaultValue: "${(expense.value.Attendees?map(a -> a.value)?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
        layoutStyle: list
        label: Attendees
        placeholder: Select attendees
        clientErrorMessage: Attendees are required when expense type is a Meal
        required: true
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp multiselect (eine Zeichenfolge) Ja
name Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
label Das Feldlabel, das den Inhalt für die Liste multiSelect beschreibt. Zeichenfolge Ja
defaultValue Die Standardauswahl. Die Vorlage definiert diese Zeichenfolge als einen Apache FreeMarker-Ausdruck, der eine leere Zeichenfolge zurückgibt, wenn das referenzierte Mischentityelement (repräsentiert durch myMultiSelect) einen Nullwert aufweist.
"${(submittedFields.value.myMultiSelect?join(','))!''}"
List<String> Nein
options Ein Array der verfügbaren Optionen. Die Vorlage definiert diese Optionen statisch mit einzelnen label- und value-Paaren mit Zeichenfolgenwerten. Sie können die Auswahloptionen jedoch mit den Eigenschaften iteratorVariable und iteratorExpression dynamisch auffüllen:
        defaultValue: "${(submittedFields.value.Attendees?join(','))!''}"
        name: Attendees
        options:
          - iteratorVariable: option
            iteratorExpression: "${attendee.type.enumValues?split(',')}"
            label: "${option}"
            value: "${option}"
List<option> Ja
placeholder Ein Hinweis, der die Verwendung des Feldes beschreibt. Wird angezeigt, wenn der Benutzer keine Auswahl getroffen hat.
label: Attendees
        placeholder: Select one or more attendees
Dieser Platzhalter wird nur für das Listenlayout angezeigt. Sie ist für Kontrollkästchenlayouts nicht verfügbar.
Zeichenfolge Nein
layoutStyle Das Layout für die Optionen multiSelect. Die Optionen lauten list und checkboxes. Zeichenfolge Nein
autoSubmit Wenn der Wert auf true gesetzt ist, wird das Formular teilweise weitergeleitet, wenn der Benutzer einen Wert für das Feld eingegeben hat. In FormSubmissionMessagePayload wird partialSubmitField auf den Namen des Feldes gesetzt, in dem autoSubmit auf true gesetzt ist. Es wird empfohlen, die automatische Weiterleitung für bedingt abhängige Felder zu konfigurieren. Beispiel: Legen Sie diese Eigenschaft fest, wenn ein Feld basierend auf dem Wert eines anderen Feldes angezeigt oder ausgeblendet werden soll oder wenn die zulässigen Werte eines Feldes vom in einem anderen Feld festgelegten Wert abhängen. Durch die automatische Weiterleitung eines Felds, von dem andere Felder abhängen, kann das Formular sofort mit den relevanten Änderungen an den abhängigen Feldern aktualisiert werden. Zeichenfolge Nein
required Gibt an, ob die Formularweiterleitung Benutzereingaben in diesem Feld erfordert boolean Nein
clientErrorMessage Die Nachricht, die von einigen Clients (MS Teams, Apple Business Messaging) verwendet wird, wenn die clientseitige Validierung nicht erfolgreich verläuft. In Slack wird diese Eigenschaft nur verwendet, wenn das bearbeitbare Formular auf der Konversationsseite angezeigt wird. Es wird nicht in einem modalen Dialog angezeigt. Zeichenfolge Nein
serverErrorMessage Eine Fehlermeldung, die an den Client gesendet wird, wenn die serverseitige Validierung eines Formularfeldwerts nicht erfolgreich ist. Wenn serverseitige Fehler dieser Art auftreten, wird empfohlen, dass die aktuelle Formularnachricht ersetzt wird und nicht eine neue Nachricht, die der Unterhaltung hinzugefügt wird, indem die Eigenschaft channelExtensions so konfiguriert wird, dass die letzte Formularnachricht ersetzt werden soll. Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Umschaltfeld

Zeigt einen Switch für zwei Optionen an. Im Slack-Kanal wird dieses Steuerelement als Kontrollkästchen wiedergegeben.
Hinweis

Im Slack-Kanal wird dieses Element als Optionsfeldpaar gerendert.
Dieses Snippet veranschaulicht die Erfassung der Benutzereingabe, indem die generierte Variable submittedForms (eine Map) referenziert wird.
      - displayType: toggle
        defaultValue: "false"
        name: TipIncluded
        labelOn: Tip
        label: Tip Included?
        valueOff: "false"
        labelOff: No Tip
        valueOn: "true"
Dieses Snippet veranschaulicht das Erfassen von Benutzereingaben durch Referenzieren einer Mischentityvariablen.
      - autoSubmit: true
        displayType: toggle
        defaultValue: "${(expense.value.TipIncluded.yesno)!'YES'}"
        name: TipIncluded
        labelOn: "Yes"
        label: Tip Included?
        valueOff: "NO"
        labelOff: "No"
        required: false
        valueOn: "YES"
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp toggle (eine Zeichenfolge) Ja
id Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
label Ein Label, das beschreibt, was geschieht, wenn der Umschalter eingeschaltet ist. Zeichenfolge Ja
defaultValue Der Ausgangswert. Wenn der Umschalter anfänglich aktiviert sein soll, setzen Sie diesen auf den Wert valueOn. Die Vorlage definiert diese Zeichenfolge als einen Apache FreeMarker-Ausdruck, der den Umschalter aktiviert, wenn das referenzierte Mischentityelement (repräsentiert durch myToggle) einen Nullwert aufweist.
"${(submittedFields.value.myToggle)!'true'}"
Zeichenfolge Ja
valueOff Der Wert, wenn der Umschalter ausgeschaltet ist. Der Standardwert für die Vorlage ist false (valueOff: "false" ). Zeichenfolge Ja
valueOn Der Wert, wenn der Umschalter eingeschaltet ist. Der Standardwert in der Vorlage ist true (value On: "true" ) Zeichenfolge Ja
labelOn Eine Beschriftung für den Schalter an der Position Zeichenfolge Nein
labelOff Ein Label für die Position "Aus". Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Textfeld

Ein Feldelement enthält die folgenden Eigenschaften:
Name Beschreibung Typ Erforderlich?
displayType Der Elementtyp. text (eine Zeichenfolge) Ja
name Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
value Der Rohwert für das Feld Zeichenfolge Ja
width Der Prozentsatz der gesamten verfügbaren Breite, die das Element in einem Tabellenlayout belegen soll. Die verbleibende Breite, beginnend bei 100 minus den Elementen mit einer angegebenen Breite, wird gleichmäßig auf die Elemente aufgeteilt, ohne dass eine Breite angegeben wurde. Ganzzahl Nein
alignment Die Ausrichtung des Wertes an einer Tabellenspalte. left, center und right. Der Standardwert ist right. Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

Das Linkfeld

Ein Feldelement enthält die folgenden Eigenschaften:
Name Beschreibung Typ Erforderlich?
displayType Der Feldtyp link (eine Zeichenfolge) Ja
name Ein eindeutiger Name für das Feld im Eingabeformular. Dieser Name wird zur Laufzeit als ID verwendet. Zeichenfolge Ja
value Die URL-Adresse. Beispiel: http:www.oracle.com Zeichenfolge Ja
width Der Prozentsatz der gesamten verfügbaren Breite, die das Element in einem Tabellenlayout belegen soll. Die verbleibende Breite, beginnend bei 100 minus den Elementen mit einer angegebenen Breite, wird gleichmäßig auf die Elemente aufgeteilt, ohne dass eine Breite angegeben wurde. Ganzzahl Nein
alignment Die Ausrichtung des Wertes an einer Tabellenspalte. Zulässige Werte sind left, center und right. Der Standardwert ist right. Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein

EditFormMessagePayload

Diese Payload definiert das bearbeitbare Formular, das an die Kanäle gesendet wird.
Name Beschreibung Typ Erforderlich?
type Der Nachrichten-Payload-Typ. editForm (eine Zeichenfolge) Ja
headerText Der Headertext, der über dem Formular angezeigt wird. Zeichenfolge Nein
footerText Der Text, der unter dem Formular und den Aktionen angezeigt wird, jedoch über den globalen Aktionen. Zeichenfolge Nein
title Der Formulartitel Zeichenfolge Nein
formRows Eine Liste der im Formular angezeigten Zeilen. Liste<FormRow> Nein
fields Eine Liste mit Feldern, die schreibgeschützt und bearbeitbar sind. Liste<field> Ja
formColumns Die Anzahl der Spalten, die für das Formularlayout verwendet werden. Der Standardwert ist eine Spalte. Ganzzahl Nein
actions Eine Liste mit Aktionen. Liste<Action> Nein
globalActions Eine Liste der globalen Aktionen. Das Rendering dieser Aktionen ist kanalspezifisch. Aktionen auf Facebook werden beispielsweise von reply_actions gerendert. Liste<Action> Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein
Feld automatisch weiterleiten
Wenn für ein Feld die Eigenschaft autoSubmit auf true gesetzt ist, sendet der Client eine FormSubmissionMessagePayload mit der Zuordnung submittedField, die entweder die gültigen Feldwerte enthält, die bisher eingegeben wurden, oder nur den Wert des automatisch weitergeleiteten Feldes (die Implementierung ist kanalspezifisch). Felder, die noch nicht festgelegt sind (unabhängig davon, ob sie erforderlich sind) oder Felder, die eine clientseitige Validierung verletzen, werden nicht in die submittedField-Map aufgenommen. Wenn das automatisch weitergeleitete Feld selbst einen ungültigen Wert enthält, wird FormSubmissionMessagePayload nicht gesendet, und stattdessen wird die Clientfehlermeldung angezeigt.
Hinweis

Microsoft Teams unterstützt keine automatische Weiterleitung.

SubmitFormAction

Name Beschreibung Typ Erforderlich?
type Aktionstyp submitForm (eine Zeichenfolge) Ja
postback Die Postback Payload, die eine Aktionseigenschaft zum Auslösen der Navigation enthalten kann. Es wird empfohlen, dass der Wert für diese Eigenschaft aus dem Postback-Objekt FormSubmissionMessagePayload übernommen wird. JSONObject Nein
variable Der Name der Variable, in der die weitergeleiteten Werte gespeichert werden. Diese Werte befinden sich in FormSubmissionMessagePayload. Zeichenfolge Nein
processingMethod Die Verarbeitungsanweisungen, die von der Komponente "Entitäten auflösen" für die weitergeleiteten Feldwerte verwendet werden. Sie können dies auf FormSubmissionMessagePayload setzen, aber auch Folgendes festlegen:
  • mapVariable
  • separateVariables
  • compositeBag
.
Zeichenfolge Ja
label Das Label für die Anzeigeaktion. Zeichenfolge Ja - Sie müssen mindestens einen label-Wert oder imageUrl-Wert angeben.
imageUrl Das Bild für die Anzeigeaktion. Zeichenfolge Sie müssen mindestens einen label- oder imageUrl-Wert angeben.
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften. Sie können beispielsweise die maximale Höhe für Facebook Messenger festlegen. Karte<ChannelType, JSONObject> Nein
FormSubmissionMessagePayload
Diese Payload wird von den Kanälen an die ODA-Pipeline zurückgegeben, wenn der Benutzer ein Formular weitergeleitet hat, indem er auf die Schaltfläche SubmitFormAction klickt. Es enthält die folgenden Eigenschaften:
Name Beschreibung Typ Erforderlich?
type Der Typ der Payload. "formSubmission" (ein Zeichenfolgenwert) Ja
submittedFields Schlüssel/Wert-Paare der weitergeleiteten Feldwerte. Der Schlüssel ist der Name (ID) des Feldes. Map<String, Object> Ja
postback Die Postback Payload, die möglicherweise eine Aktionseigenschaft zum Auslösen der Navigation enthält. Wir empfehlen, den Wert aus der SubmitFormAction zu übernehmen JSONObject Nein
partialSubmitField Der Name des Feldes, das eine teilweise Formularweiterleitung auslöst. Felder mit aktivierter automatischer Weiterleitung (autoSubmit: true) können eine teilweise Formularweiterleitung auslösen. Zeichenfolge Nein

Eingabeformular aktualisieren

Wenn der Endbenutzer das Formular weiterleitet, entweder weil für ein Feld autosubmit auf true gesetzt ist oder weil der Benutzer auf die Aktionsschaltfläche submitForm getippt hat, kann es zu Situationen kommen, in denen der Benutzer nicht alle erforderlichen Informationen angegeben hat oder einige Feldwerte einen ungültigen Wert enthalten. In diesem Fall sendet die Dialog-Engine eine neue EditFormMessagePayload. Diese Meldung sollte jedoch die vorherige Formularnachricht ersetzen. Um den Clientkanal anzuweisen, die vorherige Formularnachricht zu ersetzen, konfigurieren Sie die Kanalerweiterungseigenschaft replaceMessage wie folgt, anstatt der Unterhaltung eine neue Formularnachricht hinzuzufügen:
- channel: ${system.channelType}
  properties:
    replaceMessage: "${system.message.messagePayload.type == 'formSubmission'}"
Zur Laufzeit wird diese Eigenschaft dem channelExtensions-Element auf Root-Ebene der allgemeinen Antwortkomponenten-Payload hinzugefügt:
...,
"channelExtensions": { "replaceMessage": "true"}

TableMessagePayload

Zeigt die Daten in einem Tabellen- und Formformat an.
Name Beschreibung Typ Erforderlich?
type Der Nachrichten-Payload-Typ "table" Ja
headings Eine Liste der Überschriften von Tabellenspalten Liste<TableHeading> Ja
rows Eine Liste der Tabellenzeilen Liste<Zeile> Ja
forms Eine Liste der Formulare Liste Ja
formColumns Die Anzahl der im Formularlayout verwendeten Spalten. Der Standard lautet 1. Ganzzahl Ja
paginationInfo Paginierungsinformationen, mit denen Schaltflächen für vorherige oder nächste Sets wiedergegeben werden können PaginationInfo Ja

Zeile

Name Beschreibung Typ Erforderlich?
fields Eine Liste mit schreibgeschützten Feldern <ReadOnly-Feld> auflisten Ja
selectAction Die Aktionen, die ausgeführt werden, wenn das Formular ausgewählt wurde. Wenn Benutzer den Mauszeiger über das Formular, das Label der Aktion, bewegen, wird es als QuickInfo angezeigt (wenn es vom Kanal unterstützt wird). Aktion Nein
channelExtensions Die der Nachricht zugeordneten kanalspezifischen Erweiterungseigenschaften Karte<ChannelType>,JSONObject Nein

TableHeading

Eine Tabellenüberschrift enthält die folgenden Eigenschaften:
Name Beschreibung Typ Erforderlich?
label Das Titellabel Zeichenfolge Ja
width Breite der Überschrift Zeichenfolge Nein
alignment Die Ausrichtung des Spaltenwerts (left, right oder center). Der Standardwert ist right. Zeichenfolge Nein
channelExtensions Eine Gruppe kanalspezifischer Erweiterungseigenschaften.
Map<ChannelType>, JSONObject>
Nein

PaginationInfo

Stellt die Paging-Informationen für die Ergebnisse in den Objekten Table, Form und Table-Form dar.

Name Beschreibung Typ Erforderlich?
totalCount Die Gesamtanzahl der Ergebnisse Nummer Ja
rangeSize Die Bereichsgröße der Ergebnisse pro Seite Nummer Ja
status Paging-Statusmeldung Zeichenfolge Ja
currentRangeSize Die Größe des aktuellen Ergebnisbereichs Zahl Ja
rangeStart Der Startversatz des aktuellen Ergebnisbereichs Zahl Ja
nextRangeSize Die Größe des nächsten Ergebnisbereichs Zahl Ja
hasPrevious Gibt an, ob eine vorherige Ergebnismenge vorhanden ist boolean Ja
hasNext Gibt an, ob eine nächste Gruppe von Ergebnissen vorhanden ist boolean Ja

tableFormMessageLayout

Zeigt die Daten in einem Tabellen- und Formformat an.
Name Beschreibung Typ Erforderlich?
type Der Nachrichten-Payload-Typ "tableForm" Ja
headings Eine Liste der Überschriften von Tabellenspalten Liste<TableHeading> Ja
rows Eine Liste der Tabellenzeilen Liste<Zeile> Ja
forms Eine Liste der Formulare Liste Ja
formColumns Die Anzahl der im Formularlayout verwendeten Spalten. Der Standard lautet 1. Ganzzahl Ja
showFormButtonLabel Das Label der Schaltfläche, mit der das Formularlayout für eine bestimmte Zeile angezeigt wird. Zeichenfolge Ja
paginationInfo Paginierungsinformationen, mit denen Schaltflächen für vorherige oder nächste Sets wiedergegeben werden können PaginationInfo Ja

Das dataSet-Antwortelement

Mit dem Antwortelement dataSet können Sie Tabellen und Formulare erstellen. Er enthält die folgenden Eigenschaften:

Eigenschaft Beschreibung Erforderlich?
layout Der Layoutstil, mit dem die dataSet gerendert wird. Zulässige Werte sind table, form und tableForm. Ja
formColumns Die Anzahl der Spalten, die zum Rendern von Elementen in einem Formularlayout verwendet werden. Gilt nur, wenn das Layout form oder tableForm lautet. Standardwert: 1. Nein
showFormButtonLabel Das Label, mit dem das Formulardialogfeld in einem tableForm-Layoutstil geöffnet wird. Dies wird derzeit nur auf Slack-Kanälen verwendet. Die anderen Kanäle unterstützen die Erweiterung der Tabellenzeile, um die zusätzlichen Elemente in einem Formularlayout anzuzeigen Nein
data Wird zum Definieren eines Dateneintrags in der Datei dataSet verwendet. Siehe Dateneigenschaften von DataSet Ja

DataSet-Dateneigenschaften

Die Eigenschaft data des Antwortelements dataSet enthält die folgenden Untereigenschaften.

Eigenschaft Beschreibung Erforderlich?
iteratorExpression Definiert einen Freemarker-Ausdruck, der eine Liste von Einträgen zurückgibt, über die Sie iterieren möchten. So können Sie der dataSet dynamisch mehrere Dateneinträge hinzufügen. Nein
iteratorVariable Gibt den Namen der Iteratorvariablen an, mit der Sie den aktuellen Dateneintrag in der Liste der Dateneinträge referenzieren können, über die iteriert wird. Nein
rangeSize Die Anzahl der Dateneinträge, die gleichzeitig angezeigt werden, wenn Sie die Eigenschaften iteratorExpression und iteratorVariable angegeben haben. Nein
visible Bestimmt, wie Nachrichten pro Benutzereingabe und Kanal angezeigt werden. Siehe Die sichtbare Eigenschaft. Nein
formTitle Der Titel, der für das Formulardialogfeld im Layout tableForm im Slack-Kanal verwendet wird. Der Standardwert ist View details. Nein
items Die Datenelemente, die für jede Dateneingabe angezeigt werden sollen. Siehe DataSet Datenelementeigenschaften. Ja

DataSet Datenelementeigenschaften

Eigenschaft Beschreibung Erforderlich?
width Der Prozentsatz (als Ganzzahl ausgedrückt) der gesamten verfügbaren Breite, die das Element in einem Tabellenlayout verwenden soll. Die verbleibende Breite, beginnend bei 100 minus den Elementen mit einer angegebenen Breite, wird gleichmäßig auf die Elemente aufgeteilt, ohne dass eine Breite angegeben wurde. Nein
alignment Die Ausrichtung des Wertes an einer Tabellenspalte. Zulässige Werte sind left, center und right. Der Standardwert ist left. Nein
displayType Der Anzeigetyp des Elements. Zulässige Werte sind text und link. Der Standardwert ist text. Nein
linkLabel Das Label, das für den Hyperlink verwendet wird, wenn der Anzeigetyp auf link gesetzt ist. Der Standardwert ist der Wert der Eigenschaft value des Elements. Nein
displayInTable Legt fest, ob das Element als Spalte in der Tabelle angezeigt werden soll. Diese Eigenschaft ist nur im Layout tableForm anwendbar. Wird standardmäßig auf false gesetzt. Nein
displayInForm Legt fest, ob das Element als Feld im Formular angezeigt werden soll. Diese Eigenschaft ist nur im Layout tableForm anwendbar. Wird standardmäßig auf false gesetzt. Nein
label Das Label des Datenelements. Ja
value Der Wert des Datenelements. Ja

Die Variable system.entityToResolve

Die Variable system.entityToResolve enthält Informationen zum aktuellen Status des Entityauflösungsprozesses, wie er von den Komponenten "Entitys auflösen" und "Gemeinsame Antwort" ausgeführt wird. In der Regel referenzieren Sie die Eigenschaften dieses Variablenwerts in den Metadaten der Komponente "Allgemeine Antwort", wenn Sie Nachrichten anpassen möchten. Sie können damit die Logik für die Fehlermeldung einer Entity oder für verschiedene Eigenschaften definieren, die zu den Komponenten "Entitys auflösen" und "Gemeinsame Antwort" gehören. Hängen Sie die folgenden Eigenschaften an, um den aktuellen Entitywert zurückzugeben:
  • userInput
  • prompt
  • promptCount
  • updatedEntities
  • outOfOrderMatches
  • disambiguationValues
  • enumValues
  • needShowMoreButton
  • rangeStartVar
  • nextRangeStart
Sie können auch die Eigenschaften in FreeMarker-Ausdrücken referenzieren, die Eigenschaften von Mischentityelementen wie prompt, errorMessage und Validierungsregeln verwenden.
Nachfolgend ein Beispiel für die Verwendung dieser Variablen zur Rückgabe der Benutzereingabe in der Fehlermeldung einer Entity:
Sorry,'${system.entityToResolve.value.userInput!'this'}' is not a valid pizza size.
Nachfolgend ein Beispiel für die Verwendung verschiedener system.entityToResolve-Definitionen. Bei diesen Meldungen handelt es sich um eine Meldung, die für die Eigenschaft text definiert wurde und eine Aktualisierung bestätigt, die an einem zuvor festgelegten Entitywert mit der Apache FreeMarker-Anweisung list und der Eigenschaft updatedEntities vorgenommen wurde.
    metadata:
      responseItems:        
      - type: "text" 
        text: "<#list system.entityToResolve.value.updatedEntities>I have updated <#items as ent>${ent.description}<#sep> and </#items>. </#list><#list system.entityToResolve.value.outOfOrderMatches>I got <#items as ent>${ent.description}<#sep> and </#items>. </#list>"
      - type: "text" 
        text: "${system.entityToResolve.value.prompt}"
        actions:
        - label: "${enumValue}"
          type: "postback"
          iteratorVariable: "system.entityToResolve.value.enumValues"
Bei globalen Aktionen steuert diese Variable die globale Aktion "Mehr anzeigen" mit den Eigenschaften needShowMoreButton, rangeStartVar und nextRangeStart:
        globalActions: 
        - label: "Show More"
          type: "postback" 
          visible:
            expression: "${system.entityToResolve.value.needShowMoreButton}"
          payload:
            action: "system.showMore"
            variables: 
              ${system.entityToResolve.value.rangeStartVar}: ${system.entityToResolve.value.nextRangeStart} 
        - label: "Cancel"
          type: "postback" 
          visible:
            onInvalidUserInput: true
          payload:
            action: "cancel"
Das Label "Mehr anzeigen" muss system.showMore (action: "system.showMore") enthalten. Andernfalls funktioniert es nicht.

Validierung der Benutzernachricht

Gemeinsame Antwortkomponenten validieren den vom Benutzer angegebenen Freitextwert, der für die Eigenschaft variable festgelegt wird. Beispiel: Wenn die Eigenschaft variable als primitiver Typ definiert ist (Zeichenfolge, boolescher Wert, Float, Double), versuchen diese Komponenten, den Wert mit einem der primitiven Typen abzustimmen. Wenn die Eigenschaft "variable" für eine Entityvariable definiert ist, rufen diese Komponenten die NLP-Engine auf, um den Wert in eine der Entitys aufzulösen. Wenn diese Komponenten einen Wert jedoch nicht validieren können, kann Ihr Bot eine Fehlermeldung anzeigen. Durch Referenzieren der Variablen system.invalidUserInput können Sie der Antwort Ihres Bots eine bedingte Fehlermeldung hinzufügen. Diese Variable ist ein boolescher Wert. Sie können sie als Bedingung mit der FreeMarker-Anweisung if verwenden, um die Nachricht nur anzuzeigen, wenn ein Benutzer einen ungültigen Wert eingibt. Andernfalls wird die Nachricht ausgeblendet. Der Status AskPizzaSize von CrcPizzaBot, der im folgenden Snippet referenziert wird, zeigt dies, indem diese Variable als Bedingung in einer FreeMarker-Vorlage hinzugefügt wird, die von der Anweisung if ausgewertet wird. Da sie auf true gesetzt ist, fügt der Bot der Standardnachricht (Welche Größe möchten Sie?) eine Fehlermeldung hinzu, wenn der Benutzer einen ungültigen Wert eingibt.
metadata:
  responseItems:
  - type: "text"
    text: "<#if system.invalidUserInput == 'true'>Invalid size, please try again.\
      \ </#if>What size do you want?"
    name: "What size"
    separateBubbles: true