ステップモジュールオプション

ステップ設定画面。フォーム/YAMLの切替、実行条件・ループ・エラー処理の設定、入出力データの確認ができます

概要

Jinba Flowの各ステップは、実行のタイミングと方法を制御する高度なオプションで設定できます。これらのオプションにより、条件分岐、ループ、複雑な依存関係を持つ洗練されたワークフローを作成できます。

ステップの依存関係（needs）

needsオプションは、現在のステップが実行される前に完了する必要があるステップを指定します。これにより実行順序が作成され、必要なときにデータが利用可能になります。

基本的な使い方

fetch_dataとvalidate_inputは、フロー内の前のステップを表します。fetch_dataの結果はリストであることを想定しています。

- id: analyze_data
  tool: PYTHON_SANDBOX_RUN
  needs:
    - fetch_data
    - validate_input
  input:
    - name: code
      value: |
        import json
        data = json.loads(r'''{{steps.fetch_data.result}}''')
        len(data)
    - name: data_type
      value: NUMBER

重要なポイント

実行順序: 実行順序はneedsだけで決まります。{{steps.X...}}を参照してもXの完了を待つわけではないため、出力を読むステップはすべて指定してください
並列実行: 互いに依存しないステップは並列で実行されることがあります
失敗の処理: 依存先のステップが失敗またはキャンセルされると、このステップはキャンセルされ、これに依存するステップもキャンセルされます。依存先がすべてスキップされた場合、このステップもスキップされます。スキップされた依存先があっても、成功した依存先が1つあれば実行されます。whenを設定したステップはこのルールに従わず、条件で判断します（後述）
forEachへの依存: forEachステップは、成功したアイテムが1つでもあるか、アイテムが0件なら成功として扱われます。成功したアイテムがなく、失敗またはキャンセルされたアイテムがあれば失敗として扱われます
ダイヤモンドパターン: 複雑な依存関係グラフがサポートされています（A→B, A→C, B→D, C→D）

例：マルチブランチワークフロー

- id: input_data
  tool: INPUT_JSON
  input:
    - name: value
      value: "[1, 2, 3, 4, 5]"

- id: process_even
  tool: PYTHON_SANDBOX_RUN
  needs:
    - input_data
  input:
    - name: code
      value: |
        import json
        data = json.loads(r'''{{steps.input_data.result}}''')
        json.dumps([x for x in data if x % 2 == 0])
    - name: data_type
      value: OBJECT

- id: process_odd
  tool: PYTHON_SANDBOX_RUN
  needs:
    - input_data
  input:
    - name: code
      value: |
        import json
        data = json.loads(r'''{{steps.input_data.result}}''')
        json.dumps([x for x in data if x % 2 != 0])
    - name: data_type
      value: OBJECT

- id: combine_results
  tool: PYTHON_SANDBOX_RUN
  needs:
    - process_even
    - process_odd
  input:
    - name: code
      value: |
        import json
        even = json.loads(r'''{{steps.process_even.result.data}}''')
        odd = json.loads(r'''{{steps.process_odd.result.data}}''')
        json.dumps({"even": even, "odd": odd})
    - name: data_type
      value: OBJECT

PYTHON_SANDBOX_RUNは最後の行の値を結果とし、result.dataに格納します。data_type: OBJECTの場合、最後のjson.dumps(...)が構造化データとして返されます。結果をjson.loads(r'''...''')で読み取ると、JSON（null、true、false）をPythonコードにそのまま埋め込んだときのエラーを避けられます。

条件付き実行（when）

whenオプションを使用すると、指定した条件がtrueの場合にのみステップを実行できます。これにより、前のステップの結果に基づいた動的なワークフロー動作が可能になります。

基本構文

- id: conditional_step
  tool: TOOL_NAME
  when: "<条件式>"
  input:
    - name: param
      value: "value"

条件式

条件はCEL式で、{{ }}を使わずに直接書きます：

文字列比較: steps.check.result.status == 'success'
数値比較: steps.count.result.total > 5
ブール値評価: steps.validate.result.isValid
ステップのステータス: steps.fetch_data.status == 'failed'
組み合わせ: &&、||、!

テンプレート形式も使えます。先に{{ }}のプレースホルダーが埋め込まれ、その結果がCELとして評価されます。文字列になるプレースホルダーは、"'{{steps.check.result.status}}' == 'success'"のようにクォートで囲んでください。

