Call API Gateway con Step Functions - 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.

Call API Gateway con Step Functions

Step Functions puede controlar ciertosAWSservicios directamente desde el Lenguaje de estados de Amazon. Para obtener más información acerca de cómo trabajar conAWS Step Functionsy sus integraciones, consulte los temas siguientes:

En qué se diferencia la integración de API Gateway optimizada de la API GatewayAWSIntegración de SDK
  • apigateway:invoke:no tiene equivalente en elAWSIntegración de servicios SDK. En su lugar, el servicio Optimized API Gateway llama directamente al endpoint de API Gateway.

Utiliza Amazon API Gateway para crear, publicar, mantener y monitorear API HTTP y REST. Para integrarse con API Gateway, defina unTaskestado en Step Functions que llama directamente a un extremo REST de API Gateway HTTP o API Gateway, sin escribir código ni depender de otra infraestructura. UNATaskla definición de estado incluye toda la información necesaria para la llamada a la API. También puede seleccionar distintos métodos de autorización.

nota

Step Functions admite la capacidad de llamar a puntos finales HTTP a través de API Gateway, pero actualmente no admite la posibilidad de llamar a puntos finales HTTP genéricos.

Compatibilidad con la función API Gateway

La integración de Step Functions API Gateway admite algunas, pero no todas las funciones de API Gateway. Para obtener una lista detallada de las características admitidas, consulte lo siguiente.

  • Compatible con las integraciones API REST API de Step Functions API Gateway y API Gateway HTTP:

    • Autorizadores: IAM (medianteSignature Version 4), Sin autorización, autorizadores Lambda (basados en parámetros de solicitud y basados en tokens con encabezado personalizado)

    • Tipos de API: regional

    • Administración de API: Nombres de dominio de API Gateway API, etapa de API, ruta, parámetros de consulta, cuerpo de solicitud

  • Compatible con la integración de API de Step Functions API Gateway, pero no por la integración de API Gateway REST de Step Functions API

    • API optimizadas para límites

  • No es compatible con la integración de Step Functions API Gateway:

    • Autorizadores: Amazon Cognito, Native Open ID Connect/OAuth 2.0, encabezado de autorización para autorizadores Lambda basados en tokens

    • Tipos de API: Private

    • Administración de API: Nombres de dominio personalizados

Para obtener más información acerca de API Gateway y sus API HTTP y REST, consulte lo siguiente.

Formato de las solicitudes

Cuando cree suTaskdefinición de estado, Step Functions valida los parámetros, crea la URL necesaria para realizar la llamada y, a continuación, llama a la API. La respuesta incluye el código de estado HTTP, los encabezados y el cuerpo de la respuesta. El formato de la solicitud tiene parámetros requeridos y opcionales.

Parámetros de solicitud requeridos

  • ApiEndpoint

    • Escriba: String

    • Nombre de host de una URL de API Gateway. El formato es el siguiente <API ID>.execute-api.<region>.amazonaws.com.

      El ID de API solo puede contener una combinación de los siguientes caracteres alfanuméricos:0123456789abcdefghijklmnopqrstuvwxyz

  • Method

    • Escriba: Enum

    • El método HTTP, que debe ser uno de los siguientes:

      • GET

      • POST

      • PUT

      • DELETE

      • PATCH

      • HEAD

      • OPTIONS

Parámetros de solicitud opcionales

  • Headers

    • Escriba: JSON

    • Los encabezados HTTP permiten una lista de valores asociados a la misma clave.

  • Stage

    • Escriba: String

    • Nombre de la etapa en la que se implementa la API en API Gateway. Es opcional para cualquier API HTTP que utilice el$defaultescenario.

  • Path

    • Escriba: String

    • Parámetros de ruta que se anexan después del punto final de la API.

  • QueryParameters

    • Escriba: JSON

    • Las cadenas de consulta permiten una lista de valores asociados a la misma clave.

  • RequestBody

    • Tipo: JSON o String

    • El cuerpo de la solicitud HTTP. Su tipo puede serJSONobjeto oString.RequestBodysolo se admite paraPATCH,POST, yPUTMétodos HTTP.

  • AllowNullValues

    • Escriba: BOOLEAN

    • Configuración deAllowNullValuesatruele permitirá pasar valores nulos como los siguientes:

      { "NewPet": { "type": "turtle", "price": 123, "name": null } }
  • AuthType

    • Escriba: JSON

    • El método de autenticación. El método predeterminado esNO_AUTH. Los valores permitidos son:

      • NO_AUTH

      • IAM_ROLE

      • RESOURCE_POLICY

      ConsulteAutenticación y autorizaciónpara obtener más información.

