動作的表示式語言方法

now(String timezone)

now() 方法會傳回指定時區的現行日期和時間，格式為 yyyy-MM-dd HH:mm:ss 'GMT'XXX:

now('Australia/Sydney').

在此範例中，如果現行日期和時間是 2021-11-26 11:41:00，則傳回的字串是 2021-11-26 21:41:00 GMT+10.00 或 2021-11-26 21:41:00 GMT+11.00，視「日光節約時間」而定。

輸出字串格式變更也適用於日期和時間計算方法。 例如，如果使用的 <date> 字串格式為 yyyy-MM-dd HH:mm:ss，例如當您使用方法 today() 時，則輸出格式相同 (yyyy-MM-dd HH:mm:ss)。不過，如果 <date> 字串的格式為 yyyy-MM-dd HH:mm:ss 'GMT'XXX(例如當您使用方法 now() 時)，則輸出格式為 yyyy-MM-dd HH:mm:ss 'GMT'XXX。

.reformatDateTime(String format)

格式化輸出的日期和時間字串。 參數是指定如何格式化日期或時間值的格式字串。 必須使用 Java SimpleDateFormat 語法來指定格式字串。

此方法會傳回根據指定格式來格式化的字串:

• MM/dd/yyyy 表示 12/31/2016
• h a 表示 10pm

若要傳回星期幾，請指定：

• EEEE 代表星期二
• E for Tue
• u 表示日期索引（1 = 星期一、...、7 = 星期日）

例如，此表示式會將值 17:30:00 傳回為 5:30 PM:

${system_current_date}.reformatDateTime('h:mm a')

如果輸入字串僅包含時間，則會在輸出中使用預設日期 1970-01-01。 如果輸入字串只包含日期，則會使用預設時間 12 AM (00:00)。

.before(String date/time)

• 決定日期和時間值是否在指定的日期和時間引數之前，如下列範例所示:

${system_current_date}.before('2021-11-19')

您可以將日期與另一個日期相比較，或將時間與另一個時間相比較。 您也可以比較時間與日期和時間值，在此情況下會忽略日期，且只比較時間。 任何不符值的其他比較 (例如，比較日期與時間) 都會傳回 false，異常狀況會記載在 output.debug.log_messages 中 (您可以在助理預覽或 API 回應中看到)。

.after(String date/time)

• 決定日期和時間值是否在日期和時間引數之後。

.sameMoment(String date/time)

• 決定日期和時間值是否與日期和時間引數相同。

.sameOrAfter(String date/time)

• 決定日期和時間值是否晚於或與日期和時間引數相同。
• 類似 .after()。

.sameOrBefore(String date/time)

• 決定日期和時間值是在日期和時間引數之前，還是與日期和時間引數相同。

日期和時間計算

使用下列方法來計算日期。

其中 <date> 是以 yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss 格式指定。

例如，若要取得明天的日期，請指定下列表示式:

${system_current_date}.plusDays(1)

使用下列方法來計算時間。

其中 <time> 是以 HH:mm:ss 格式指定。

例如，若要從現在開始取得時間一小時，請指定下列表示式:

 now().plusHours(1)  

使用時間跨距

若要根據今天的日期是否落在特定時間範圍內來顯示回應，您可以使用時間相關方法的組合。 例如，如果您在每年的假期期間執行特殊優惠，您可能想要檢查今天的日期是否落在今年的 11 月 25 日至 12 月 24 日之間。

首先，將感興趣的日期定義為階段作業變數。 在下列開始和結束日期階段作業變數表示式中，透過連結動態現行年份值與寫在程式中的月份和日期值來建構日期:

start_date = now().reformatDateTime('Y') + '-12-24'
end_date = now().reformatDateTime('Y') + '-11-25'

然後，在步驟條件中，您可以指出只有在現行日期介於您定義為階段作業變數的開始和結束日期之間時，才要顯示回應:

now().after(${start_date}) && now().before(${end_date})