例：条件分岐

- id: check_type
  tool: PYTHON_SANDBOX_RUN
  input:
    - name: code
      value: |
        import json
        json.dumps({"type": "premium"})
    - name: data_type
      value: OBJECT

- id: premium_processing
  tool: PYTHON_SANDBOX_RUN
  when: "steps.check_type.result.data.type == 'premium'"
  needs:
    - check_type
  input:
    - name: code
      value: |
        "プレミアムユーザーを処理中..."

- id: standard_processing
  tool: PYTHON_SANDBOX_RUN
  when: "steps.check_type.result.data.type == 'standard'"
  needs:
    - check_type
  input:
    - name: code
      value: |
        "スタンダードユーザーを処理中..."

重要な注意事項

条件はステップ実行前に評価されます。whenではitem、itemIndex、itemCountは使えません
条件がfalseの場合、ステップのステータスはskippedになります
依存先がすべてスキップされたステップもスキップされます。ほかに成功した依存先があれば実行されます
whenを設定すると、条件だけで実行するかどうかが決まり、依存先が失敗してもキャンセルされません。when: "true"なら依存先が失敗しても実行され、when: "steps.X.status == 'failed'"なら失敗したときだけ実行されます
条件を評価できない場合（プレースホルダーが空文字になった場合など）、ステップはfailedになります

ループ実行（forEach）

forEachオプションは、コレクション内の各アイテムに対してステップを複数回実行します。これはデータリストのバッチ処理に便利です。

基本構文

- id: get_list
  tool: INPUT_JSON
  input:
    - name: value
      value: '["apple", "banana", "cherry"]'

- id: process_items
  tool: TOOL_NAME
  needs:
    - get_list
  forEach: "steps.get_list.result"
  input:
    - name: value
      value: "{{item}}"

forEachはテンプレート形式の"{{steps.get_list.result}}"も受け付けます。

動作の仕組み

forEachの値がリストとして評価されます。リストでない場合、ステップはエラーなしで0回実行されます
リスト内の各アイテムに対してステップが1回ずつ実行されます
ステップの入力では、{{item}}が現在のアイテム、{{itemIndex}}がその位置（0始まり）、{{itemCount}}がアイテム数です。アイテムがオブジェクトの場合は{{item.<property>}}か{{item | json}}を使ってください。{{item}}だけでは[object Object]と表示されます
後続のステップからは、steps.<step_id>がアイテムごとのエントリ（status、result、error）のリストとして見えます。steps.<step_id>.resultは成功したアイテムの結果のリスト、steps.<step_id>.statusはsuccess、partial、failedのいずれかです

例：複数アイテムの処理

- id: get_users
  tool: INPUT_JSON
  input:
    - name: value
      value: |
        [
          {"id": 1, "name": "Alice"},
          {"id": 2, "name": "Bob"},
          {"id": 3, "name": "Charlie"}
        ]

- id: greet_users
  tool: PYTHON_SANDBOX_RUN
  forEach: "steps.get_users.result"
  needs:
    - get_users
  input:
    - name: code
      value: |
        f"こんにちは、{item['name']}さん！"

- id: combine_greetings
  tool: PYTHON_SANDBOX_RUN
  needs:
    - greet_users
  input:
    - name: code
      value: |
        import json
        greetings = json.loads(r'''{{steps.greet_users.result}}''')
        "\n".join(g["data"] for g in greetings)

PYTHON_SANDBOX_RUNの中では、現在のアイテムをPythonの変数itemとしても使えます。各あいさつは{"data": "こんにちは、Aliceさん！"}として格納されるため、combine_greetingsではg["data"]を読み取ります。

アイテムプロパティへのアクセス

forEach: "steps.items.result"
input:
  - name: id
    value: "{{item.id}}"
  - name: name
    value: "{{item.name}}"

forEachとインデックス

ループ内の位置はitemIndex（0始まり）とitemCountで分かります：

- id: get_items
  tool: INPUT_JSON
  input:
    - name: value
      value: '["apple", "banana", "cherry"]'

