Runbookの式と式内関数リファレンス

目次

[更新: 2026年4月30日]

ワークフローでは 式 （expression）を利用して変数の値を参照したり、リテラルや変数を演算したりできます。ここではワークフロー中の式と、式内で使える関数について説明します。

式について

式は、次の形式で記述します。

${ ... }

式は、以下のような場所で記述できます。

• assignのステップで変数に値を代入する

• returnのステップで値を返す

式の解釈や値の型の扱いは、JavaScriptの構文解析ライブラリーであるEsprimaに基づきます。そのため式の記法や挙動はJavaScriptに準じます。

参考

Esprimaの詳細については、次のWebサイトを参照してください。

ECMAScript parsing infrastructure for multipurpose analysis

式の記述例

式の記述例は、以下のようになります。

${args.XXXX}

ワークフローに渡された引数（args）のうち XXXX という引数名の値を参照します。

${userName + "さん"}

変数 userName の値と文字列リテラル「さん」を足し合わせます（文字列の演算）。

${math.abs(-2)}

式内関数 math.abs を「-2」という引数で呼びます。

式の値と型

式の値には、ワークフローの引数（args）と同様にいくつかの型があります。

• 文字列（string）・数字（number）・真偽値（boolean）・nullというプリミティブな型

• 配列（array）・連想配列（object）という複合型

ヒント

このマニュアルページでは、どの型でもよい場合に「any」と表記します。また、配列は「リスト」として、連想配列は「マップ」としても表記します。

参考

ワークフローの引数の型については、構文リファレンスの「args」の項目を参照してください。

式内関数

式では、いくつかの関数を利用できます。これを 式内関数 と呼び、次のようにグループ分けできます。

• array

• json

• list

• map

• math

• test

• text

• time

• uuid

以降で、式内関数を順に説明します。

arrayグループ

arrayグループの式内関数では、配列を操作します。

ヒント

配列の添字（インデックス）はゼロ（0）から始まります。

array.fill関数

配列のすべての要素を指定した値に変更します。構文は次のようになります。

array.fill(<list>, <value>)

引数	型	説明
list	array	置き換えられるもとのリスト
value	any	すべての要素を置き換える値

戻り値の型は array です。arrayのすべての要素をvalueに置き換えたリストを返します。

記述例は以下のようになります。

steps:
  fill:
    return: ${array.fill([1, 2, 3], 0)}
    # return [0, 0, 0]

array.range関数

引数の条件にあわせた連番のリストを生成して返します。構文は次のようになります。

array.range(<start?>, <stop>, <step?>)

引数	型	説明
start?	number	開始値。省略可。省略した場合は0
stop	number	終了値
step?	number	ステップ幅。省略可。省略した場合は1

戻り値の型は array です。引数の条件に合った連番のリストを返します。例えば、array.range(5) は0から4まで5つの整数のリスト（[0, 1, 2, 3, 4]）を生成します。

記述例は以下のようになります。

steps:
  range:
    return: ${array.range(0, 10)}
    # return [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

array.push関数

配列の末尾に指定した値を追加します。構文は次のようになります。

array.push(<list>, <value>)

引数	型	説明
list	array	追加されるもとのリスト
value	any	最後に追加する要素

戻り値の型は array です。arrayの末尾にvalueを追加して返します。

記述例は以下のようになります。

steps:
  push:
    return: ${array.push([1, 2, 3], 4)}
    # return [1, 2, 3, 4]

array.set関数

配列の指定した要素に指定した値をセットします。構文は次のようになります。

array.set(<list>, <index>, <value>)

引数	型	説明
list	array	追加されるもとのリスト
index	number	追加する位置を示すインデックス
value	any	追加する要素

戻り値の型は array です。arrayのindexで指定した要素にvalueをセットして返します。

記述例は以下のようになります。

steps:
  set:
    return: ${array.set([1, 2, 3], 1, 1)}
    # return [1, 1, 3]

array.length関数

配列の長さを返します。構文は次のようになります。

array.length(<list>)

引数	型	説明
list	array	長さを取得するリスト

戻り値の型は number です。配列に含まれる要素の数を返します。