java.util.Date 支援

除了內建方法之外，您還可以使用 java.util.Date 類別的標準方法。

例如，若要取得從今天開始一週的日期，您可以使用下列語法:

new Date(new Date().getTime() + (7 * (24*60*60*1000L)))

此表示式會先取得現行日期（以毫秒為單位，自 1970 年 1 月 1 日 00:00:00 GMT 開始）。 它也會計算以 7 天為單位的毫秒數 ((24*60*60*1000L) 代表以毫秒為單位的一天)。 它接著會將現行日期加上 7 天。 結果是從今天開始一週內的完整日期 (例如，Fri Jan 26 16:30:37 UTC 2018)。

toDouble()

將物件或欄位轉換為 Double 數字類型。 您可以在任何物件或欄位上呼叫此方法。 如果轉換失敗，則會傳回 null。

toInt()

將物件或欄位轉換為 Integer 數字類型。 您可以在任何物件或欄位上呼叫此方法。 如果轉換失敗，則會傳回 null。

toLong()

將物件或欄位轉換為 Long 數字類型。 您可以在任何物件或欄位上呼叫此方法。 如果轉換失敗，則會傳回 null。

若要在 SpEL 表示式中指定 Long 數字類型，您必須將 L 附加至數字，以將其識別為如此 (例如，5000000000L)。任何不符合 32 位元整數類型的數字都需要此語法。 大於 2 ^ 31 (2,147,483,648) 或小於 -2 ^ 31 (-2,147,483,648) 的數字視為 Long 數字類型。 Long 數字類型的最小值為 -2^63，而最大值為 2^63-1（或 9,223,372,036,854,775,807）。

標準數學

使用 SpEL 表示式可定義標準數學方程式，其中運算子使用以下符號來代表：

java.lang.Math()

您可以使用 java.lang.Math 類別的函數來執行基本數值作業。

您可以使用 Class 方法，包括:

• max():

  T(Math).max(${step_297},${step_569})
  

• min():

  T(Math).min(${step_297},${step_569})
  

• pow():

  T(Math).pow(${step_297}.toDouble(),2.toDouble())
  

如需其他方法的相關資訊，請參閱 java.lang.Math 參考文件。

java.util.Random()

傳回亂數。 您可以使用下列任何語法選項:

• 若要傳回隨機布林值 (true 或 false)，請使用 new Random().nextBoolean()。
• 若要傳回介於 0 (包括) 與 1 (排除) 之間的隨機倍精準數，請使用 new Random().nextDouble()
• 若要傳回介於 0 (包括) 與您指定的數字之間的隨機整數，請使用 new Random().nextInt(_n_)，其中 n 大於您想要的數字範圍頂端。 例如，如果您要傳回介於 0 和 10 之間的亂數，請指定 new Random().nextInt(11)。
• 若要傳回完整整數值範圍 (-2147483648 至 2147483648) 中的隨機整數，請使用 new Random().nextInt()。

例如，您可以建立僅針對隨機選取的客戶子集執行的步驟。 下列步驟條件表示步驟有 50% 機會執行:

new Random().nextInt(2) == 1

如需其他方法的相關資訊，請參閱 java.util.Random 參考文件。

您也可以使用下列類別的標準方法:

• java.lang.Byte
• java.lang.Integer
• java.lang.Long
• java.lang.Double
• java.lang.Short
• java.lang.Float

String.append(Object)

此方法會將輸入物件 (以字串形式) 附加至字串，並傳回已修改的字串。

${step_297}.append('next text')

String.contains(String)

如果動作變數或階段作業變數包含在條件中有用的子字串，則此方法會傳回 true。

${step_297}.contains('Yes')

String.endsWith(String)

如果字串以輸入子字串結尾，則此方法會傳回 true。

${step_297}.endsWith('?')

String.equals(String)

如果指定的字串等於動作變數或階段作業變數，則此方法會傳回 true。

${step_297}.equals('Yes')

