start_execution ¶

def start_execution(
    self,
    state_machine_arn: "capo_sfn.types.arn.Arn",
    *,
    config_overrides: Optional[SFNClientConfig] = None,
    name: Optional["capo_sfn.types.name.Name"] = None,
    input: Optional["capo_sfn.types.sensitive_data.SensitiveData"] = None,
    trace_header: Optional["capo_sfn.types.trace_header.TraceHeader"] = None,
) -> "capo_sfn.types.start_execution_output.StartExecutionOutput":
    r"""<p>Starts a state machine execution.</p> <p>A qualified state machine ARN can either refer to a <i>Distributed Map state</i> defined within a state machine, a version ARN, or an alias ARN.</p> <p>The following are some examples of qualified and unqualified state machine ARNs:</p> <ul> <li> <p>The following qualified state machine ARN refers to a <i>Distributed Map state</i> with a label <code>mapStateLabel</code> in a state machine named <code>myStateMachine</code>.</p> <p> <code>arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel</code> </p> <note> <p>If you provide a qualified state machine ARN that refers to a <i>Distributed Map state</i>, the request fails with <code>ValidationException</code>.</p> </note> </li> <li> <p>The following qualified state machine ARN refers to an alias named <code>PROD</code>.</p> <p> <code>arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD></code> </p> <note> <p>If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias.</p> </note> </li> <li> <p>The following unqualified state machine ARN refers to a state machine named <code>myStateMachine</code>.</p> <p> <code>arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine></code> </p> </li> </ul> <p>If you start an execution with an unqualified state machine ARN, Step Functions uses the latest revision of the state machine for the execution.</p> <p>To start executions of a state machine <a href="https://docs.aws.amazon.com/step-functions/latest/dg/concepts-state-machine-version.html">version</a>, call <code>StartExecution</code> and provide the version ARN or the ARN of an <a href="https://docs.aws.amazon.com/step-functions/latest/dg/concepts-state-machine-alias.html">alias</a> that points to the version.</p> <note> <p> <code>StartExecution</code> is idempotent for <code>STANDARD</code> workflows. For a <code>STANDARD</code> workflow, if you call <code>StartExecution</code> with the same name and input as a running execution, the call succeeds and return the same response as the original request. If the execution is closed or if the input is different, it returns a <code>400 ExecutionAlreadyExists</code> error. You can reuse the name 90 days after it closes. </p> <p> <code>StartExecution</code> isn't idempotent for <code>EXPRESS</code> workflows. </p> </note>

    Args:
        state_machine_arn: <p>The Amazon Resource Name (ARN) of the state machine to execute.</p> <p>The <code>stateMachineArn</code> parameter accepts one of the following inputs:</p> <ul> <li> <p> <b>An unqualified state machine ARN</b> – Refers to a state machine ARN that isn't qualified with a version or alias ARN. The following is an example of an unqualified state machine ARN.</p> <p> <code>arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine></code> </p> <p>Step Functions doesn't associate state machine executions that you start with an unqualified ARN with a version. This is true even if that version uses the same revision that the execution used.</p> </li> <li> <p> <b>A state machine version ARN</b> – Refers to a version ARN, which is a combination of state machine ARN and the version number separated by a colon (:). The following is an example of the ARN for version 10. </p> <p> <code>arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine>:10</code> </p> <p>Step Functions doesn't associate executions that you start with a version ARN with any aliases that point to that version.</p> </li> <li> <p> <b>A state machine alias ARN</b> – Refers to an alias ARN, which is a combination of state machine ARN and the alias name separated by a colon (:). The following is an example of the ARN for an alias named <code>PROD</code>.</p> <p> <code>arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD></code> </p> <p>Step Functions associates executions that you start with an alias ARN with that alias and the state machine version used for that execution.</p> </li> </ul>
        name: <p>Optional name of the execution. For STANDARD workflows, this name must be unique for your Amazon Web Services account, region, and state machine. If a previous execution with the same name exists, you can reuse the name 90 days after it closes. For EXPRESS workflows, execution names can be reused immediately. For more information, see <a href="https://docs.aws.amazon.com/step-functions/latest/dg/limits.html#service-limits-state-machine-executions"> Limits Related to State Machine Executions</a> in the <i>Step Functions Developer Guide</i>.</p> <p>If you don't provide a name for the execution, Step Functions automatically generates a universally unique identifier (UUID) as the execution name.</p> <p>A name must <i>not</i> contain:</p> <ul> <li> <p>white space</p> </li> <li> <p>brackets <code>< > { } [ ]</code> </p> </li> <li> <p>wildcard characters <code>? *</code> </p> </li> <li> <p>special characters <code>" # % \ ^ | ~ ` $ & , ; : /</code> </p> </li> <li> <p>control characters (<code>U+0000-001F</code>, <code>U+007F-009F</code>, <code>U+FFFE-FFFF</code>)</p> </li> <li> <p>surrogates (<code>U+D800-DFFF</code>)</p> </li> <li> <p>invalid characters (<code> U+10FFFF</code>)</p> </li> </ul> <p>To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.</p>
        input: <p>The string that contains the JSON input data for the execution, for example:</p> <p> <code>"{\"first_name\" : \"Alejandro\"}"</code> </p> <note> <p>If you don't include any JSON input data, you still must include the two braces, for example: <code>"{}"</code> </p> </note> <p>Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.</p>
        trace_header: <p>Passes the X-Ray trace header. The trace header can also be passed in the request payload.</p> <note> <p> For X-Ray traces, all Amazon Web Services services use the <code>X-Amzn-Trace-Id</code> header from the HTTP request. Using the header is the preferred mechanism to identify a trace. <code>StartExecution</code> and <code>StartSyncExecution</code> API operations can also use <code>traceHeader</code> from the body of the request payload. If <b>both</b> sources are provided, Step Functions will use the <b>header value</b> (preferred) over the value in the request body. </p> </note>

    Raises:
        capo_sfn.errors.execution_already_exists.ExecutionAlreadyExists: <p>The execution has the same <code>name</code> as another execution (but a different <code>input</code>).</p> <note> <p>Executions with the same <code>name</code> and <code>input</code> are considered idempotent.</p> </note>
        capo_sfn.errors.execution_limit_exceeded.ExecutionLimitExceeded: <p>The maximum number of running executions has been reached. Running executions must end or be stopped before a new execution can be started.</p>
        capo_sfn.errors.invalid_arn.InvalidArn: <p>The provided Amazon Resource Name (ARN) is not valid.</p>
        capo_sfn.errors.invalid_execution_input.InvalidExecutionInput: <p>The provided JSON input data is not valid.</p>
        capo_sfn.errors.invalid_name.InvalidName: <p>The provided name is not valid.</p>
        capo_sfn.errors.kms_access_denied_exception.KmsAccessDeniedException: <p>Either your KMS key policy or API caller does not have the required permissions.</p>
        capo_sfn.errors.kms_invalid_state_exception.KmsInvalidStateException: <p>The KMS key is not in valid state, for example: Disabled or Deleted.</p>
        capo_sfn.errors.kms_throttling_exception.KmsThrottlingException: <p>Received when KMS returns <code>ThrottlingException</code> for a KMS call that Step Functions makes on behalf of the caller.</p>
        capo_sfn.errors.state_machine_deleting.StateMachineDeleting: <p>The specified state machine is being deleted.</p>
        capo_sfn.errors.state_machine_does_not_exist.StateMachineDoesNotExist: <p>The specified state machine does not exist.</p>
        capo_sfn.errors.validation_exception.ValidationException: <p>The input does not satisfy the constraints specified by an Amazon Web Services service.</p>
        capo_sfn.errors.UnknownServiceError: The service returned an error code this client does not model.
    """

    def _handler(
        req: "OperationRequest[capo_sfn.types.start_execution_input.StartExecutionInput]",
    ) -> OperationResponse[
        "capo_sfn.types.start_execution_output.StartExecutionOutput"
    ]:
        import capo_sfn._operations.aws_step_functions.start_execution

        output, http_response = (
            capo_sfn._operations.aws_step_functions.start_execution.start_execution(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    def _redact_input(
        input_: "capo_sfn.types.start_execution_input.StartExecutionInput",
    ) -> dict[str, Any]:
        import capo_sfn.types.start_execution_input

        return capo_sfn.types.start_execution_input.redact_sensitive(input_)

    interceptors_, options_ = self.operation_options(
        config_overrides,
        OperationLogging("StartExecution", redact_input=_redact_input),
    )
    input_: capo_sfn.types.start_execution_input.StartExecutionInput = {
        "state_machine_arn": state_machine_arn
    }
    if name is not None:
        input_["name"] = name
    if input is not None:
        input_["input"] = input
    if trace_header is not None:
        input_["trace_header"] = trace_header

    response = execute_pipeline(
        OperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    response.response.close()
    return response.output