記述例は以下のようになります。

steps:
  length:
    return: ${array.length([1, 2, 3])}
    # return 3

jsonグループ

jsonグループの式内関数では、連想配列のエンコードとデコードを行います。

ヒント

連想配列に変換される（あるいは変換後の）文字列（バイト列）の文字コードは、UTF-8を想定します。

json.decode関数

バイト列や文字列を、連想配列に変換します。構文は次のようになります。

json.decode(<data>)

引数	型	説明
data	string	デコードされる入力データ

戻り値の型は object です。引数のdataを連想配列にデコードして返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      stringData: '{"name":"watashi","age":20,"address":"東京都港区"}'
  decode:
    return: ${json.decode(stringData)}
    # return {name: "watashi", age: 20, address: "東京都港区"}

json.encode関数

連想配列を文字列に変換します。構文は次のようになります。

json.encode(<data>)

引数	型	説明
data	object	エンコードされる入力データ

戻り値の型は string です。引数のdataを文字列にエンコードして返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      jsonData: {name: "watashi", age: 20, address: "東京都港区"}
  encode:
    return: ${json.encode(jsonData)}
    # return "{\"name\":\"watashi\",\"age\":20,\"address\":\"東京都港区\"}"

listグループ

listグループの式内関数では、リスト（配列）に値を追加します。

ヒント

引数のリストは変更されないことに注意してください。

list.concat関数

リストの末尾に指定した値を追加します。構文は次のようになります。

list.concat(<list>, <value>)

引数	型	説明
list	array	追加されるもとのリスト。
value	any	最後に連結される要素

戻り値の型は array です。arrayの末尾にvalueを追加したリストを返します。

記述例は以下のようになります。

steps:
  concat:
    return: ${list.concat([1, 2, 3], 4)}
    # return [1, 2, 3, 4]

list.prepend関数

リストの先頭に指定した値を追加します。構文は次のようになります。

list.prepend(<list>, <value>)

引数	型	説明
list	array	追加されるもとのリスト
value	any	最初に追加される要素

戻り値の型は array です。arrayの先頭にvalueを追加したリストを返します。

記述例は以下のようになります。

steps:
  prepend:
    return: ${list.prepend([1, 2, 3], 0)}
    # return [0, 1, 2, 3]

mapグループ

mapグループの式内関数では連想配列（マップ）を操作します。

ヒント

mapグループでは、引数および戻り値が object 型の場合、キーを string 型、値を any 型とする連想配列を想定します。

map.delete関数

連想配列から指定したキーの項目を削除します。構文は次のようになります。

map.delete(<map>, <key>)

引数	型	説明
map	object	削除対象のマップ
key	string	マップから削除するために指定されたキーを表す文字列

戻り値の型は object です。mapから指定したkeyの項目を削除した連想配列を返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      target: {"key1": "hello", "key2": "world", "key3": "!"}
  delete:
    return: ${map.delete(target, 'key3')}
    #return {"key1": "hello", "key2": "world"}

map.get関数

連想配列から指定したキーの項目を取得します。構文は次のようになります。

map.get(<map>, <key>)

引数	型	説明
map	object	検索するマップ
key	string	検索に使用される文字列または文字列のリスト。リストが指定された場合、関数はキーのリストを使って繰り返し呼び出される

戻り値の型は any です。mapから指定したkeyの項目を返します。mapに指定したkeyが存在しない場合は null を返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      target: {"key1": "hello", "key2": "world", "key3": "!"}
  get:
    return: ${map.get(target, 'key2')}
    # return "world"

map.put関数

連想配列に、指定したキーの項目を指定した値で追加、あるいはキーが存在する場合は更新します。構文は次のようになります。

map.put(<map>, <key>, <value>)

引数	型	説明
map	object	追加、更新されるマップ
key	string	追加、更新される項目のキー
value	any	追加、更新される項目の値

戻り値の型は object です。指定したkeyの項目を追加・更新したmapを返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      target: {"key1": "hello", "key2": "world", "key3": "!"}
  put:
    return: ${map.put(target, 'key1', 'the')}
    # return {"key1": "the", "key2": "world", "key3": "!"}

