Oracle Cloud Infrastructureドキュメント

B Apache FreeMarkerリファレンス

組込み文字列FreeMarker操作

次の表に、testerという文字列変数を例として使用して「組込み文字列操作」の一部を使用する方法を示します。 次のスニペットに示すように、値は"hello world "に設定されます(末尾に3つの空白があります):
context:
  variables:
    tester: "string"
…
states:
  setVariable:
    component: "System.SetVariable"
    properties:
      variable: "tester"
      value: "hello world   "
  
ノート

次のtextプロパティ定義により、ボットはtester値を出力したり、変数に値が設定されていない場合はno string foundを出力したりできます。
printVariable:
  component: "System.Output"
  properties:
    text: "${tester.value!'no string found'}"
  transitions: {} 
組込み操作 使用方法 出力
capitalize ${tester.value?capitalize} Hello World
last_index_of ${tester.value?last_index_of('orld')} 7
left_pad ${tester.value?left_pad(3,'_')} ___hello world
length ${tester.value?length} 14
lower_case ${tester.value?lower_case} hello world
upper_case ${tester.value?upper_case} HELLO WORLD
replace ${tester.value?replace('world', 'friends')} hello friends
remove_beginning ${tester.value?remove_beginning('hello')} world
trim ${tester.value?trim} hello world (末尾の3つのスペースは削除されます)
ensure_starts_with ${tester.value?ensure_starts_with('brave new ')} brave new hello world
ensure_ends_with ${tester.value?ensure_ends_with(' my friend')}$ hello world my friend
contains ${tester.value?contains('world')?string ('You said world', 'You did not say world')} You said world

contains('world')式は、trueまたはfalseを戻します。 これらのブール値は、string ('string1','string2')関数を使用して文字列で置換されます。

