Runbook 構文リファレンス

[更新: 2026年04月20日]

ワークフローを定義するRunbookの構文を説明します。RunbookはYAMLで記述します。

Runbookを構成する要素 

Runbook（ワークフローを定義するYAMLファイル）のルート階層には、次の3つの要素を記述します。

要素	説明
meta	ワークフローのメタ情報
args	ワークフローの引数
steps	ワークフローの各ステップで、上から順に実行される

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

meta:
  description: 説明文

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

steps:
  ...

以降で順に説明します。

meta 

meta ではワークフローのメタ情報として、内容の説明を description で簡潔に記述します。

meta:
  description: 説明文

ヒント

metaは必須ではありませんが、入力を推奨します。

args 

args ではワークフローの実行時に渡される引数を、次の構文で定義します。

args:
  <引数名>:
    type: <型>
    default: デフォルト値
    description: 引数の説明

それぞれの引数は、type・default・description の3項目で構成されます。

項目	説明
type	引数の型を指定する
default	ワークフロー実行時に引数として渡されなかった場合に使用されるデフォルト値
description	引数の説明を記述する

引数の型は、次のいずれかを指定できます。

型	説明
string	文字列
number	数字
boolean	真偽値
object	オブジェクト（連想配列）
array	配列
null	値なし

渡された引数は、ワークフローのsteps内で、後述する式の形（${args.XXXXX}）で参照できます。

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

meta:
  description: 渡された文字列をそのまま出力するワークフロー

args:
  target:
    type: string
    default: 文字列が入力されませんでした。
    description: 任意の文字列

steps:
  done:
    return: ${args.target}

ここでは「target」という名前の引数に、文字列が渡されます。

ヒント

ワークフローの引数は、コントロールパネルで実行する場合は「実行開始画面」の「引数」欄で、APIから実行する場合はリクエストボディのargsで渡すことができます。

参考

コントロールパネルの「実行開始画面」についてはマニュアルの「実行開始画面でワークフローを実行」を参照してください。APIの詳細は、APIポータルの「Workflows API」を参照してください。

steps 

steps では、ワークフローで実行される各ステップを順に記述します。構文は次のようになります。

steps:
  <ステップ名1>:
    1つ目のステップ
  <ステップ名2>:
    2つ目のステップ

実行それぞれにステップ名を付けます。ステップ名は、1つのワークフロー内で一意である必要があります。

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

meta:
  description: 「sample message」という文字列を表示するワークフロー
steps:
  step1: #ステップ名
    assign:
      target: ${"sample message"}
  done: #ステップ名
    return: ${target}

この「step1」や「done」がステップ名です。ラベルとしてシンプルで分かりやすい名前を付けるとよいでしょう。

各ステップでassignとreturnが実行されます。それぞれの動作は、この後の「stepsに記述できるステップの種類」で説明します。

注意

ステップ名として「return」と「end」は使用できません。

式 

ワークフローの中では、次のような場合に式を利用して値の参照や演算などができます。

assignで変数に値を代入する
returnで値を返す
式内関数

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

${ ... }

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

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

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

参考

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

ECMAScript parsing infrastructure for multipurpose analysis

stepsに記述できるステップの種類 

steps では、ワークフローで実行される処理定義を記述します。記述できるステップの種類には、何らかの処理を行うものや、実行順序を制御するものがあります。

以下では、何らかの処理を行います。

assign
call

以下は処理の区切りや終端で意味を持ちます。

return
next

以下は実行順序を制御します。

switch
for
parallel
try - except

assign 

assign では、指定された変数に指定された値を代入します。構文は次のようになります。

steps:
  <ステップ名>:
    assign:
      <変数1>: <値1>
      <変数2>: <値2> #一度に複数を指定可能
      ...

次の記述例では「target」に "sample message" を、「my_list」に ["zero", "one", "two"] を代入します。

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

call 

call は外部関数を呼び出します。構文は次のようになります。