String.equalsIgnoreCase(String)

如果指定的字串等於動作變數或階段作業變數 (不論觀察值為何)，則此方法會傳回 true。

${step_297}.equalsIgnoreCase('Yes')

String.extract(String regexp, Integer groupIndex)

此方法會從輸入中傳回符合指定正規表示式群組型樣的字串。 如果找不到相符項，則會傳回空字串。

此方法旨在擷取不同正規表示式型樣群組的相符項，而不是擷取單一正規表示式型樣的不同相符項。 若要尋找不同的相符項，請參閱 getMatch() 方法。

在此範例中，動作變數會儲存符合您指定的正規表示式型樣群組的字串。 在表示式中，定義兩個正規表示式型樣群組，並以括弧括住每個群組。 固有是由兩個群組組成的第三個群組。 這是第一個 (groupIndex 0) 正規表示式群組; 它符合包含完整數字群組和文字群組的字串。 第二個正規表示式群組 (groupIndex 1) 與第一次出現的數字群組相符。 第三個群組 (groupIndex 2) 與數字群組後第一次出現的文字群組相符。

${step_297}.extract('([\d]+)(\b [A-Za-z]+)', <n>)

如果動作變數包含:

Hello 123 this is 456.

結果如下:

• 若 <n>=0，則值為 123 this。
• 若 <n>=1，則值為 123。
• 若 <n>=2，則值為 this。

String.find(String regexp)

如果字串的任何區段符合輸入正規表示式，則此方法會傳回 true。 您可以針對 JSONArray 或 JSONObject 元素呼叫此方法，並在進行比較之前將陣列或物件轉換為字串。

例如，如果動作變數 ${step_297} 收集字串 Hello 123456，則下列表示式會傳回 true:

${step_297}.find('^[^\d]*[\d]{6}[^\d]*$')

條件是 true，因為輸入文字的數值部分符合正規表示式 ^[^\d]*[\d]{6}[^\d]*$。

String.getMatch(String regexp, Integer matchIndex)

此方法會傳回符合所指定正規表示式型樣的出現項目的字串。 如果找不到相符項，則此方法會傳回空字串。

找到相符項時，會將它們新增至您可以視為相符項陣列的項目。 因為陣列元素計數從 0 開始，所以如果您想要傳回第三個相符項，則會指定 2 作為 matchIndex 值。 例如，如果輸入的字串包含與指定型樣相符的三個字組，則只能藉由指定其索引值來傳回第一個、第二個或第三個相符項。

例如，下列範例是在動作變數中尋找一組數字。

${step_297}.getMatch('([\d]+)', 1)

如果動作變數 ${step_297} 包含字串 hello 123 i said 456 and 8910，則此表示式會傳回 456。

String.isEmpty()

如果字串是空字串，但不是 null，則此方法會傳回 true，如下列範例中所示:

${step_297}.isEmpty()

String.length()

此方法會傳回字串的字元長度，如下列範例所示:

${step_297}.length()

如果動作變數 ${step_297} 包含字串 Hello，則此表示式會傳回 5。

String.matches(String regexp)

如果字串符合輸入正規表示式，則此方法會傳回 true，如下列範例所示:

${step_297}.matches('^Hello$')

如果動作變數 ${step_297} 包含字串 Hello，則此表示式會評估為 true。

String.startsWith(String)

如果字串以指定的子字串開頭，則此方法會傳回 true，如下列範例所示:

${step_297}.startsWith('What')

如果動作變數 ${step_297} 包含字串 What is your name?，則此表示式會傳回 true。

String.substring(Integer beginIndex, Integer endIndex)

此方法會傳回子字串，以 beginIndex 中的字元開頭，並以 endIndex 之前的字元結尾。 ( endIndex 字元本身不包含在子字串中。) 索引值以零為基礎，因此字串中的第一個字元位於索引 0。

此範例會傳回從索引 5 (這是第六個字元) 開始，並繼續到字串結尾的子字串:

${step_297}.substring(5, ${step_297}.length())

如果動作變數 ${step_297} 包含字串 This is a string.，則此表示式會傳回 is a string.

String.toJson()

此方法會剖析包含 JSON 資料的字串，並傳回 JSON 物件或陣列，如下列範例所示:

${json_var}.toJson()

如果階段作業變數 ${json_var} 包含下列字串:

"{ \"firstname\": \"John\", \"lastname\": \"Doe\" }"

toJson() 方法會傳回下列物件:

{
  "firstname": "John",
  "lastname": "Doe"
}

String.toLowerCase()

此方法會傳回轉換為小寫字母的指定字串，如下列範例所示:

${step_297}.toLowerCase()

如果動作變數 ${step_297} 包含字串 This is A DOG!，則此表示式會傳回字串 this is a dog!。

String.toUpperCase()

此方法會傳回轉換為大寫字母的原始字串，如下列範例所示:

${step_297}.toUpperCase()

如果動作變數 ${step_297} 包含字串 hi there，則此方法會傳回字串 HI THERE。

String.trim()

此方法會修整字串開頭和結尾的任何空格，並傳回已修改的字串，如下列範例所示:

${step_297}.trim()

如果動作變數 ${step_297} 包含字串 something is here ，則此方法會傳回字串 something is here。

java.lang.String 支援

除了內建方法之外，您還可以使用 java.lang.String 類別的標準方法。

T(java.lang.String).format('%d + %d equals %d', 1, 1, 2)

T(String).format('%.2f',${step_297})

Array.add(value...)

此方法會將一個以上新值新增至陣列，並在作業成功時傳回 true。

${Items}.add('four', 'five')

如果 Items 為 ['one', 'two', 'three']，則此範例會就地更新它，以變成 ['one', 'two', 'three', 'four', 'five']。

Array.addAll(Array array)

此方法會將一個陣列新增至另一個陣列，並傳回 null。

${Items}.addAll(${New_items})

如果 Items 是 ['one', 'two', 'three'] 且 New_items 是 ['four', 'five', 'six']，則此範例會就地更新 Items 以變成 ['one', 'two', 'three', 'four', 'five', 'six']。

Array.append(value...)

此方法會將一個以上新值附加至陣列，並以新陣列傳回結果。 未修改原始陣列。

${Items}.append('four', 'five')

如果 Items 為 ['one', 'two', 'three']，則此範例會傳回新陣列 ['one', 'two', 'three', 'four', 'five']。

Array.clear()

此方法會從陣列中移除所有值並傳回空值。

${Items}.clear()

在評估此表示式之後，Items 是空陣列 ([])。

Array.contains(value)

如果陣列包含完全等於輸入值的項目，則此方法會傳回 true。 指定的值可以是字串或數字。

${Items}.contains(123)

如果 Items 為 [123, 456, 789]，則此範例會傳回 true。

Array.containsIgnoreCase(value)

如果陣列包含等於輸入值的項目，則此方法會傳回 true。 不論值是以大寫字母或小寫字母來指定，都會符合字串。 指定的值可以是字串或數字。

${Items}.contains('two')

如果 Items 陣列包含字串 two 的任何大寫 (例如，TWO 或 Two 也符合)，則此範例會傳回 true。

Array.filter(temp_var, "temp_var.property operator comparison_value")

將每一個陣列元素與您指定的值相互比較，以過濾陣列，並傳回只包含相符元素的新陣列。

過濾表示式由下列值組成：

• temp_var: 臨時變數的任意名稱，用來在評估每一個陣列元素時保留它。 例如，如果原始陣列包含說明城市的物件，您可以使用 city 作為臨時變數名稱。

• property: 您要過濾的元素內容。 這必須是來源陣列中元素的內容。 使用語法 temp_var.property，將內容指定為 temp_var 的內容。 例如，如果 latitude 是來源元素的有效內容名稱，您可以將內容指定為 city.latitude。

