CloudFlow:入力と出力

フローとステップ

データは、フロー内のステップ間で受け渡されることがよくあります。フロー定義言語 (FDL) のステップは、関数型プログラミング言語の関数に似ています。入力を受け取り、出力を返します。出力は、呼び出し元である親ステップのローカル変数に保存されます。入力と出力は、JSON オブジェクト形式でなければなりません。ローカル変数の型はステップによって異なります。たとえば、タスクステップでは Function Compute 関数呼び出しの結果をローカル変数として使用します。並列ステップでは、すべてのブランチの出力の配列をローカル変数として使用します。ステップの入力、出力、ローカル変数の合計サイズは 32 KB を超えることはできません。この制限を超えると、フローの実行は失敗します。

あるステップが別のステップを含む場合、外側のステップを親ステップ、内側のステップを子ステップと呼びます。最も外側のステップの親はフロー自体です。2 つのステップが同じ親ステップを持つ場合、それらは兄弟ステップです。

フローとステップの両方に、入力、出力、ローカル変数があります。次のリストでは、これらがどのように変換されるかを説明します。

• ステップ入力マッピング (inputMappings) は、親ステップの入力とローカル変数を子ステップの入力にマッピングします。
• ステップ出力マッピング (outputMappings) は、現在のステップの入力とローカル変数を現在のステップの出力にマッピングします。
• フロー入力マッピング (inputMappings) は、ユーザーがフローを実行するときに提供する入力をフローの入力にマッピングします。
• フロー出力マッピング (outputMappings) は、フローの入力とローカル変数をフローの出力にマッピングします。

親ステップのローカル変数には、すべての子ステップの出力をマージした結果が保存されます。出力に同じ名前のキーが含まれている場合、後に実行されるステップの結果が先に実行されたステップの結果を上書きします。ほとんどの場合、入力マッピングと出力マッピングを指定する必要はありません。代わりに、デフォルトのマッピング動作を使用できます。デフォルトの変換は次のとおりです：

• 入力マッピングを指定しない場合、子ステップの入力は、親ステップの入力とローカル変数をマージしたものになります。ローカル変数と入力に同じ名前のキーがある場合、ローカル変数の値が入力の値を上書きします。
• 出力マッピングを指定しない場合、並列ステップと foreach ステップを除くほとんどのステップでは、ローカル変数が出力として使用されます。

入力と出力をより細かく制御するには、詳細なマッピングルールを理解する必要があります。

次の図は、サンプルフローの入力マッピングと出力マッピングを示しています。この例では、step1 は step2 と step3 の親ステップです。step1 と step4 は最も外側のステップです。

version: v1
type: flow
steps:
  - type: parallel
    name: step1
    branches:
      - steps:
        - type: pass
          name: step2
      - steps:
        - type: pass
          name: step3
  - type: pass
    name: step4      

次のコードは、これらのマッピングを分かりやすく説明したものです。

func flow(input0 Input) (output0 Output) {
  local0 := {}
  input1 := buildInput(step1InputMappings, input0, local0)
  output1 := step1(input1)
  save(local0, output1)
  input4 := buildInput(step4InputMappings, input0, local0)
  output4 := step4(input4)
  save(local0, output4)
  return buildOutput(flowOutputMappings, input0, local0)
}
func step1(input1 Input) (output1 Output) {
  local10 := {}
  input2 := buildInput(step2InputMappings, input1, local10)
  output2 := step2(input2)
  save(local10, output2)
  local11 := {}
  input3 := buildInput(step3InputMappings, input1, local11)
  output3 := step3(input3)
  save(local11, output3)
  return buildOutput(step1OutputMappings, [local10, local11])
}
func step2(input2 Input) (output2 Output) {
}
func step3(input3 Input) (output3 Output) {
}
func step4(input4 Input) (output4 Output) {
}       

この例では、フローには 2 つの子ステップ (step1 と step4) が含まれます。step1 は並列ステップで、2 つの子ステップ (step2 と step3) を含みます。

1. システムがフローの実行を開始すると、フローの入力マッピングに基づいて StartExecution の入力をフロー入力 (input0) に変換します。
2. flow が開始されると、そのローカル変数 local0 は空です。
3. システムは、入力マッピング (step1InputMappings) に基づいて step1 の入力 input1 を準備します。マッピングのソースは、flow の入力 input0 とローカル変数 local0 です。
4. システムは step1 を呼び出し、入力 input1 を渡し、step1 は出力 output1 を返します。
   • step1 が開始されると、そのローカル変数は空です。step1step1 は並列ステップであるため、同時アクセスの問題を防ぐために、各ブランチは独自のローカル変数を持ちます。
   • システムは、入力マッピング (step2InputMappings) に基づいて step2 の入力 input2 を準備します。マッピングのソースは、step1 の入力 input1 とローカル変数 local10 です。
   • システムは step2 を呼び出し、入力 input2 を渡し、step2 は出力 output2 を返します。
   • システムは step2 の出力を、step1 のローカル変数 local10 に保存します。
   • 同様に、システムは step3 を呼び出し、その結果を step1 のローカル変数 local11 に保存します。