map.merge関数

連想配列に別の連想配列の項目を追加します。キーが重複する場合は、追加する連想配列の項目に置き換えます。構文は次のようになります。

map.merge(<map1>, <map2>)

引数	型	説明
map1	object	結合されるマップ
map2	object	結合するマップ

戻り値の型は object です。map1にmap2を結合して返します。同じキーがある場合、最初のマップの値は2番目のマップの値で置き換えられます。

例えば、map1が {key1: value1} で、map2が {key1: value2} の場合、戻り値は {key1: value2} になります。

記述例は以下のようになります。

steps:
  set:
    assign:
      target1: {"key1": "hello", "key2": "world", "key3": "!"}
      target2: {"key2": "hello", "key5": "world"}
  merge:
    return: ${map.merge(target1, target2)}
    # return {"key1": "hello", "key2": "hello", "key3": "!", "key5": "world"}

map.mergeNested関数

連想配列に別の連想配列の項目を再帰的に追加します。キーが重複する場合は、追加する連想配列の項目に置き換えます。構文は次のようになります。

map.mergeNested(<map1>, <map2>)

引数	型	説明
map1	object	結合されるマップ
map2	object	結合するマップ

戻り値の型は object です。map1にmap2を結合して返します。ネストされたマップがあれば再帰的にマージされます。

例えば、map1が {key1: {keyx: valuex}} で、map2が {key1: {keyy: valuey}} の場合、key1 の値がマップなので再起的に {keyx: valuex} と {keyy: valuey} がマージされ、戻り値は {key1: {keyx: valuex, keyy: valuey}} になります。

記述例は以下のようになります。

steps:
  set:
    assign:
      target1: {"key1": {"key2": "hello"}}
      target2: {"key1": {"key3": "world"}}
  mergeNested:
    return: ${map.mergeNested(target1, target2)}
    # return {"key1": {"key2": "hello", "key3": "world"}}

mathグループ

mathグループの式内関数では数値計算を行います。

math.ceil関数

小数点以下を切り上げます。構文は次のようになります。

math.ceil(<x>)

引数	型
x	number

戻り値の型は number です。小数点以下を切り上げた数値を返します。

記述例は以下のようになります。

steps:
  ceil:
    return: ${math.ceil(1.1)}
    # return 2

math.randint関数

指定された範囲内でランダムな整数値を出力します。構文は次のようになります。

math.randint(<x>, <y>)

引数	型
x	number
y	number

戻り値の型は number です。xからyまでのランダムな整数値を返します。

記述例は以下のようになります。

steps:
  randint:
    return: ${math.randint(1, 10)}
    # return 1から10までのランダムな整数値

math.sqrt関数

平方根を出力します。構文は次のようになります。

math.sqrt(<x>)

引数	型
x	number

戻り値の型は number です。√xの値を返します。

記述例は以下のようになります。

steps:
  sqrt:
    return: ${math.sqrt(2)}
    # return 1.4142135623730951

math.abs関数

絶対値を出力します。構文は次のようになります。

math.abs(<x>)

引数	型
x	number

戻り値の型は number です。xの絶対値を返します。

記述例は以下のようになります。

steps:
  abs:
    return: ${math.abs(-2)}
    # return 2

math.max関数

2つの数値を比較して大きい方を出力します。構文は次のようになります。

math.max(<x>, <y>)

引数	型
x	number
y	number

戻り値の型は number です。xとyを比較して大きい方の値を返します。

記述例は以下のようになります。

steps:
  max:
    return: ${math.max(2, -2)}
    # return 2

math.min関数

2つの数値を比較して小さい方を出力します。構文は次のようになります。

math.min(<x>, <y>)

引数	型
x	number
y	number

戻り値の型は number です。xとyを比較して小さい方の値を返します。

記述例は以下のようになります。

steps:
  min:
    return: ${math.min(2, -2)}
    # return -2

testグループ

testグループの式内関数は、テストの実行回数や特定の条件が満たされた回数をカウントするために使用します。

test.count関数

変数への代入に呼ばれるたびに、内部的なカウンターの値をインクリメントします。構文は次のようになります。

test.count()

