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:
-
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 unTask
estado 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. UNATask
la 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.
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.
-
LaConceptos de Amazon API Gateway(Se ha creado el certificado).
-
Elección entre API HTTP y API de RESTen la guía para desarrolladores de API Gateway.
Formato de las solicitudes
Cuando cree suTask
definició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.comEl 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
$default
escenario.
-
-
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
oString
-
El cuerpo de la solicitud HTTP. Su tipo puede ser
JSON
objeto oString
.RequestBody
solo se admite paraPATCH
,POST
, yPUT
Métodos HTTP.
-
-
AllowNullValues
-
Escriba:
BOOLEAN
-
Configuración de
AllowNullValues
atrue
le 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 es
NO_AUTH
. Los valores permitidos son:-
NO_AUTH
-
IAM_ROLE
-
RESOURCE_POLICY
ConsulteAutenticación y autorizaciónpara obtener más información.
-
-
Por motivos de seguridad, las siguientes claves de encabezado HTTP no están permitidas actualmente:
-
Cualquier cosa con el prefijo
X-Forwarded
,X-Amz
oX-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:
-
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.
-
Ese Step Functions es el servicio que llama a API Gateway:
"Service": "states.amazonaws.com"
. -
El recurso al que desea obtener acceso, incluidos:
-
La
región
. -
La
account-id
en la región especificada. -
La
api-id
. -
La
nombre de la fase
. -
La
VERBO HTTP-
(método). -
La
resource-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.waitForTaskToken
patró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, unerror
ycause
se devuelve de la siguiente manera:
-
Si el código de estado HTTP está disponible, el error se devolverá en el formato
ApiGateway.
.<HTTP Status Code>
-
Si el código de estado HTTP no está disponible, el error se devolverá en el formato
ApiGateway.
.<Exception>
En ambos casos, elcause
se 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\"}" }
Un código de estado de2XX
indica 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.
-
Políticas de IAM para Step Functions yAmazon API Gateway
-
Un proyecto de ejemplo que muestra cómoRealizar una llamada a API Gateway
Conceptos de Amazon API Gatewayen la Guía para desarrolladores de API Gateway.