Oracle Cloud Infrastructureドキュメント

変数コンポーネント

これらは、YAMLベースのダイアログ・フロー・エディタの「変数」カテゴリで使用可能なコンポーネントです。

System.SetVariable

System.SetVariableコンポーネントは、事前定義済の変数の値を設定します。

プロパティ 説明 必須?
variable contextプロパティの1つとして定義される変数の名前。これは、エンティティまたは事前設定済の値(文字列など)に対して定義される変数です。 はい
value ターゲット値。リテラルとして、または別の変数を参照する式として定義できます。 はい
また、Apache FreeMarker式または(次のスニペットに示すように)リテラルを使用して、変数に対して事前設定済の値を設定することもできます。FreeMarkerの詳細は、ここで確認できます。
setOAuthRedirectURL:
    component: "System.SetVariable"
    properties:
      variable: "redirectURL"
      value: "https://thatcompany.io/connectors/v2/tenants/5c824-45fd-b6a2-8ca/listeners/facebook/channels/78B5-BD58-8AF6-F54B141/redirect"
    transitions:
      ...
System.OAuthAccountLinkを参照してください。
ノート

インテント・エンジンからのレスポンスの構造がリリース21.12で変更されました。リリース21.12より前は、nlpResultオブジェクトの最上位レベルのFullEntityMatchesおよびentityMatchesペイロードのペイロードには、コンポジット・バッグ・エンティティのアイテムによって参照されているが、インテントに直接関連付けられていないエンティティが含まれていました。リリース21.12以降、FullEntityMatchesおよびEntityMatchesオブジェクトのペイロードには、これらのエンティティは含まれなくなりました(かわりに、下位レベルのコンポジット・バッグ・アイテム・オブジェクト内にあります)。その結果、System.SetVariableを使用してiResult.value.entityMatchesなどの構文を使用してnlpResultオブジェクトに保持されている結果を使用して変数を設定する21.12にアップグレードされたスキルは、エンティティ値が存在しなくなったため失敗する可能性があります。スキルの継続的な機能を確認し、ベスト・プラクティスに従うには、コンポジット・バッグ(<variable_name>.value.<item_name>)の値を参照し、System.SetVariableコンポーネントのかわりにSystem.CommonResponseまたはSystemResolveEntitiesコンポーネントを使用します。

System.ResetVariables

このコンポーネントは、変数の値をnullにリセットします。

このコンポーネントには遷移は必要ありませんが、たとえば、ユーザーが新しい値を入力できるように、System.Intent状態に戻る遷移を設定できます。
プロパティ 説明 必須?
variableList リセットする必要がある変数のカンマ区切りリスト。
ドット表記法を使用して、コンテキスト変数(次の例ではexpense)として宣言されているコンポジット・バッグ内の特定のバッグ・アイテムの値をリセットします。 
resetExpenseType:
  component: "System.ResetVariables"
  properties:
    variableList: "expense.Type"
  transitions:
    next: "resolveExpense"
 はい

System.CopyVariables

変数値をコピーします。

このコンポーネントは、次のスニペット(値はユーザー・コンテキストにコピーされます)にあるように、fromおよびtoプロパティを使用して定義します:
setupUserContext:
    component: "System.CopyVariables"
    properties:
      from: "lastQuestion,lastResponse"
      to: "user.lastQuestion,user.lastResponse"
このコンポーネントにはこれらの両方のプロパティが必要ですが、これらの定義が相互を反映している必要はありません。fromとtoの両方を変数のリストとして定義できますが、fromを単一の変数で定義し、toをリストとして定義することもできます。追加のtoプロパティを設定した場合、継続するfromプロパティの変数値が継承されます。

System.SetCustomMetrics

このコンポーネントを使用して、カスタム・メトリック・レポートのスキルをインストゥルメントします。例:
  insights:
    component: "System.SetCustomMetrics"
    properties:
      dimensions:
       - name: "Pizza Size"
         value: "${size}"
       - name: "Pizza Type"
         value: "${type}"
       - name: "Crust Type"
         value: "${crust}"
    transitions:
      next: "summarizeOrder"
ノート

複数のディメンションを単一の状態に設定でき、スキルごとに最大6つのディメンションを定義できます。
属性 説明
name カスタム・メトリック・レポートに表示されるディメンションの名前(50文字以下)。文字、数字およびスペースのみを使用してください。特殊文字は使用しないでください。
value ディメンション値は、FreeMarker式またはテキスト文字列として定義できます。
  • FreeMarker式を使用して、エンティティに対して宣言されたcontext変数を参照します。たとえば、crust: "PizzaCrust"変数の場合、構文は"${crust}"です。コンポジット・バッグ内の値リスト・エンティティ・アイテムを参照するための構文は、"${<composite bag entity name>.value.<item name>}"です。たとえば、"${pizza.value.Crust}".
  • 文字列を使用して、ダイアログ・フロー定義で変数によって設定されず、かわりにスキル使用の他の側面を追跡する値を追跡します。 
    livechatTransfer:
    component: "System.AgentConversation"
    properties:
...
    transitions:
      actions:
        agentLeft: "livechatEndPrompt"
        expired: "livechatEndPrompt"
        error: "livechatHandleNoTransfer"
      next: "setInsightsCustomMetrics"

  setInsightsCustomMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "transferred"
...

  setInsightsCustomMetrics2:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "not transferred"
    transitions:
       return: "done"

例: 複数の状態にわたる単一のディメンションの設定

次のスニペットは、一連のSystem.SetCustomMetrics状態から単一のディメンション(Agent Transfer)を作成する方法を示しています。 
states:
  intent:
    component: "System.Intent"
    properties:
      variable: "iResult"
      optionsPrompt: "Do you want to"      
    transitions:
      actions:
        OrderPizza: "startOrderPizza"
        WelcomePizza: "startWelcome"
        LiveChat: "setInsightsCustomMetrics3"
        unresolvedIntent: "startUnresolved"

...

  setInsightsCustomMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Pizza Size"
        value: "${pizza.value.PizzaSize}"
      - name: "Pizza Type"
        value: "${pizza.value.PizzaTopping}"
      - name: "Pizza Crust"
        value: "${pizza.value.PizzaDough}"
      - name: "Agent Transfer"
        value: "No Agent Needed"
    transitions:
      next: "showPizzaOrder"

...
   
  startUnresolved:
    component: "System.Output"
    properties:
      text: "I didn't that get that. Let me connect you with support."
      keepTurn: true 
    transitions:
      next: "setInsightsCustomMetrics1"
      
### Transfer because of unresolved input ####

  setInsightsCustomMetrics1:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "Bad Input"
    transitions:
      next: "getAgent"

  maxError:
    component: "System.Output"
    properties:
      text: "OK, let's connect you with someone to help"
      keepTurn: true
    transitions:
      next: "setInsightsCustomMetrics2"
      
### Transfer because of Max Error"  ####

  setInsightsCustomMetrics2:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "Max Errors"
    transitions:
      next: "getAgent"
      
### Transfer because of direct request ####

  setInsightsCustomMetrics3:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Agent Transfer"
        value: "Agent Requested"
    transitions:
      next: "getAgent"

  getAgent:
    component: "System.AgentInitiation"

...

各System.SetCustomMetrics状態は、エージェント転送ディメンションに異なるカテゴリを定義します。カスタム・メトリック・レポートでは、これらの状態が実行フローに含まれており、前述のサンプルに示されているように遷移に名前が付けられている場合に、これらのメトリックのデータが記録されます。

エージェント転送ディメンションのカスタム・メトリック状態 値 使用
setInsightsCustomMetrics エージェント不要 注文が支援なしで行われた会話の成功数を反映します。
setInsightsCustomMetrics1 不正な入力 未解決の入力によってユーザーがライブ・エージェントに転送された収束の数を反映します。
setInsightsCustomMetrics2 最大エラー数 ユーザーがライブ・エージェントに到達したためにライブ・エージェントに誘導された会話の数を反映します。
setInsightsCustomMetrics3 エージェントがリクエストされました ユーザーがライブ・エージェントをリクエストした会話の数を反映します。

例: ユーザー・フィードバックのメトリックのトラッキング

フィードバック・メトリックを追跡するには、対応するSystem.SetCustomMetrics状態をSystem.Feedback遷移状態に追加します。例:
...
  getUserFeedback:
    component: "System.Feedback"
    properties: 
      threshold: 2
      maxRating: 5
      enableTextFeedback: true
      footerText: 
    transitions:
      actions:
        above: "PositiveFeedbackMetrics"
        below: "NegativeFeedbackMetrics"
        cancel: "CancelFeedbackMetrics"
        
        
  PositiveFeedbackMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Feedback Type"
        value: "Positive"
    transitions:
      next: "positiveFeedback"        
        
        
  positiveFeedback:
    component: "System.Output"
    properties:
      text: "Thank you for the ${system.userFeedbackRating.value}-star rating."
    transitions:
      return: "done"
      
  NegativeFeedbackMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Feedback Type"
        value: "Negative"
    transitions:
      next: "negativeFeedback"
      
  negativeFeedback:
    component: "System.Output"
    properties:
      text: "Thank you for your feedback."
    transitions:
      return: "done"
      
  CancelFeedbackMetrics:
    component: "System.SetCustomMetrics"
    properties:
      dimensions: 
      - name: "Feedback Type"
        value: "Canceled"   
    transitions:
      next: "cancelFeedback"        
      
  cancelFeedback:
    component: "System.Output"
    properties:
      text: "Maybe next time."
    transitions:
      return: "done"