• operator: 用來比較內容值與比較值的運算子。 您可以使用下列任何運算子:

  支援的過濾運算子

  操作員	說明
  ==	等於
  >	大於
  <	小於
  >=	大於或等於
  <=	小於或等於
  !=	不等於

• comparison_value: 您要比較每一個陣列元素內容值的值。 您可以指定文字值或參照變數。

[
   {
      "name":"Tokyo",
      "population":13988129

   },
   {
      "name":"Rome",
      "population":2860009

   },
   {
      "name":"Beijing",
      "population":21893095

   },
   {
      "name":"Paris",
      "population":2165423

   }
]

${cities}.filter("city", "city.population > 5000000")

[
   {
      "name":"Tokyo",
      "population":13988129

   },
   {
      "name":"Beijing",
      "population":21893095

   }
]

${cities}.filter("city", "city.population > ${step_123}")

Array.get(Integer index)

此方法會從陣列中傳回位於指定索引位置的項目。 陣列為零索引，表示陣列中的第一個項目位於索引位置 0。

${Items}.get(1)

如果 Items 為 ['one', 'two', 'three']，則此範例會傳回 two。

get() 方法是使用方括弧 ([]) 從陣列中擷取項目的替代方案。 下列範例也是有效的，並傳回相同的結果:

${Items}[1]

如果您使用客戶指定的值從陣列中選擇項目，則可能需要扣除 1 才能轉換為零索引值。 例如，您可以使用 ${Items}.get(${step_123} - 1) 之類的表示式來擷取預期值。

Array.getRandomItem()

此方法會從陣列中傳回隨機選擇的項目。

${Items}.getRandomItem()

如果 Items 為 ['one', 'two', 'three']，則此範例會隨機傳回 one、two 或 three。

Array.indexOf(value)

此方法會傳回陣列中第一次出現輸入值的索引位置，如果陣列不包含輸入值，則會傳回 -1。 指定的值可以是字串或數字。

${Items}.indexOf(`two`)

如果 Items 為 ['one', 'two', 'three']，則此範例會傳回整數 1 (指出零索引陣列中的第二個位置)。

Array.join(String delimiter)

此方法會將這個陣列中的所有值都結合至字串。 值會轉換為字串，並以輸入定界字元分隔。

例如，您可以使用名為 pizza_toppings 且包含陣列 ["pepperoni", "ham", "mushrooms"] 的變數。 下列表示式會將此陣列轉換為字串 pepperoni, ham, mushrooms:

${toppings_array}.join(', ')

如果您使用該表示式來定義變數值，則可以在助理輸出中參照該變數，以建立人類可讀的訊息 (例如 You have selected the following toppings: pepperoni, ham, mushrooms)。

JSONArray.joinToArray(template, retainDataType)

此方法會從陣列中的每一個項目擷取資訊，並根據您指定的範本來建置格式化的新陣列。 範本可以是字串、JSON 物件或陣列。 此方法會傳回字串陣列、物件陣列或陣列陣列 (視範本類型而定)。

此方法適用於將資訊格式化為字串，您可以在步驟輸出中傳回該字串，或將資料轉換成不同的結構，以便您可以將它與外部 API 搭配使用。

在範本中，您可以使用下列語法來參照來源陣列中的值:

%e.{property}%

其中 {property} 代表來源陣列中的內容名稱。

例如，假設您的助理儲存在階段作業變數中包含航班詳細資料的陣列。 儲存的資料可能如下所示:

"flights": [
      {
        "flight": "AZ1040",
        "origin": "JFK",
        "carrier": "Alitalia",
        "duration": 485,
        "destination": "FCO",
        "arrival_date": "2019-02-03",
        "arrival_time": "07:00",
        "departure_date": "2019-02-02",
        "departure_time": "16:45"
      },
      {
        "flight": "DL1710",
        "origin": "JFK",
        "carrier": "Delta",
        "duration": 379,
        "destination": "LAX",
        "arrival_date": "2019-02-02",
        "arrival_time": "10:19",
        "departure_date": "2019-02-02",
        "departure_time": "07:00"
      },
      {
        "flight": "VS4379",
        "origin": "BOS",
        "carrier": "Virgin Atlantic",
        "duration": 385,
        "destination": "LHR",
        "arrival_date": "2019-02-03",
        "arrival_time": "09:05",
        "departure_date": "2019-02-02",
        "departure_time": "21:40"
      }
    ]