- id: process_with_index
  tool: PYTHON_SANDBOX_RUN
  needs:
    - get_items
  forEach: "steps.get_items.result"
  input:
    - name: code
      value: |
        position = {{itemIndex}} + 1
        total = {{itemCount}}
        f"{position}/{total}: {item}"

forEachのオプション

forEachOptions でアイテムの処理方法を制御します。ステップ設定画面では、順次 / 並列（スレッド数付き）の選択、処理するアイテムの最大数、エラー時に停止 / 続行の選択に対応します：

- id: process_items
  tool: TOOL_NAME
  forEach: "{{steps.get_list.result}}"
  forEachOptions:
    concurrency: 1        # 1 = 順次。2 以上 = そのスレッド数で並列
    maxItems: 100         # 先頭 N 件のみ処理
    continueOnError: true # 失敗したアイテムをスキップしてループを続行
  input:
    - name: item
      value: "{{item}}"

concurrency: 同時に実行するアイテム数。順次を選ぶと 1、並列を選ぶと入力したスレッド数が保存されます。未設定の場合は、デプロイ環境のデフォルトの並列数で実行されます
maxItems: リストの先頭 N 件のみを処理します。未設定の場合はすべてのアイテムを処理します
continueOnError: true（続行、デフォルト）は失敗したアイテムをスキップしてループを続け、false（エラー時に停止）はアイテムが失敗したバッチの後でループを止め、残りのアイテムをskippedにします。最初の失敗の直後に止めたい場合は、concurrency: 1にしてください

オプションの組み合わせ

needs、when、forEachを1つのステップで組み合わせることができます： check_enabledは、フロー内の前のステップを表します。その結果には真偽値のactiveが含まれることを想定しています。

- id: get_items
  tool: INPUT_JSON
  input:
    - name: value
      value: '["apple", "banana", "cherry"]'

- id: process_active_items
  tool: PYTHON_SANDBOX_RUN
  needs:
    - get_items
    - check_enabled
  when: "steps.check_enabled.result.active == true"
  forEach: "steps.get_items.result"
  input:
    - name: code
      value: |
        f"処理完了: {item}"

評価順序：

すべてのneedsのステップが終わるまで待機
whenが設定されていれば、trueの場合のみ実行。whenがなければ、needsのステップの結果で決まります（前述のとおりキャンセルまたはスキップ）
forEachループを実行（forEachがない場合は単一実行）

ベストプラクティス

依存関係

可能な限り依存チェーンを浅くする
並列実行を使用してパフォーマンスを向上させる
ステップに明確な名前を付けて依存関係を読みやすくする

条件

意味のある条件式を使用する
すべての可能な結果（成功、失敗、エッジケース）を考慮する
さまざまな入力値で条件をテストする

ループ

長い実行時間を避けるためにループ回数を制限する
空の配列を適切に処理する
大規模なデータセットのメモリ使用量を考慮する

Docs

ステップモジュールオプション

概要

ステップの依存関係（needs）

基本的な使い方

重要なポイント

例：マルチブランチワークフロー

条件付き実行（when）

基本構文

条件式

例：条件分岐

重要な注意事項

ループ実行（forEach）

基本構文

動作の仕組み

例：複数アイテムの処理

アイテムプロパティへのアクセス

forEachとインデックス

forEachのオプション

オプションの組み合わせ

ベストプラクティス

依存関係

条件

ループ

関連ドキュメント

​概要

​ステップの依存関係（needs）

​基本的な使い方

​重要なポイント

​例：マルチブランチワークフロー

​条件付き実行（when）

​基本構文

​条件式

​例：条件分岐

​重要な注意事項

​ループ実行（forEach）

​基本構文

​動作の仕組み

​例：複数アイテムの処理

​アイテムプロパティへのアクセス

​forEachとインデックス

​forEachのオプション

​オプションの組み合わせ

​ベストプラクティス

​依存関係

​条件

​ループ

​関連ドキュメント

概要

ステップの依存関係（needs）

基本的な使い方

重要なポイント

例：マルチブランチワークフロー

条件付き実行（when）

基本構文

条件式

例：条件分岐

重要な注意事項

ループ実行（forEach）

基本構文

動作の仕組み

例：複数アイテムの処理

アイテムプロパティへのアクセス

forEachとインデックス

forEachのオプション

オプションの組み合わせ

ベストプラクティス

依存関係

条件

ループ

関連ドキュメント