記述例は以下のようになります。

steps:
  loop:
    for:
      in: '${array.range(10)}'
      as: i
      steps:
        add:
          assign:
            _: ${test.count()}
  countResult:
    return: ${test.count()}
    # return 10

test.resetCount関数

カウンターの値をリセットします。構文は次のようになります。

test.resetCount()

記述例は以下のようになります。

steps:
  loop:
    for:
      in: '${array.range(10)}'
      as: i
      steps:
        add:
          assign:
            _: ${test.count()} # カウンターをインクリメント
  resetResult:
    return: ${test.resetCount()} # カウンターの値を参照
    # return 0

textグループ

textグループの式内関数では、文字列を操作します。

ヒント

文字列の文字セットを指定する関数では、例えば「UTF-8」「US-ASCII」「ISO-8859-2」などが使用できます。なお、文字セットを表す文字列の大文字と小文字は区別しません。

参考

正規表現を使用する関数について、正規表現は「RE2構文」を参照してください。

text.decode関数

指定された文字セットを使用して、与えられたバイト列を文字列にデコードします。構文は次のようになります。

text.decode(<data>, <charset?>)

ヒント

指定された文字セットで正しくデコードできない各バイトは、置換文字「�」（UnicodeのU+FFFD）で表現されます。

引数	型	説明
data	bytes	デコードする入力データ（バイト列）
charset	string	デコードに使用する文字セット。デフォルトは「UTF-8」

戻り値の型は string です。デコードされた文字列を返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      sample: ${"Hello World"}
  decode:
    return: ${text.decode(text.encode(sample, "utf-8"))}
    # return "Hello World"

text.encode関数

指定された文字セットを使用して、与えられたテキストをバイト列にエンコードします。構文は次のようになります。

text.encode(<data>, <charset?>)

引数	型	説明
data	string	エンコードする入力テキスト
charset	string	エンコードに使用する文字セット。デフォルトは「UTF-8」

戻り値の型は bytes です。エンコードされたバイト列を返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      sample: ${"Hello World"}
  encode:
    return: ${text.encode(sample, "utf-8")}
    # return [72,101,108,108,111,32,87,111,114,108,100]

text.findAll関数

指定した文字列について、指定した部分文字列が出現するすべてのインデックスを検索します。文字列はコードポイントを基準にインデックス付けされ、ゼロから始まるインデックスが使われます。検索は左から右に進み、重複するマッチは検索されません。構文は次のようになります。

text.findAll(<source>, <substr>)

引数	型	説明
source	string	検索対象の文字列
substr	string	検索する部分文字列

戻り値の型は array です。source中に部分文字列substrが見つかったときに、そのインデックスをソートしたリストを返します。一致する文字列が見つからなかった場合は、空のリストを返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      sample: ${"Hello World"}
  findAll:
    return: ${text.findAll(sample, "l")}
    # return [2, 3, 9]

text.findAllRegex関数

指定した文字列について、指定した正規表現に一致するすべての部分を検索します。一致するすべての部分がリストとして返されます。各一致は、マッチした部分文字列の開始インデックス（ゼロベース）と部分文字列自体を含むマップです。重複する一致がある場合、左端の一致のみが考慮されます。重複する一致が同じインデックスで始まる場合は、最長の一致が考慮されます。構文は次のようになります。

text.findAllRegex(<source>, <regex>)

引数	型	説明
source	string	検索対象の文字列
regex	string	検索する正規表現

戻り値の型は array です。regexに一致する部分文字列がsource中に見つかったときに、そのインデックスをキーとし、一致した部分文字列を値とするマップのリストを返します。リストはインデックス順にソートされます。一致する文字列が見つからなかった場合は、空のリストを返します。

。各マップは、キー index （部分文字列の開始インデックス）と match （一致した部分文字列）を持ちます。

記述例は以下のようになります。

steps:
  set:
    assign:
      sample: ${"Hello World"}
  findAllRegex:
    return: ${text.findAllRegex(sample, "o|l")}
    # return [{"index": 2, "match": "l"}, {"index": 3, "match": "l"}, {"index": 4, "match": "o"}, {"index": 7, "match": "o"}, {"index": 9, "match": "l"}]