若要建置以使用者可讀取的形式說明這些航班的字串陣列，您可以使用下列表示式:

${Flight_data}.joinToArray("Flight %e.flight% to %e.destination%", true)

此表示式會傳回下列字串陣列: ["Flight AZ1040 to FCO","Flight DL1710 to LAX","Flight VS4379 to LHR"]。

retainDataType 選用參數指定方法是否保留所傳回陣列中所有輸入值的資料類型。 如果 retainDataType 設為 false 或省略，在某些狀況下，輸入陣列中的字串可能會轉換成所傳回陣列中的數字。 例如，如果從輸入陣列選取的值是 "1"、"2" 和 "3"，則傳回的陣列可能是 [ 1, 2, 3 ]。 若要避免非預期的類型轉換，請針對此參數指定 true。

<br/>Flight number: %e.flight% <br/> Airline: %e.carrier% <br/> Departure date: %e.departure_date% <br/> Departure time: %e.departure_time% <br/> Arrival time: %e.arrival_time% <br/>

${Flight_data}.joinToArray(${Template})

Flight number: AZ1040
Airline: Alitalia
Departure date: 2019-02-02
Departure time: 16:45
Arrival time: 07:00

Flight number: DL1710
Airline: Delta
Departure date: 2019-02-02
Departure time: 07:00
Arrival time: 10:19

Flight number: VS4379
Airline: Virgin Atlantic
Departure date: 2019-02-02
Departure time: 21:40
Arrival time: 09:05

{
  "departure": "Flight %e.flight% departs on %e.departure_date% at %e.departure_time%.",
  "arrival": "Flight %e.flight% arrives on %e.arrival_date% at %e.arrival_time%."
}

Array.remove(Integer index)

此方法會從陣列中移除指定索引位置中的項目，並傳回更新的陣列。

${Items}.remove(1)

如果 Items 為 ['one', 'two', 'three']，則此範例會傳回 ['one', 'three']。 原始 Items 陣列也會就地修改。

Array.removeValue(value)

此方法會從陣列中移除第一次出現的指定值，並傳回更新的陣列。 指定的值可以是字串或數字。

${Items}.removeValue('two')

如果 Items 為 ['one', 'two', 'three']，則此範例會傳回 ['one', 'three']。 原始 Items 陣列也會就地修改。

Array.set(Integer index, value)

此方法會將指定索引位置中的項目取代為指定值，並傳回更新的陣列。

${Items}.set(2,'five')

如果 Items 為 ['one', 'two', 'three']，則此範例會傳回 ['one', 'two', 'five']。 原始 Items 陣列也會就地修改。

Array.size()

此方法會以整數傳回陣列中的項目數。

${Items}.size()

如果 Items 為 ['one', 'two', 'three']，則此範例會傳回 3。

Array.sort()

此方法會執行就地排序，並傳回已排序的陣列。 預設參數為 ascending。 您可以指定 descending 來變更排序順序。 任何其他參數項目都會被忽略，且會出現日誌錯誤。

${Items}.sort("ascending")

此方法會比較數字和字串。 數字一律小於字串。 依預設，任何其他類型都會轉換成字串來比較。

例如：

Array.transform()

Array.transform() 方法僅與 session_history 變數 搭配使用。 您可以轉換變數的輸出，以符合特定的產生 AI 系統。

表格: 會談格式的簽章 顯示可用於不同會談格式的簽章:

如果 currentAction 為 true:

轉換輸出中不包含 n : true 旗標。