構文リファレンス

[更新: 2025年7月17日]

Workflow の定義を行うファイルの仕様について記載します。

ファイルのルートには以下のような構文を記述します。

meta … Workflow のメタ情報
args … Workflow の引数
steps … Workflow の各ステップ。上から順に実行されます。

meta:
  description: 説明文

args:
  target:
    type: string
    description: データの説明

steps:
  ...

meta

Workflow のメタ情報を記述します。
この Workflow の内容を簡潔に説明するために記述します。

引数	説明
`description`	`string` Workflow の説明文を記述します

meta:
  description: 説明文

注釈

このフィールドは必須ではありませんが、入力を推奨します。

args

ワークフロー実行時に渡す引数の定義を記述します。
ここで定義された引数は、ワークフローの実行時にリクエストボディのargsで渡すことができます。
渡された引数は、ワークフローのsteps内で ${args.XXXXX} の形参照することができます。

引数	説明
type	引数の型を指定します。型は以下のいずれかを指定できます。・string ・number ・boolean ・object ・array ・null
description	引数の説明を記述します。

args:
  target:
    type: string
    description: データの説明
steps:
  done:
    return: ${args.target}

steps

ワークフローの各ステップを記述します。

例

steps:
  a: #ステップ名
    assign:
      target: ${"sample message"}
  b: #ステップ名
    return: ${target}

注釈

ステップ名は、ワークフロー内で一意である必要があります。また、returnとendはステップ名として使用できません。

式

変数への値の代入(assign step)や、return句、値の参照、式内関数などで式を利用できます。

例

${args.XXXX}
${userName + "さん"}
${math.abs(-2)}

現時点で、式の解釈、値の型は、構文解析と処理に esprima に依存しているのでそれに準じます。

return

return はワークフローを即時終了し、指定した値を出力として返します。 steps の末尾に記述します。

meta:
  description: returnを使った例
steps:
  step1:
    assign:
      value: ${1}
  step2:
    return: ${value}

next

next は、ワークフローの次のステップを指定します。各 step の末尾に記述します。
next を指定しない場合、次のステップは、 steps の順番に従います。

meta:
  description: nextを使った例
steps:
  step1:
    assign:
      value: ${1}
    next: step3
  step2:
    assign:
      value: ${2}
  step3:
    return: ${value}

assign

指定された値を変数に代入するステップです。
例では、 target に "sample message" 、 my_list に ["zero", "one", "two"] を代入しています。

引数	説明
`assign`	代入する変数名とその値のリストを指定します。

meta:
  description: assignを使った例
steps:
  step:
    assign:
      target: ${"sample message"}
      my_list: ["zero","one","two"] #複数可

call

外部関数などを呼び出すステップです。

引数	説明
`call`	呼び出す関数名を指定します。 callリファレンスを参照してください。
`args`	関数に渡す引数を指定します。引数名に関しても上記リファレンスを参照してください。
`result`	関数の戻り値を格納する変数名を指定します。

meta:
  description: callを使った例
steps:
  step:
    call: http.get #関数名
    args:
      url: ${"https://example.com"} #引数
    result: response
  res:
    return: ${response}

switch

条件分岐を行うステップです。

引数	説明
switch	条件分岐の条件と、それに対するステップのリスト
condition	条件分岐の条件を記述します
steps	条件分岐の条件が真の場合に実行するステップのリスト
next	条件分岐の条件が真の場合に次に実行するステップの名前
return	条件分岐の条件が真の場合にワークフローを終了し結果として返す値

複数のconditionが真だった場合、最初に見つかったものが実行されます steps, next , return のどれか一方を指定することができます。

meta:
  description: switchを使った条件分岐の例
steps:
  default:
    assign:
      result: null
  step:
    switch:
      - condition: ${false} #条件式
        steps:
          a: #ステップ名
            assign:
              result: ${"invisible message"}
      - condition: ${true} #条件式
        steps:
          b: #ステップ名
            assign:
              result: ${"visible message"}
  done:
    return: ${result}

meta:
  description: switchでnextやreturnを使った例
steps:
  default:
    assign:
      result: ${"default message"}
  step:
    switch:
      - condition: ${false} #条件式
        return: ${"returned message"} #ワークフローを終了し、結果として返す値(今回falseなので実行されない)
      - condition: ${true} #条件式
        next: done #次に実行するステップの名前(今回trueなので実行される)
  unreachable:
    assign:
      result: ${"unreachable step"}
  done:
    return: ${result}

for

指定されたステップを繰り返し実行します。

引数	説明
in	要素を繰り返す対象の配列
as	要素を格納する変数名
steps	繰り返し実行するステップのリスト

meta:
  description: forを使った繰り返しの例
steps:
  default:
    assign:
      target: 0
  step:
    for:
      in: [1, 2, 3] #ループ対象
      as: i #ループ変数
      steps:
        a:
          assign:
            target: ${target+1}
  done:
    return: ${target}

parallel

並行処理は、分岐と繰り返しの 2 つの形式があります。

parallel branch

指定されたステップを並行して実行します。

引数	説明
shared	共有する変数名のリスト。各ステップで共有され結果を書き込むのに使用します。
concurrencyLimit	並行処理の最大数
branches	各ブランチのステップのリスト

meta:
  description: parallel branchを使った並行処理の例
steps:
  default:
    assign:
      result: []
  step:
    parallel:
      shared: [result]
      branches:
        - getUserCall:
            call: http.get
            args:
              url: ${"https://example.com"}
            result: response
          push:
            assign:
              _: ${array.push(result, "user(" + response.statusCode + ")")} # 配列に結果を追加
        - getPassCall:
            call: http.get
            args:
              url: ${"https://example.com"}
            result: response
          push:
            assign:
              _: ${array.push(result, "pass(" +response.statusCode + ")")} # 配列に結果を追加
  done:
    return: ${result}

parallel iteration

まとまった量のデータを分散して処理するステップです。

引数	説明
shared	共有する変数名のリスト。各ステップで共有され結果を書き込むのに使用します。
concurrencyLimit	並行処理の最大数
in	要素を繰り返す対象の配列
as	要素を格納する変数名
steps	各分岐イテレーションで実行するステップのリスト

meta:
  description: parallel iterationを使った並行処理の例
steps:
  default:
    assign:
      result: []
  step:
    parallel:
      shared: [result]
      concurrencyLimit: 2
      in: [1, 2, 3, 4]
      as: i
      steps:
        a:
          call: http.get
          args:
            url: ${"https://example.com"}
          result: response
        b:
          assign:
            _: ${array.push(result, i +"("+ response.statusCode +")")} # 配列に結果を追加
  done:
    return: ${result}

try-except

実行中にエラーが起きた場合、そのエラーを処理するフローを記述できます。

引数	説明
try	実行中にエラーが発生しうる Step です。 call や steps などを記述できます
except	try でエラーが発生した場合の処理を記述します。 as でエラーを格納する変数名を指定できます。steps でエラーが発生した場合の処理を記述します。

try 節で囲まれていない箇所でエラーが発生した場合、Workflow は停止します。

meta:
  description: try-exceptを使った例
steps:
  tryStep:
    try:
      call: http.get
      args:
        url: ${"https://example.com"}
        timeout: 0 # 意図してタイムアウトエラーを発生させる
      result: response
    except:
      assign:
        response: ${"error"}
  done:
    return: ${response}