text.matchRegex関数

指定した文字列について、指定した正規表現に一致する部分があるかどうかを真偽値で返します。構文は次のようになります。

text.matchRegex(<source>, <regex>)

引数	型	説明
source	string	検索対象の文字列
regex	string	検索する正規表現

戻り値の型は boolean です。regexに一致する部分文字列がsource中に見つかったときには true を、そうでない場合は false を返します

記述例は以下のようになります。

steps:
  set:
    assign:
      sample: ${"Hello World"}
  matchRegex:
    return: ${text.matchRegex(sample, "Help|World")}
    # return true

text.replaceAll関数

指定した文字列について、指定した部分文字列をすべて新しい文字列に置き換えます。構文は次のようになります。

text.replaceAll(<source>, <substr>, <repl>)

引数	型	説明
source	string	置き換えるもとの文字列
substr	string	置き換え対象となる部分文字列
repl	string	置き換え後の文字列

戻り値の型は string です。source内の部分文字列substrをすべてreplに置き換えた文字列を返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      sample: ${"Hello World"}
  replaceAll:
    return: ${text.replaceAll(sample, "Hello", "The")}
    # return "The World"

text.replaceAllRegex関数

指定した文字列について、指定した正規表現に一致するすべての部分文字列を新しい文字列に置き換えます。構文は次のようになります。

text.replaceAllRegex(<source>, <regex>, <repl>)

引数	型	説明
source	string	置き換えるもとの文字列
regex	string	置き換え対象となる正規表現
repl	string	置き換え後の文字列

戻り値の型は string です。source内のregexに一致する部分文字列をすべてrepl に置き換えた文字列を返します。

記述例は以下のようになります。

steps:
  set:
    assign:
      sample: ${"Hello World"}
  replaceAllRegex:
    return: ${text.replaceAllRegex(sample, "Hello|World", "The")}
    # return "The The"

text.split関数

指定した文字列について、指定した区切り文字で分割します。構文は次のようになります。

text.split(<source>, <separator>)

引数	型	説明
source	string	分割する文字列
separator	string	区切り文字

戻り値の型は array です。指定したseparatorを使ってsourceを分割し、文字列のリストとして返します。

記述例は以下のようになります。

steps:
  split:
    return: ${text.split("abc", "a")}
    # return ["", "bc"]

text.substring関数

指定した文字列について、開始インデックスと終了インデックスの間の部分文字列を抽出します。構文は次のようになります。

text.substring(<source>, <start>, <end>)

引数	型	説明
source	string	部分文字列を抽出するもとの文字列
start	number	部分文字列の開始インデックス
end	number	部分文字列の終了インデックス

戻り値の型は string です。sourceから指定されたstartとendの間の部分文字列を返します。

記述例は以下のようになります。

steps:
  substring:
    return: ${text.substring("Hello World", 0, 5)}
    # return "Hello"

text.toLower関数

指定した文字列をすべて小文字に変換します。構文は次のようになります。

text.toLower(<source>)

引数	型	説明
source	string	変換する文字列

戻り値の型は string です。sourceをすべて小文字にして返します。

記述例は以下のようになります。

steps:
  toLower:
    return: ${text.toLower("Hello World")}
    # return "hello world"

text.toUpper関数

指定した文字列をすべて大文字に変換します。構文は次のようになります。

text.toUpper(<source>)

引数	型	説明
source	string	変換する文字列

戻り値の型は string です。sourceをすべて大文字にして返します。

記述例は以下のようになります。

steps:
  toUpper:
    return: ${text.toUpper("Hello World")}
    # return "HELLO WORLD"

text.urlDecode関数

指定した文字列がURLエンコードされているとみなしてデコードします。プラス（+）は空白文字に変換し、URLエンコードされた文字（%xx）を対応するUTF-8文字に変換します。構文は次のようになります。

text.urlDecode(<source>)

引数	型	説明
source	string	URLエンコードされた文字列

戻り値の型は string です。URLエンコードされたsourceについてもとのURLを返します。

記述例は以下のようになります。

