Descubrimiento de los patrones de integración de servicios en Step Functions

Para las integraciones de servicios, puede especificar varios patrones de integración para controlar la forma en que su máquina de estado interactúa con los servicios de AWS integrados:

Cada uno de estos patrones de integración de servicios se controla por cómo se crea un URI en el campo "Resource" de la definición de tarea.

El valor de un recurso de ASL en Step Functions es un nombre único (URI) que se ajusta al formato ARN, pero normalmente no identifica un recurso real de su cuenta. El prefijo “arn:aws:states:” configura un espacio de nombres que Step Functions utiliza para las integraciones. La porción ::: del valor denota campos region y account-id vacíos e innecesarios porque ambos se deducen de la región y la cuenta en las que se ejecuta el flujo de trabajo.

Las integraciones heredadas con AWS Lambda son la única excepción en la que el valor de recurso especifica un recurso real de la función de Lambda. La consola de Step Functions mostrará estos recursos heredados, pero no puede crear ni editar dichos recursos en la interfaz de usuario gráfica actual, a menos que decida editar el código ASL directamente.

Compatibilidad con patrones de integración

Los flujos de trabajo estándar y los flujos de trabajo rápidos son compatibles con las mismas integraciones, pero no con los mismos patrones de integración.

Para ayudarle a decidir entre los dos tipos, consulte Elegir el tipo de flujo de trabajo en Step Functions.

AWS Integraciones de SDK en Step Functions

Integraciones optimizadas en Step Functions

Respuesta de la solicitud

Cuando se especifica un servicio en la cadena "Resource" del estado de la tarea y solo se proporciona el recurso, Step Functions esperará una respuesta HTTP y, a continuación, avanzará al siguiente estado. Step Functions no esperará a que se complete un trabajo.

En el siguiente ejemplo se muestra cómo publicar un tema de Amazon SNS.

"Send message to SNS": {
    "Type":"Task",
    "Resource":"arn:aws:states:::sns:publish",
    "Parameters": {
        "TopicArn":"arn:aws:sns:region:123456789012:myTopic",
        "Message":"Hello from Step Functions!"
    },
    "Next":"NEXT_STATE"
}

Este ejemplo hace referencia a la API Publish de Amazon SNS. El flujo de trabajo avanza hasta el siguiente estado después de llamar a la API Publish.

Ejecutar un trabajo (.sync)

En servicios integrados como AWS Batch y Amazon ECS, Step Functions puede esperar a que finalice una solicitud antes de avanzar al siguiente estado. Para que Step Functions espere, especifique el campo "Resource" en la definición de estado de tarea con el sufijo .sync añadido después del URI del recurso.

Por ejemplo, para enviar un trabajo de AWS Batch, consulte el campo "Resource" de la definición de la máquina de estado como se muestra en este ejemplo.

"Manage Batch task": {
    "Type": "Task",
    "Resource": "arn:aws:states:::batch:submitJob.sync",
    "Parameters": {
        "JobDefinition": "arn:aws:batch:us-east-2:123456789012:job-definition/testJobDefinition",
        "JobName": "testJob",
        "JobQueue": "arn:aws:batch:us-east-2:123456789012:job-queue/testQueue"
    },
    "Next": "NEXT_STATE"
}

Tener la parte .sync añadida al nombre de recurso de Amazon (ARN) del recurso significa que Step Functions espera a que finalice el trabajo. Después de llamar a AWS Batch de submitJob, el flujo de trabajo se detiene. Cuando finaliza el trabajo, Step Functions avanza al siguiente estado. Para obtener más información, consulte el proyecto de muestra de AWS Batch: Administración de un trabajo por lotes con AWS Batch y Amazon SNS.

Si se anula una tarea que utiliza este patrón de integración de servicios (.sync) y Step Functions no puede cancelarla, es posible que se incurra en cargos adicionales por el servicio integrado. Una tarea se puede anular si:

Step Functions hará todo lo posible por cancelar la tarea. Por ejemplo, si se anula una tarea states:startExecution.sync de Step Functions, se llamará a la acción de la API StopExecution de Step Functions. Sin embargo, es posible que Step Functions no pueda cancelar la tarea. Entre los motivos se incluyen, entre otros:

Cuando utiliza el patrón de integración de servicios .sync, Step Functions utiliza sondeos que consumen la cuota y los eventos asignados para supervisar el estado de un trabajo. Para las invocaciones .sync dentro de la misma cuenta, Step Functions utiliza los eventos de EventBridge y sondea las API que especifique en el estado Task. Para las invocaciones .sync entre cuentas, Step Functions solo utiliza sondeos. Por ejemplo, para states:StartExecution.sync, Step Functions realiza sondeos en la API DescribeExecution y utiliza la cuota asignada.

Para ver una lista de los servicios integrados que admiten la espera para que finalice un trabajo (.sync), consulte Integración de servicios con Step Functions.

En algunos casos, es posible que desee que Step Functions continúe con el flujo de trabajo antes de que el trabajo finalice por completo. Puede lograrlo de la misma manera que cuando utiliza el patrón de integración de servicios Cómo esperar una devolución de llamada con el token de tarea. Para ello, pase un token de tarea a su trabajo y, a continuación, devuélvalo mediante una llamada a la API SendTaskSuccess o SendTaskFailure. Step Functions utilizará los datos que proporcione en esa llamada para completar la tarea, dejar de supervisar el trabajo y continuar con el flujo de trabajo.

Cómo esperar una devolución de llamada con el token de tarea

Las tareas de devolución de llamada proporcionan una forma de detener un flujo de trabajo hasta que se devuelva un token de tarea. Una tarea podría tener que esperar la aprobación por parte de una persona, integrarse con un tercero o llamar a sistemas heredados. Para tareas como estas, puede pausar Step Functions hasta que la ejecución del flujo de trabajo alcance la cuota de servicio de un año (consulte Cuotas relacionadas con la limitación controlada de estados) y esperar a que se complete un proceso o flujo de trabajo externo. En estas situaciones, Step Functions le permite pasar un token de tarea a las integraciones de servicios del SDK de AWS y también a algunas integraciones de servicios optimizadas. La tarea se detendrá hasta que se reciba dicho token de tarea de nuevo con una llamada SendTaskSuccess o SendTaskFailure.

Si se agota el tiempo de espera de un estado Task que utiliza el token de tarea de devolución de llamada, se genera un nuevo token aleatorio. Puede acceder a los tokens de tarea desde el objeto Context.

Para usar .waitForTaskToken con una integración del SDK de AWS, la API que utilice debe tener un campo de parámetros en el que colocar el token de tarea.

Para ver una lista de los servicios integrados que admiten la espera de un token de tarea (.waitForTaskToken), consulte Integración de servicios con Step Functions.

Ejemplo de token de tarea

En este ejemplo, un flujo de trabajo de Step Functions debe integrarse con un microservicio externo para realizar una comprobación de crédito como parte de un flujo de trabajo de aprobación. Step Functions publica un mensaje de Amazon SQS que incluye un token de tarea como parte del mensaje. Un sistema externo se integra con Amazon SQS y obtiene el mensaje de la cola. Cuando dicho proceso haya terminado, devuelve el resultado y el token de tarea original. Posteriormente, Step Functions continúa con su flujo de trabajo.

El campo "Resource" de la definición de tarea que hace referencia a Amazon SQS incluye .waitForTaskToken añadido al final.

"Send message to SQS": {
    "Type": "Task",
    "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
    "Parameters": {
        "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
        "MessageBody": {
            "Message": "Hello from Step Functions!",
            "TaskToken.$": "$$.Task.Token"
        }
    },
    "Next": "NEXT_STATE"
}

Este indica a Step Functions que se detenga y espere el token de tarea. Cuando se especifica un recurso con .waitForTaskToken, se puede acceder al token de tarea en el campo "Parameters" de la definición de estado con una designación de ruta especial ($$.Task.Token). La $$. inicial designa que la ruta accede al objeto Context y obtiene el token de tarea para la tarea actual en una ejecución en curso.

Cuando finalice, el servicio externo llama a SendTaskSuccess o SendTaskFailure con el taskToken incluido. Solo entonces el flujo de trabajo avanza al siguiente estado.