steps:
  <ステップ名>:
    call: <呼び出す外部関数名>
    args:
      <引数名>: <渡す値>
    result: <変数名>

このように外部関数の呼び出しは、callに加えて args と result という3項目の兄弟要素で記述します。

項目	説明
call	呼び出す外部関数名を指定する
args	外部関数に渡す引数を、上記assignの各変数と同様な形式で指定する
result	外部関数からの戻り値を格納する変数名を指定する

参考

呼び出すことができる外部関数の詳細は、マニュアルの「callリファレンス」を参照してください。

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

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

ヒント

外部関数からの戻り値は「実行詳細画面」の「ステップのログ一覧」に表示されます。100文字を超えると省略されます。

参考

「実行詳細画面」については、マニュアルの「実行詳細画面を操作する」を参照してください。

return 

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

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

meta:
  description: returnの使用例
steps:
  step1:
    assign:
      value: ${1}
  done:
    return: ${value}

next 

next は各ステップの末尾に記述し、次に実行する任意のステップ名を指定します。nextを指定しなければ、ステップの実行順はstepsの記述順に従います。

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

meta:
  description: nextの使用例
steps:
  step1:
    assign:
      value: ${1}
    next: done // 直下にあるstep2ではなく、最後のdoneを次に実行する
  step2:
    assign:
      value: ${2}
  done:
    return: ${value}

switch 

switch は実行順序を制御するステップの1つで、条件分岐を行います。構文は次のようになります。

steps:
  <ステップ名>:
    switch:
      - condition: ${<条件式1>} #条件式1の評価が真なら以降が実行される
        steps: # もしくはnextあるいはretuenを記述できる
          <ステップ名>:
            ...: #条件式1が真のときに実行されるステップを記述
          ...
      - condition: ${<条件式2>} #条件式2の評価が真なら以降が実行される
        ...... # 条件式2が真のときに実行される

このようにswitchでは、条件式（condition）と実行内容の組みをいくつか並べた配列（リスト）の形をしています。複数のconditionが真だった場合には、上から評価して最初に真となった条件が実行されます。

実行する項目としては、stepsでステップを記述できるほか、nextかreturnのいずれか1つを記述できます。

項目	説明
steps	条件が真の場合に実行するステップを記述する
next	条件が真の場合には、指定したステップ名からを次に実行する
return	条件が真ならばワークフローを終了し、指定された値を結果として返す

このうちstepsを実行する記述例は以下のようになります。

meta:
  description: switchを使った条件分岐の例
steps:
  default:
    assign:
      result: null
  step1:
    switch:
      - condition: ${false} # 条件式の評価が偽なので実行されない
        steps:
          a: # ステップ名
            assign:
              result: ${"invisible message"}
      - condition: ${true} # 条件式の評価が真なので実行される
        steps:
          b: # ステップ名
            assign:
              result: ${"visible message"}
  step2: # switchに続けて実行されるステップ
    return: ${result}

またnextやreturnを実行する記述例は以下のようになります。

meta:
  description: switchでnextやreturnの使用例
steps:
  default: # 最初に実行されるステップ
    assign:
      result: ${"default message"}
  step1: # 次に実行されるステップ
    switch:
      - condition: ${false} # 条件式を評価するとfalseなので実行されない
        return: ${"returned message"} # ワークフローを終了し、結果として返す値
      - condition: ${true} # 条件式を評価するとtrueなので実行される
        next: done # 次にステップ名「done」のステップを実行する
  unreachable: # このステップが実行されることはない
    assign:
      result: ${"unreachable step"}
  done: # switchの中の条件項目でnextにより指定される
    return: ${result}

ここでは「step1」のswitchに2つの分岐項目がありますが、評価して真になる ${true} の分岐ステップが実行され、nextで指定された「done」に処理が移ります。

for 

for も実行順序を制御するステップの1つで、指定されたステップを繰り返し実行します。構文は次のようになります。

steps:
  <ステップ名>:
    for:
      in: [<ループ対象>]
      as: <ループ変数>
      steps:
        <ステップ名>:
          ...