nota

Por motivos de seguridad, las siguientes claves de encabezado HTTP no están permitidas actualmente:

  • Cualquier cosa con el prefijoX-Forwarded,X-AmzoX-Amzn.

  • Authorization

  • Connection

  • Content-md5

  • Expect

  • Host

  • Max-Forwards

  • Proxy-Authenticate

  • Server

  • TE

  • Transfer-Encoding

  • Trailer

  • Upgrade

  • Via

  • Www-Authenticate

El siguiente ejemplo de código muestra cómo invocar API Gateway mediante Step Functions.

{ "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "GET", "Headers": { "key": ["value1", "value2"] }, "Stage": "prod", "Path": "bills", "QueryParameters": { "billId": ["123456"] }, "RequestBody": {}, "AuthType": "NO_AUTH" } }

Autenticación y autorización

Puede utilizar los siguientes métodos de autenticación:

  • Sin autorización: Llama a la API directamente sin método de autorización.

  • Rol de IAM: Con este método, Step Functions asume el papel de la máquina de estado, firma la solicitud conSignature Version 4(SigV4) y, a continuación, llama a la API.

  • Política de recursos: Step Functions autentica la solicitud y, a continuación, llama a la API. Debe adjuntar una política de recursos a la API que especifica lo siguiente:

    1. El equipo de estado que invocará API Gateway.

      importante

      Debe especificar el equipo de estado para limitar el acceso a ella. Si no lo hace, cualquier máquina de estado que autentica su solicitud API Gateway conPolítica de recursosse concederá acceso a la autenticación de su API.

    2. Ese Step Functions es el servicio que llama a API Gateway:"Service": "states.amazonaws.com".

    3. El recurso al que desea obtener acceso, incluidos:

      • Laregión.

      • Laaccount-iden la región especificada.

      • Laapi-id.

      • Lanombre de la fase.

      • LaVERBO HTTP-(método).

      • Laresource-path-specifier.

    Para ver una política de recursos de ejemplo, consultePolíticas de IAM para Step Functions y API Gateway.

    Para obtener más información sobre el formato de los recursos, consulteFormato de Resource de permisos para ejecutar la API en API Gatewayen la Guía para desarrolladores de API Gateway.

    nota

    Las políticas de recursos solo se admiten para la API REST.

Patrones de integración de servicios

La integración de API Gateway admite dos patrones de integración de servicios:

  • Respuesta de la solicitud, que es el patrón de integración predeterminado. Permite que Step Functions avance al siguiente paso inmediatamente después de recibir una respuesta HTTP.

  • Cómo esperar una devolución de llamada con el token de tarea(.waitForTaskToken), que espera hasta que se devuelva un token de tarea con una carga. Para utilizar el.waitForTaskTokenpatrón, anexar.waitForTaskToken al final delRecursode la definición de tareas, tal y como se muestra en el siguiente ejemplo:

    { "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "POST", "Headers": { "TaskToken.$": "States.Array($$.Task.Token)" }, "Stage": "prod", "Path": "bills/add", "QueryParameters": {}, "RequestBody": { "billId": "my-new-bill" }, "AuthType": "IAM_ROLE" } }

Formato de salida

Se proporcionan los siguientes parámetros de salida:

Nombre Tipo Descripción
ResponseBody JSON o String El cuerpo de respuesta de la llamada a la API.
Headers JSON Los encabezados de respuesta.
StatusCode Integer Código de estado HTTP de la respuesta.
StatusText String El texto del estado de la respuesta.

Respuesta de ejemplo:

{ "ResponseBody": { "myBills": [] }, "Headers": { "key": ["value1", "value2"] }, "StatusCode": 200, "StatusText": "OK" }

Control de errores

Cuando se produce un error, unerrorycausese devuelve de la siguiente manera:

  • Si el código de estado HTTP está disponible, el error se devolverá en el formatoApiGateway.<HTTP Status Code>.

  • Si el código de estado HTTP no está disponible, el error se devolverá en el formatoApiGateway.<Exception>.

En ambos casos, elcausese devuelve como una cadena.

El siguiente ejemplo muestra una respuesta en la que se ha producido un error:

{ "error": "ApiGateway.403", "cause": "{\"message\":\"Missing Authentication Token\"}" }
nota

Un código de estado de2XXindica que ha tenido éxito y no se devolverá ningún error. Todos los demás códigos de estado o excepciones emitidas provocarán un error.

Para obtener más información, consulte:

Conceptos de Amazon API Gatewayen la Guía para desarrolladores de API Gateway.