Step Functions の Context オブジェクトから実行データにアクセスする - AWS Step Functions
Context オブジェクトへのアクセスContext オブジェクトのフィールドMap ステートにおける Context オブジェクトのデータ

Step Functions の Context オブジェクトから実行データにアクセスする

ステートの管理とデータの変換

変数を使用したステート間のデータ受け渡しと JSONata を使用したデータ変換について説明します。

Context オブジェクトは、実行中に使用できる内部 JSON 構造であり、ステートマシンと実行に関する情報が含まれています。このコンテキストは、ワークフローにそれぞれの実行に関する情報を提供します。ワークフローでは、JSONata 式で $states.context を使用することで Context オブジェクトを参照できます。

Context オブジェクトへのアクセス

JSONata で Context オブジェクトにアクセスするには

JSONata ステートで Context オブジェクトにアクセスするには、JSONata 式で $states.context を使用します。

{
  "ExecutionID" : "{% $states.context.Execution.Id %}"
}

JSONPath で Context オブジェクトにアクセスするには

JSONPath で Context オブジェクトにアクセスするには、まずキーの末尾に .$ を追加して、その値がパスであることを示します。次に、値の前に $$. を付けて Context オブジェクト内のノードを選択します。

{
  "ExecutionID.$": "$$.Execution.Id"
}

JSONPath のステートでは、次の JSONPath フィールドからコンテキスト ($$.) を参照できます。

  • InputPath

  • OutputPath

  • ItemsPath (マップ状態)

  • Variable (選択状態)

  • ResultSelector

  • Parameters

  • 変数と変数の比較演算子

Context オブジェクトのフィールド

Context オブジェクトには、ステートマシン、ステート、実行、タスクに関する情報が含まれています。Context JSON オブジェクトには、次の形式で各タイプのデータのノードが含まれます。

{
    "Execution": {
        "Id": "String",
        "Input": {},
        "Name": "String",
        "RoleArn": "String",
        "StartTime": "Format: ISO 8601",
        "RedriveCount": Number,
        "RedriveTime": "Format: ISO 8601"
    },
    "State": {
        "EnteredTime": "Format: ISO 8601",
        "Name": "String",
        "RetryCount": Number
    },
    "StateMachine": {
        "Id": "String",
        "Name": "String"
    },
    "Task": {
        "Token": "String"
    }
}

実行中、Context オブジェクトには関連データが入力されます。

コンテキストには新しいフィールドが随時追加されます。JSON コンテキストを直接処理している場合は、新しい未知のフィールドを適切に処理できるコードを作成することをお勧めします。例えば、Jackson ライブラリで JSON をアンマーシャリングする場合は、UnrecognizedPropertyException を防ぐために、ObjectMapper で FAIL_ON_UNKNOWN_PROPERTIES を false に設定することをお勧めします。

また、RedriveTime Context オブジェクトは、実行を redriven した場合にのみ使用できます。redriven a Map Run 済みの場合、RedriveTime コンテキストオブジェクトは Standard タイプの子ワークフローでのみ使用できます。Express タイプの子ワークフローを含む redriven マップ実行では、RedriveTime は使用できません。

実行中に取得できるコンテンツは、次の形式で構成されます。

{
    "Execution": {
        "Id": "arn:aws:states:region:123456789012:execution:stateMachineName:executionName",
        "Input": {
           "key": "value"
        },
        "Name": "executionName",
        "RoleArn": "arn:aws:iam::123456789012:role...",
        "StartTime": "2025-08-27T10:04:42Z"
    },
    "State": {
        "EnteredTime": "2025-08-27T10:04:42.001Z",
        "Name": "Test",
        "RetryCount": 3
    },
    "StateMachine": {
        "Id": "arn:aws:states:region:123456789012:stateMachine:stateMachineName",
        "Name": "stateMachineName"
    },
    "Task": {
        "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
    }
}
秒の小数部を含むタイムスタンプ形式