ends_with ${tester.value?ends_with('world')?string ('Ends with world', 'Doesn't end with world')} Ends with world
starts_with ${tester.value?starts_with('world')?string ('Starts with world', 'Doesn't start with world')} Doesn't start with world
matches (正規表現はtrueまたはfalseを返す) ${tester.value?matches('^([^0-9]*)$')} 正規表現は、値に数値が含まれているかどうか(この場合、ブール値はfalseとして返される)に応じて、trueまたはfalseを戻します。 tester値はtrueを戻します。
matches (正規表現は文字列を戻します) ${tester.value?matches('^([^0-9]*)$')?} 前述と同じですが、今回はtrueが文字列として返されます。 matches('regular expression')ファンクションは、trueまたはfalseをブール型として戻します。 System.Outputコンポーネントのtrueまたはfalseを印刷するには、?stringを使用して文字列への変換を実行します。

注意: 正規表現を使用して値のグループを返すことや、これらを使用して単一の一致する値を返す(または一致しない)ことはできません。

例: 大文字小文字による信頼度レベルの改善

ユーザー入力が大文字小文字を区別すると、インテント解決の信頼度レベルに影響する場合があります。 たとえば、Mayは月または動詞を参照し、ユーザー入力は間違えやすいです (Pizza、piZza、PIZZA)。 可能性のあるすべてのケース・バリエーションをエンティティ定義のシノニムとして捕捉するのではなく、次のスニペットのlower_caseなどのFTL演算子を使用して、大文字小文字を同じにすることができます。
getIntent:
    component: "System.Text"
      properties:
        prompt: "Hi, I am a the Pizza Palace bot. How can I help?"
        variable: "userstring"
      transitions: {}
toLowercase:
    component: "System.SetVariable"
      properties:
      variable: "userstring"
      value: "${userstring.value?lower_case}"
    transitions: {}
intent:
     component: "System.Intent"
      properties:
      variable: "iResult"
      sourceVariable: "userstring"
    transitions:
      actions:
      orderPizza: "orderPizza"
      cancelOrder: "cancelOrder"
      unresolvedIntent: "handleUnresolved"

これを実装するには、最初にSystem.Textコンポーネントを使用してユーザー入力を求めます。 この例では、System.Textコンポーネントがユーザー入力をuserstring変数に保存します。 Sytem.SetVariableでは、FTLを使用してユーザー入力文字列の大/小文字を小文字に変更し、変更した文字列を同じuserstring変数に保存します。 最後に、userstring変数は、sourceVariableプロパティを使用して、変更されたユーザー文字列をインテント・エンジンに対して実行するSystem.Intentコンポーネントによって参照されます。

例: System.Switchコンポーネントを使用したケースの変換

FTLで簡略化できる別のコンポーネントはSystem.Switchです。

次のスニペットには、choice変数に格納されているユーザー入力(ワインやビール)に応じてコールされる様々な状態が示されています。
switch:
    component: "System.Switch"
    properties:
      variable: "choice"
      values:
      - "wine"
      - "beer"
    transitions:
      actions:
        wine: "serverWine"
        beer: "serveBeer"
        NONE: "serveWater"
System.Textコンポーネントを使用して収集された入力の大/小文字の区別は、単語(WiNE)内でも一貫性がない可能性があります。 可能性のあるすべてのバリエーションをSystem.Switch定義に追加するかわりに、upper_caseなどのFTL操作を使用して、大文字小文字の区別を統一してください:
switch:
  component: "System.Switch"
  properties:
    source: "${choice.value?upper_case}"
    values:
    - "WINE"
    - "BEER"
transitions:
 actions:
  WINE: "serveWine"
  BEER: "serverBeer"
  NONE: "serveWater"

例: FTL式の連結

次のスニペットは、FTL式を連結して、ユーザー入力UA1234およびUA 1234を単純に1234に変換する方法を示しています。
normalizeFlightNumber:
  component: "System.SetVariable"
  properties:
    variable: "flight"
    value: "${flight.value?trim?lower_case?remove_beginning('ua ')
            ?remove_beginning('ua')}"

組込みのFreeMarker数値操作

次の表に、「ビルトイン数操作」をリストし、negativeValue (-2.5)およびpositiveValue (0.5175)コンテキスト変数の値セットを次のスニペットに出力する方法を示します。
context:
  variables:
    negativeValue: "float"
    positiveValue: "float"
states:
  setNegativeValue:
    component: "System.SetVariable"
    properties:
       variable: "negativeValue"
       value: -2.5
setPositiveValue:
  component: "System.SetVariable"
  properties:
    variable: "positiveValue"
    value: 0.5175
操作 出力
abs ${negativeValue.value?abs} 2.5

演算子によって、負の数値は正の値に変換されます。

string (数値とともに使用) ${negativeValue.value?abs?string.percent} 250%

演算子によって、最初に負の値が正の値に変更されます。 次に、この値をパーセントに変換し、暗黙的に値に100を乗算します。

string (小数点書式の値と様々な通貨を使用)

ティップ: その他の通貨記号については、文字ベースをチェックアウトしてください。

${positiveValue.value?string['###.##']} 0.51
${positiveValue.value?string['###.##%']} 51%

演算子では、値に100を乗算した後にパーセント文字が追加されます。

${positiveValue.value?string['##.###\u00A4']} 0.51 $
${positiveValue.value?string['##.###\u20AC']} 0.51 €
${positiveValue.value?string['##.###\u00A3']} 0.51 £
round ${negativeValue.value?round} -2

演算子は、最も近い整数に丸められます。 数値が.5で終わる場合、上位方向に丸められます。

${positiveValue.value?round} 1

演算子は、最も近い整数に丸められます。 数値が.5で終わる場合、上位方向に丸められます。

floor ${positiveValue.value?floor} 0

演算子は下向きに丸めます。

ceiling ${positiveValue.value?ceiling} 1

演算子は上に丸められます。

lower_abc ${negativeValue.value?abs?round?lower_abc} c

演算子によって負の値は正の値に変換され、3に丸められます。 C(アルファベットの3番目の文字)を返します。

upper_abc ${negativeValue.value?abs?round?upper_abc} C

演算子によって負の値は正の値に変換され、3に丸められます。 アルファベットの3番目の文字であるCが返されます。

is_infinite ${positiveValue.value?is_infinite?string} false

IEEE 754 (Floating-Point演算用のStandard)に従って浮動小数点値が無限大でないため、演算子はfalseを返します。

注意: 戻り値は?stringなしのブール値となります。

組込みFreeMarker配列操作

配列(または「順序」)操作を使用すると、ボット間で配列のサイズを決定したり、配列をソートしたり、配列内のコンテンツを検索できます。

配列操作は、インテントおよびエンティティ処理から結果を返します。 例えば:
  • ${iResult.value.entityMatches[‘name of entity’]}は、ユーザー文字列内で検出され、System.Intentコンポーネントに渡されてiResult: nlpresult変数に格納されたエンティティの配列を戻します。

  • ${iResult.value.intentMatches.summary}は、インテントの配列と、指定されたユーザー入力の信頼度レベルを返します。

配列を使用すると、テストのためにモック・データを作成したり、ユーザー・セッション以外に永続させるデータ構造を定義できます。 配列は、カスタム・コンポーネントや「ユーザー・スコープの変数」で保存できます。また、次のスニペットに示すように、コンテキスト変数に保存できます。 ここには、person変数およびcolors変数用の配列が設定されています。
context:
  variables:
    person: "string"
    colors: "string"
...

setPerson:
    component: "System.SetVariable"
    properties:
      variable: "person"
      value:
        - firstName: "Frank"
          lastName: "Normal"
        - firstName: "Grant"
          lastName: "Right"
        - firstName: "Geoff"
          lastName: "Power"
        - firstName: "Marcelo"
          lastName: "Jump"

...

setColors:
    component: "System.SetVariable"
    properties:
      variable: "colors"
      value:
        - "yellow"
        - "blue"
        - "red"
        - "black"
        - "white"
        - "green"
これらのcolorsおよびperson配列は、次の表および「例: 配列の反復」の配列操作の説明に使用されます。
演算子 出力
size ${person.value?size?number} 4-person配列のサイズ(4つのメンバー)
配列索引 ${person.value[1].firstName} Grant-person配列内の2番目のfirstNameプロパティの値です。
${person.value[1].firstName !'unknown'} 前述と同じですが、この場合、第2のfirstNameプロパティに値がない場合、ボットは不明と出力します。
first ${person.value?first.firstName} Frank-個人配列の最初のエントリ。 この操作では、配列索引は使用されません。
last ${person.value?last.firstName} Marcelo-個人配列内の最終的なlastName値。
sort_by ${person.value?sort_by('lastName') [0].firstName} Marcelo
この演算子では、lastNameプロパティでperson配列が昇順にソートされます。 次に、person配列内の最終エントリに対応するfirstNameプロパティの値を出力します:
  • Jump、Marcelo

  • 標準、ランク

  • Power, Geoff

  • 権限、付与

注意: System.SetVariableを使用して変数内のソート済配列を保存しないかぎり、データは単一のリクエストに対してのみソートされたままです。

${person.value?sort_by('lastName')?reverse[0].firstName} Grant-値は降順でソートされます:
  • Right, 付与

  • Power, Geoff

  • 標準、ランク

  • Jump、Marcelo

seq_index_of ${colors.value?seq_index_of('red')} 2-色配列の赤の索引値。
seq_last_index_of ${colors.value?seq_last_index_of('red')} 2-赤の最後の索引値
結合 ${colors.value?join(',')} colors配列をカンマ区切り文字列として返します: yellow, blue, red, black, white, green
seq_contains ${colors.value?seq_contains('red')? 配列には赤色があるので、Yesを返します。

注意: ?seq_containsはブール値を返します。 この値は、?string(‘...’.’...’)式を使用する文字列で置換されます。

sort ${colors.value?sort?join(',')} 色の配列をカンマ区切り文字列として昇順で返します: black, blue, green, red, white, yellow
reverse ${colors.value?sort?reverse?join(',')} colors配列をカンマ区切り文字列として降順に返します: yellow, blue, red, black, white, green

例: 配列の反復

配列は、ユーザー入力のエンティティの数を決定します。 次のスニペットは、person変数に保持されている配列のサイズを判別し、ボットが次のように出力するようにその要素を反復処理する方法を示しています:

    component: "System.CommonResponse"
    properties:
      metadata:
        responseItems:
        - type: "text"
          text: "${person?index+1}. ${person.firstName} ${person.lastName}"
          name: "Sorry"
          separateBubbles: true
          iteratorVariable: "person"
      processUserMessage: false