Step Functionsの入出力処理の制御パラメータ（InputPath、 Parameters、ResultPathおよびOutputPath）を理解するために参照したドキュメント

こんにちは、CX事業本部の若槻です。

AWS Step Functionsの入出力処理の制御で利用可能なパラメータには以下のようなものがあります。

• InputPath
• Parameters
• ResultPath
• OutputPath

これらパラメータは使いこなせればとても便利ですが、直感では動きが分かりづらい部分があります。

そこで今回は、Step Functionsの上記パラメータの動きを理解するのに特に役に立ったAWS ドキュメントを紹介をしていきます。

そもそもStep Functionsとは

• https://aws.amazon.com/jp/step-functions/

AWS Step Functions では、AWS の複数のサービスをサーバーレスのワークフローに整理できるため、すばやくアプリケーションをビルドおよび更新できます。Step Functions を使用すると、AWS Lambda や Amazon ECS などのサービスをつなげて機能豊富なアプリケーションにまとめるワークフローを設計して実行できます。ワークフローは一連のステップで構成され、あるステップの出力が次のステップへの入力になります。アプリケーションの開発は、Step Functions を使用することで、よりシンプルかつ直感的になります。ワークフローが、理解しやすく、他の人に説明しやすく、変更しやすいステートマシン図に変換されるためです。アプリケーションの実行の各ステップをありのままにモニタリングできるため、問題をすばやく特定して修正できます。Step Functions では、各ステップが自動的にトリガーおよび追跡され、エラーが発生した場合は再試行されるため、アプリケーションが意図したとおりの順序で実行されます。

パラメータを理解するのに役立ったAWSドキュメント

Step Functions の入出力処理

Step Functions の入出力処理 は、各パラメータの端的な説明と入出力を表すイラストがとても分かりやすかったです。

• 説明

次の図は、JSON 情報がタスク状態を遷移する様子を表します。InputPath では、Task 状態のタスクにどの JSON 入力部分を渡すかを選択します (例: AWS Lambda 関数)。次に、ResultPath を使用して、出力に渡す状態入力とタスク結果の組み合わせを選択します。OutputPath では、JSON 出力をフィルタリングして、出力に渡される情報を絞り込むことができます。

• イラスト

上記の説明およびイラストをまとめると以下のようになります。

• InputPath：「State Input」のどのJSON部分を「タスク(Lambda関数など)の入力」（または「Parametersの入力」）とするかを指定する。
• Parameters：「InputPathの出力」のJSONを利用した新しいJSONを動的に作成し、「タスク(Lambda関数など)の入力」とする。
• ResultPath：「タスク(Lambda関数など)の出力」を「State Input」のどのJSON部分と置き換えるかを指定する。
• OutputPath：「ResultPathの出力」のどのJSON部分を「State Output」とするかを指定する。

InputPath、ResultPath、および OutputPath 例

InputPath、ResultPath、および OutputPath 例 では、JSONデータのサンプルを利用した入出力の動作例が分かりやすく示されていました。

• ステートマシン定義

Lambda関数に対する入出力を行うステートマシンです。

{
  "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
  "StartAt": "HelloWorld",
  "States": {
    "HelloWorld": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:HelloFunction",
      "InputPath": "$.lambda",
      "ResultPath": "$.data.lambdaresult",
      "OutputPath": "$.data",
      "End": true
    }
  }
}

• State Input

{
  "comment": "An input comment.",
  "data": {
    "val1": 23,
    "val2": 17
  },
  "extra": "foo",
  "lambda": {
    "who": "AWS Step Functions"
  }
}

• InputPath$.lambdaの出力

{"who": "AWS Step Functions"}

• Lambda関数からの出力

Hello, AWS Step Functions!

• ResultPath$.data.lambdaresultの出力

{
  "comment": "An input comment.",
  "data": {
    "val1": 23,
    "val2": 17,
    "lambdaresult": "Hello, AWS Step Functions!"
  },
  "extra": "foo",
  "lambda": {
    "who": "AWS Step Functions"
  }
}

• OutputPath$.dataの出力

{
  "val1": 23,
  "val2": 17,
  "lambdaresult": "Hello, AWS Step Functions!"
}

上記の動作例を前項目のイラストに当てはめると以下のようになります。

InputPath およびパラメータ

InputPath およびパラメータ では、Parametersパラメータの入出力の動作例が分かりやすく示されていました。

• InputPathの出力

{
  "comment": "Example for Parameters.",
  "product": {
    "details": {
       "color": "blue",
       "size": "small",
       "material": "cotton"
    },
    "availability": "in stock",
    "sku": "2317",
    "cost": "$23"
  }
}

• Parametersの値

{
    "comment": "Selecting what I care about.",
    "MyDetails": {
      "size.$": "$.product.details.size",
      "exists.$": "$.product.availability",
      "StaticValue": "foo"
    }
}

• Parametersの出力

{
  "comment": "Selecting what I care about.",
  "MyDetails": {
      "size": "small",
      "exists": "in stock",
      "StaticValue": "foo"
  }
}

上記の動作例を前項目のイラストに当てはめると以下のようになります。

各パラメータのまとめと補足

InputPath

「State Input」のどのJSON部分を「タスク(Lambda関数など)の入力」（または「Parametersの入力」）とするかを指定するパラメータです。

パラメータ値を$とした場合、「State Input」のJSON全体が「タスク(Lambda関数など)の入力」となります。

指定しない場合、デフォルトの値は$となります。

Parameters

「InputPathの出力」のJSONを利用した新しいJSONを動的に作成し「タスク(Lambda関数など)の入力」とするパラメータです。

指定しない場合は利用されません。

ResultPath

「タスク(Lambda関数など)の出力」を「State Input」のどのJSON部分と置き換えるかを指定パラメータです。

パラメータ値を$とした場合、「State Input」のJSON全体が「タスク(Lambda関数など)の出力」と置き換わります。

指定しない場合、デフォルトの値は$となります。

• ResultPath を使用して結果で入力を置き換える

ResultPath を指定しない場合、デフォルトの動作は、"ResultPath": "$" を指定した場合と同様になります。

OutputPath

「ResultPathの結果」のどのJSON部分を「State Output」とするかを指定するパラメータです。

パラメータ値を$とした場合、「ResultPathの出力」のJSON全体が「State Output」となります。

指定しない場合、デフォルトの値は$となります。

• Step Functions の入出力処理 » OutputPath

OutputPath を指定しない場合、デフォルトの値は $ です。

おわりに

今回の記事の内容は、下記の記事を書く際に検証を重ねた際の副産物となります。

• Amazon Transcribeによる音声認識をポーリング方式（Step Functions + Lambda）でやってみた

Step Functionsは今後サーバーレス構成を扱う中で利用する機会が多くなる機能なので、理解を深められて良かったです。

以上