このようにforでは in・as・steps という3項目の子要素を記述します。

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

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

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

これは、1から3までの和が返されます。

parallel 

Workflowsのワークフローでは並行処理が可能です。分岐（ブランチ）と繰り返し（イテレーション）の2種類があります。それぞれ形式が異なりますが、共通する子要素が2項目あります。これらは省略可能です。

項目	説明
shared	共有する変数名のリストで、各並列ステップから読み取り専用でアクセスできる
concurrencyLimit	並行処理の最大数

並行処理の戻り値は、それぞれ各ブランチまたはイテレーションで「result」変数に設定した値が、親スレッドの「results」配列に自動的に収集されます。n番目の結果は results[n-1] に格納されます（配列のインデックスは0から始まります）。

分岐による並行処理

指定された複数のブランチを並行して実行します。構文は次のようになります。

steps:
  <ステップ名>:
    parallel:
      shared: # 並列実行する各ブランチで共有する変数とその値の組み
        <変数>: ${<値>}
        ......
      concurrencyLimit: <並列数> # 並行処理の最大数
      branches:
        - <ブランチA>: # ブランチ名
            ...... # ブランチAで実行するステップ
        - <ブランチB>: # ブランチ名
            ...... # ブランチBで実行するステップ

このように分岐（ブランチ）による並行処理では、子要素として上記2つのほか branches を記述します。

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

meta:
  description: parallel branchを使った並行処理の例
steps:
  step1:
    parallel:
      branches:
        - getUserCall: # ブランチ名
            call: http.get
            args:
              url: ${"https://example.com"}
            result: response
          setResult: # ブランチ中のステップ名
            assign:
              result: ${"user(" + response.statusCode + ")"}
        - getPassCall: # ブランチ名
            call: http.get
            args:
              url: ${"https://example.com"}
            result: response
          setResult: # ブランチ中のステップ名
            assign:
              result: ${"pass(" + response.statusCode + ")"}
  done:
    return: ${results} # 自動的に収集された結果の配列

繰り返しによる並行処理

まとまった量のデータを分散して処理するステップです。構文は次のようになります。

steps:
  <ステップ名>:
    parallel:
      shared: # 並列実行する各ブランチで共有する変数とその値の組み
        <変数>: ${<値>}
        ......
      concurrencyLimit: <並列数> # 並行処理の最大数
      in: [1, 2, 3, 4]
      as: i
      steps:
        ...... # 繰り返しのステップ

並行処理に共有する子要素のほか、先ほどのforと同じ子要素で繰り返し（イテレーション）を記述します。

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

meta:
  description: parallel iterationを使った並行処理の例
steps:
  step1:
    parallel:
      concurrencyLimit: 2
      in: [1, 2, 3, 4]
      as: i
      steps:
        a: #ステップ名
          call: http.get
          args:
            url: ${"https://example.com"}
          result: response
        b: #ステップ名
          assign:
            result: ${i + "(" + response.statusCode + ")"}
  done:
    return: ${results} # 自動的に収集された結果の配列

try-except 

実行中にエラーが起きた場合に、そのエラーを処理するフローを記述できます。これは try 節と excapt 節の2つの項目から成り立ちます。

steps:
  <ステップ名>:
    try:
      ...... # エラーが発生しうるステップ
    except:
      as: <変数名>
      return: ${<値>} # あるいはstepsでステップを記述

このようにエラーが発生しうるステップをtry節に記述します。このようなtry節があれば、エラーが発生した場合にexcapt節の処理が実行されます。excapt節では、エラーを格納する変数名をasで指定し、エラーに対応する処理をステップで記述します。

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

meta:
  description: try-exceptの使用例
steps:
  tryStep:
    try:
      assign:
        response: ${json.decode('string')}
    except:
      as: error
      return: ${error.message}
  done:
    return: ${response}

ヒント

try節がない箇所でエラーが発生すると、ワークフローは停止します。