Step Functions は ISO8601 仕様に準拠しており、出力の秒の小数部は必要に応じて 0、3、6、または 9 桁のいずれかになります。タイムスタンプの秒の小数部がゼロの場合、Step Functions は出力の末尾にゼロを追加するのではなく、ゼロを削除します。

Step Functions のタイムスタンプを処理するコードは、秒の小数部の桁数が可変であることを考慮して、作成する必要があります。

Map ステートにおける Context オブジェクトのデータ

ステートの管理とデータの変換

変数を使用したステート間のデータ受け渡しと JSONata を使用したデータ変換について説明します。

Map ステートを処理しているとき、コンテキストには Index、Value、Source などの情報も含まれます。

各 Map ステートのイテレーションでは、Index に現在処理中の配列要素のインデックス番号が、Value に処理中の配列要素そのものが、Source には CSV、JSON、JSONL、PARQUET のいずれかに対応する InputType が含まれます。

Map ステート内では、Context オブジェクトに次のデータが含まれます。

"Map": {
   "Item": {
      "Index" : Number,
      "Key"   : "String", // Only valid for JSON objects
      "Value" : "String",
      "Source": "String"
   }
}

これらは Map 状態でのみ使用でき、ItemSelector (Map) フィールドで指定することができます。

注記

Context オブジェクトのパラメータは、ItemSelector セクションに含まれるステート内ではなく、メインの Map ステートの ItemProcessor ブロック内に定義する必要があります。

JSONPath の Map ステートを使用しているステートマシンでは、次のように Context オブジェクトから情報を挿入できます。

{
  "StartAt": "ExampleMapState",
  "States": {
    "ExampleMapState": {
      "Type": "Map",
      "ItemSelector": {
        "ContextIndex.$": "$$.Map.Item.Index",
        "ContextValue.$": "$$.Map.Item.Value",
        "ContextSource.$": "$$.Map.Item.Source"
      },
      "ItemProcessor": {
        "ProcessorConfig": {
          "Mode": "INLINE"
        },
        "StartAt": "TestPass",
        "States": {
          "TestPass": {
            "Type": "Pass",
            "End": true
          }
        }
      },
      "End": true
    }
  }
}

JSONata を使用する場合は、Map ステートで追加されるコンテキスト情報に $states.context 変数からアクセスできます。

{
  "StartAt": "ExampleMapState",
  "States": {
    "ExampleMapState": {
      "Type": "Map",
      "ItemSelector": {
        "ContextIndex": "{% $states.context.Map.Item.Index %}",
        "ContextValue": "{% $states.context.Map.Item.Value %}",
        "ContextSource": "{% $states.context.Map.Item.Source %}"
      },
      "ItemProcessor": {
        "ProcessorConfig": {
          "Mode": "INLINE"
        },
        "StartAt": "TestPass",
        "States": {
          "TestPass": {
            "Type": "Pass",
            "End": true
          }
        }
      },
      "End": true
    }
  }
}

次の入力を使用して前のステートマシンを実行すると、 Index と Value が出力に挿入されます。

[
  {
    "who": "bob"
  },
  {
    "who": "meg"
  },
  {
    "who": "joe"
  }
]

実行の出力では、以下のように、3 回の各反復に対して Index および Value 項目の値が返されます。

[
  {
    "ContextIndex": 0,
    "ContextValue": {
      "who": "bob"
    },
    "ContextSource" : "STATE_DATA" 
  },
  {
    "ContextIndex": 1,
    "ContextValue": {
      "who": "meg"
    },
    "ContextSource" : "STATE_DATA" 
  },
  {
    
    "ContextIndex": 2,
    "ContextValue": {
      "who": "joe"
    },
    "ContextSource" : "STATE_DATA" 
  }
]

$states.context.Map.Item.Source の値は、次のいずれかになります。

  • ステートの入力では、値は STATE_DATA です。

  • Amazon S3 LIST_OBJECTS_V2 と Transformation=NONE を組み合わせた場合、値はバケットの S3 URI になります。例: S3://bucket-name。

  • 他のすべての入力タイプの場合、値は Amazon S3 URI になります。例: S3://bucket-name/object-key。