Patrones de integración de servicios - AWS Step Functions

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Patrones de integración de servicios

AWS Step Functionsse integra con los servicios directamente en el Lenguaje de estados de Amazon. Puede controlar estos servicios de AWS mediante tres patrones de integración de servicios:

  • Llame a un servicio y deje que Step Functions avanza al siguiente estado de manera inmediata después de que obtenga una respuesta HTTP.

  • Llame a un servicio y haga que Step Functions espere a que finalice un trabajo.

  • Llame a un servicio con un token de tarea y haga que Step Functions espere hasta que se devuelva dicho token con una carga.

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.

Para obtener información acerca de cómo configurarAWS Identity and Access Management(IAM) para los servicios integrados, consultePolíticas de IAM para servicios integrados.

nota

Las invocaciones de Lambda utilizarán el.syncpatrón de integración de servicios, incluso si no lo especificó. Si desea invocar Lambda de forma asíncrona, puede utilizar elInvocationTypeparámetro. Para obtener más información, consulteInvocar Lambda con Step Functions

Respuesta de la solicitud

Cuando especifica un servicio en el"Resource"cadena del estado de su tarea, y ustedsóloProporciona el recurso, Step Functions esperará una respuesta HTTP y, a continuación, avanzará al siguiente estado. Step Functions no esperará a que finalice un trabajo.

El siguiente ejemplo 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:us-east-1:123456789012:myTopic", "Message":"Hello from Step Functions!" }, "Next":"NEXT_STATE" }

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

Ejecutar un trabajo (.sync)

Para servicios integrados tales comoAWS Batchy Amazon ECS, Step Functions puede esperar a que finalice una solicitud antes de avanzar al siguiente estado. Para que Step Functions espere, especifique la"Resource"en la definición del estado de la tarea con el.syncsufijo anexado después del URI del recurso.

Por ejemplo, al enviar unAWS Batchtrabajo, utilice el"Resource"en la definición de 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 el.syncparte 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 submitJob de AWS Batch, 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 Job Batch (AWS Batch, Amazon SNS).

Si se trata de una tarea que utiliza esto (.sync) se ha anulado el patrón de integración de servicios y Step Functions no puede cancelar la tarea, podría incurrir en cargos adicionales por parte del servicio integrado. Se puede anular una tarea si:

  • La ejecución de la máquina de estado se detiene.

  • Una rama diferente de un estado paralelo falla con un error no detectado.

  • La iteración de un estado de mapa falla con un error no detectado.

Step Functions hará el mejor esfuerzo para cancelar la tarea. Por ejemplo, si un Step Functionsstates:startExecution.syncse cancela, llamará a Step FunctionsStopExecutionAcción de la API. Sin embargo, es posible que Step Functions no pueda cancelar la tarea. Entre los motivos de esto se incluyen, entre otros:

  • El rol de ejecución de IAM carece de permiso para realizar la llamada a la API correspondiente.

  • Se ha producido una interrupción temporal del servicio.

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

nota

Integraciones de servicios que utilizan el.syncEl patrón requiere permisos de IAM adicionales. Para obtener más información, consulte Políticas de IAM para servicios integrados.

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 detener las Step Functions de manera indefinida y esperar a que finalice un proceso externo o un flujo de trabajo. En estas situaciones, las Step Functions le permiten pasar un token de tarea aAWSIntegraciones de servicios SDK y también a algunos servicios integrados de integraciones optimizadas. La tarea se detendrá hasta que se reciba dicho token de tarea de nuevo con una llamada SendTaskSuccess o SendTaskFailure.

Para utilizar.waitForTaskTokencon unAWSIntegración del SDK, la API que utiliza 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 Integraciones optimizadas para Step Functions.

Ejemplo de token de tarea

En este ejemplo, un flujo de trabajo de Step Functions de ha de 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 extrae el mensaje de la cola. Cuando haya terminado, devuelve el resultado y el token de tarea original. Step Functions continúa con su flujo de trabajo.


            Tarea de SQS a la espera de que se devuelva un token de tarea

La"Resource"de la definición de tarea que hace referencia a Amazon SQS incluye.waitForTaskTokenanexado 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 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.

nota

Para evitar la espera de forma indefinida si un proceso no envía el token de tarea con SendTaskSuccess o SendTaskFailure, consulte Cómo configurar un tiempo de espera de latido para una tarea en espera.

Cómo obtener 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:us-east-1:123456789012:execution:stateMachineName:executionName", "Input": { "key": "value" }, "Name": "executionName", "RoleArn": "arn:aws:iam::123456789012: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:us-east-1:123456789012: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, anexar.$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,.waitForTaskTokenen la"Resource"indica a Step Functions que espere a que se devuelva el token de tarea. La"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 Objeto Context en la sección Procesamiento de entrada y salida 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 estatal). 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 Ejemplo de patrón de devolución de llamadas (Amazon SQS, Amazon SNS, Lambda) .