steps:
  urlDecode:
    return: ${text.urlDecode("a%2Fb%2Fc%3Fitem%3Dd%2Be%20f")}
    # return "a/b/c?item=d+e f"

text.urlEncode関数

指定した文字列をURLエンコードします。空白文字は %20 に変換します。構文は次のようになります。

text.urlEncode(<source>)

引数	型	説明
source	string	URLエンコードする文字列

戻り値の型は string です。sourceをパーセント（%）でエンコードした文字列を返します。

記述例は以下のようになります。

steps:
  urlEncode:
    return: ${text.urlEncode("a/b/c?item=d+e f")}
    # return "a%2Fb%2Fc%3Fitem%3Dd%2Be%20f"

text.urlEncodePlus関数

指定された文字列をURLエンコードします。空白文字はプラス（+）に変換します。構文は次のようになります。

text.urlEncodePlus(<source>)

引数	型	説明
source	string	URLエンコードする文字列

戻り値の型は string です。sourceをパーセント（%）でエンコードし、空白をプラス（+）に変換した文字列を返します。

記述例は以下のようになります。

steps:
  urlEncodePlus:
    return: ${text.urlEncodePlus("a/b/c?item=d+e f")}
    # return "a%2Fb%2Fc%3Fitem%3Dd%2Be+f"

timeグループ

timeグループの式内関数では時間（タイムスタンプ）を扱います。

ヒント

タイムスタンプの表現は、UNIX時間（1970年1月1日0時0分0秒UTCからの経過秒数）による数値か、RFC 3339セクション5.6（ISO 8601のサブセット）形式（例えば「2024-01-10T16:15:54.615087Z」など）互換の日時文字列です。マイクロ秒の精度まで扱えます。

time.format関数

指定したUNX時間のタイムスタンプを、指定したタイムゾーンで日時文字列にフォーマットします。構文は次のようになります。

time.format(<seconds>, <timezone?>)

引数	型	説明
seconds	number	UNIX時間によるタイムスタンプ
timezone	string	タイムゾーン。デフォルトは「UTC」

ヒント

タイムゾーンとしては、TZデータベース のゾーン名（Asia/Tokyoなど）を指定します。

戻り値の型は string です。secondsをUNIX時間として、timezoneのタイムゾーンで日時文字列に変換して返します。

steps:
  format:
    return: ${time.format(1734425022, "Asia/Tokyo")}
    # return "2024-12-17T17:43:42.000+09:00"

time.parse関数

RFC 3339互換の日時文字列を、UNIX時間に変換します。構文は次のようになります。

time.parse(<value>)

引数	型	説明
value	string	日時文字列

戻り値の型は number です。valueを日時文字列として、UNIX時間の浮動小数点数に変換して返します。

記述例は以下のようになります。

steps:
  parse:
    return: ${time.parse("2024-12-17T17:43:42.300+09:00")}
    # return 1734425022.3

time.now関数

現在の日時をUNIX時間で返します。構文は次のようになります。

time.now()

戻り値の型は number です。浮動小数点数で返します。

記述例は以下のようになります。

steps:
  now:
    return: ${time.now()}
    # return 1734425022.315

関数を組み合わせて日時文字列を返すこともできます。

steps:
  now:
    return: ${time.format(time.now(), "Asia/Tokyo"}
    # return "2024-12-17T17:43:42.315+09:00"

uuidグループ

uuidグループの式内関数は、UUID（Universally Unique Identifier：汎用一意識別子）を生成します。

uuid.v7関数

バージョン7形式のUUIDを生成します。構文は次のようになります。

uuid.v7()

戻り値の型は string です。ランダムに生成したUUIDを文字列による形式で返します。

記述例は以下のようになります。

steps:
  v7:
    return: ${uuid.v7()}
    # return 550e8400-e29b-41d4-a716-446655440000

uuid.nil関数

全てのビットが0のUUIDを返します。構文は次のようになります。

uuid.nil()

戻り値の型は string です。文字列「00000000-0000-0000-0000-000000000000」を返します。

記述例は以下のようになります。

steps:
  nil:
    return: ${uuid.nil()}
    # return 00000000-0000-0000-0000-000000000000