Obtención de un token del objeto Context

El objeto Context es un objeto JSON interno que contiene información acerca de la ejecución. Al igual que la entrada de estado, se puede acceder con una ruta desde el campo "Parameters" durante una ejecución. Al obtener acceso desde una definición de tarea, incluye información acerca de la ejecución específica, incluido el token de tarea.

{
    "Execution": {
        "Id": "arn:aws:states:region:account-id:execution:stateMachineName:executionName",
        "Input": {
            "key": "value"
        },
        "Name": "executionName",
        "RoleArn": "arn:aws:iam::account-id:role...",
        "StartTime": "2019-03-26T20:14:13.192Z"
    },
    "State": {
        "EnteredTime": "2019-03-26T20:14:13.192Z",
        "Name": "Test",
        "RetryCount": 3
    },
    "StateMachine": {
        "Id": "arn:aws:states:region:account-id:stateMachine:stateMachineName",
        "Name": "name"
    },
    "Task": {
        "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
    }
}

Puede acceder al token de tarea mediante una ruta especial desde dentro del campo "Parameters" de la definición de tarea. Para acceder a la entrada o al objeto Context, especifique primero que el parámetro será una ruta añadiendo un .$ al nombre del parámetro. El siguiente ejemplo especifica los nodos de la entrada y del objeto Context en una especificación de "Parameters".

"Parameters": {
    "Input.$": "$",
    "TaskToken.$": "$$.Task.Token"
},

En ambos casos, la adición de .$ al nombre del parámetro indica a Step Functions que espere una ruta. En el primer caso, "$" es una ruta que incluye toda la entrada. En el segundo caso, $$. especifica que la ruta accederá al objeto Context y $$.Task.Token establece el parámetro en el valor del token de tarea en el objeto Context de una ejecución en curso.

En el ejemplo de Amazon SQS, .waitForTaskToken en el campo "Resource" indica a Step Functions que espere a que se devuelva el token de tarea. El parámetro "TaskToken.$": "$$.Task.Token" pasa dicho token como parte del mensaje de Amazon SQS.

"Send message to SQS": {
    "Type": "Task",
    "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
    "Parameters": {
        "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
        "MessageBody": {
            "Message": "Hello from Step Functions!",
            "TaskToken.$": "$$.Task.Token"
        }
    },
    "Next": "NEXT_STATE"
}

Para obtener más información acerca del objeto Context, consulte Acceso a los datos de ejecución desde el objeto Context en Step Functions en la sección Entrada y salida de procesamiento de esta guía.

Cómo configurar un tiempo de espera de latido para una tarea en espera

Una tarea que está a la espera de un token de tarea esperará hasta que la ejecución alcance la cuota de servicio de un año (consulte )., Cuotas relacionadas con la limitación controlada de estados). Para evitar que las ejecuciones se bloqueen, puede configurar un intervalo de tiempo de espera de latido en la definición de máquina de estado. Utilice el campo HeartbeatSeconds para especificar el intervalo de tiempo de espera.

{
    "StartAt": "Push to SQS",
        "States": {
        "Push to SQS": {
            "Type": "Task",
                "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
                    "HeartbeatSeconds": 600,
            "Parameters": {
                "MessageBody": { "myTaskToken.$": "$$.Task.Token" },
                "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/push-based-queue"
            },
            "ResultPath": "$.SQS",
                "End": true
        }
    }
}

En esta definición de máquina de estado, una tarea envía un mensaje a Amazon SQS y espera a que un proceso externo devuelva la llamada con el token de tarea proporcionado. El campo "HeartbeatSeconds": 600 establece el intervalo de tiempo de espera de latido en 10 minutos. La tarea esperará a que el token de tarea se devuelva con una de estas acciones de la API:

Si la tarea en espera no recibe un token de tarea válido dentro de ese periodo de 10 minutos, se produce un error con el nombre States.Timeout en la tarea.

Para obtener más información, consulte el proyecto de ejemplo de devolución de llamada Creación de un ejemplo de patrón de devolución de llamada con Amazon SQS, Amazon SNS y Lambda.