5. システムは step1 の出力を、flow のローカル変数 local0 に保存します。
6. 同様に、システムは入力マッピングに基づいて step4 の入力 input4 を準備します。マッピングのソースは、flow の入力 input0 とローカル変数 local0 です。
   説明 この時点で、ローカル変数 local0 には、すでに step1 の出力が含まれている場合があります。これが、step1 と step4 の間でデータが受け渡される仕組みです。
7. システムは step4 を呼び出し、入力 input4 を渡し、step4 は出力 output4 を返します。
8. システムは step4 の出力を、flow のローカル変数 local0 に保存します。
9. 最後に、システムはフローの出力マッピングに基づいて local0 をフローの出力に変換します。

型定義

入力マッピングと出力マッピングはいずれも、target と source のペアで構成される配列です。source はパラメーター値の取得元を定義し、target は宛先パラメーター名を定義します。source の値が $ で始まる場合、それはシステムが解析して特定の値を取得するための JSONPath 式です。それ以外の場合、その値は定数として扱われます。たとえば、$input.key は、パラメーター値が input オブジェクト内の key の値であることを示します。JSONPath 式をテストするには、このツール を使用できます。

• ソース

  source フィールドは定数値をサポートします。定数値の型は、number、文字列、ブール値、配列、object、または null です。

  次の例は、さまざまな型の定数を使用したマッピングと、その結果の出力を示しています。

  outputMappings:
    - target: int_key
      source: 1
    - target: bool_key
      source: true
    - target: string_key
      source: abc
    - target: float_key
      source: 1.234
    - target: null_key
      source: null
    - target: array1
      source: [1, 2, 3]
    - target: array2
      source:
        - 1
        - 2
        - 3
    - target: object1
      source: {a: b}
    - target: object2
      source:
        a: b          

  {
    "array1": [1, 2, 3],
    "array2": [1, 2, 3],
    "bool_key": true,
    "float_key": 1.234,
    "int_key": 1,
    "null_key": null,
    "object1": {
      "a": "b"
    },
    "object2": {
      "a": "b"
    },
    "string_key": "abc"
  }            

• ターゲット

  ターゲットは文字列の定数でなければなりません。

入力マッピング

入力マッピングは、親ステップの入力 ($input)、親ステップのローカル変数 ($local)、または定数を子ステップの入力に変換します。入力マッピングを指定しない場合、親ステップの入力とローカル変数がマージされ、子ステップの入力として使用されます。親ステップの入力とローカル変数に同じ名前のキーがある場合、ローカル変数の値が入力の値を上書きします。

inputMappings:
  - target: key1
    source: $input.key1
  - target: key2
    source: $local.key2
  - target: key3
    source: literal         

{
"key1":"value1"
}

{
"key2":"value2"
}

inputMappings:
  - target: key1
    source: $input.key1
  - target: key2
    source: $local.key2
  - target: key3
    source: literal

{
"key1":"value1",
"key2":"value2",
"key3":"literal"
}

{
"key1":"value1"
}

{
"key2":"value2"
}

{
"key1":"value1",
"key2":"value2"
}

{
"key1":"value1"
}

{
"key1":"value2"
}

{
"key1":"value2"
}

出力マッピング

出力マッピングは、現在のステップの入力 ($input)、ローカル変数 ($local)、または定数をステップの出力に変換します。出力マッピングを指定しない場合、選択ステップとループステップでは、ローカル変数が出力として使用されます。タスクステップでは、タスク実行の結果が出力として使用されます。並列ステップと foreach ステップのローカル変数は配列であるため、配列の結果を JSON オブジェクトに変換するには出力マッピングを定義する必要があります。デフォルトでは、これらのローカル変数は出力に含まれません。詳細については、各ステップの説明をご参照ください。

outputMappings:
  - target: key1
    source: $input.key1
  - target: key2
    source: $local.key2
  - target: key3
    source: literal          

{
"key1":"value1"
}

{
"key2":"value2"
}

outputMappings:
  - target: key1
    source: $input.key1
  - target: key2
    source: $local.key2
  - target: key3
    source: literal

{
"key1":"value1",
"key2":"value2",
"key3":"literal"
}

{
"key1":"value1"
}

[
  {
    "key2":"value2.1"
  },
  {
    "key2":"value2.2"
  }
]

outputMappings:
  - target: key1
    source: $input.key1
  - target: key2
    source: $local[*].key2
  - target: key3
    source: literal

{
  "key1":"value1",
  "key2":["value2.1","value2.2"],
  "key3":"literal"
}

{
"key1":"value1"
}

{
"key2":"value2"
}

{
"key2":"value2"
}

出力を親ステップのローカル変数に保存する方法

子ステップの出力 ($output) は、親ステップのローカル変数にマージされます。両方に同じ名前のキーがある場合、出力の値がローカル変数内の対応する値を上書きします。

{
"key1":"value1"
}

{
"key2":"value2"
}

{
  "key1":"value1",
  "key2":"value2"
}

{
"key1":"value11"
}

{
  "key1":"value1",
  "key2":"value2"
}

{
  "key1":"value11",
  "key2":"value2"
}