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.
Cree una API puerta de enlace REST APIs con Step Functions
Aprenda a usar Amazon API Gateway para crear, publicar, mantener y monitorear HTTP y REST APIs con Step Functions. Para la integración con API Gateway, debe definir un Task
estado en Step Functions que llame directamente a una API puerta de enlace HTTP o REST punto final de API puerta de enlace, sin escribir código ni depender de otra infraestructura. Una definición de Task
estado incluye toda la información necesaria para la API llamada. También puede seleccionar distintos métodos de autorización.
Para obtener información sobre la integración con AWS servicios en Step Functions, consulte Integración de los servicios de yPasar parámetros a un servicio API en Step Functions.
Características clave de la integración de Optimized API Gateway
-
apigateway:invoke:
no tiene equivalente en el AWS SDKintegración de servicios. En su lugar, el servicio Optimized API Gateway llama directamente a su terminal API Gateway.
APICompatibilidad con las funciones de Gateway
La integración de Step Functions API Gateway admite algunas funciones de API Gateway, pero no todas. Para obtener una lista más detallada de las características compatibles, consulte lo siguiente.
-
Compatible con las HTTP API integraciones Step Functions API API Gateway REST API y Gateway:
-
Autorizadores: IAM (con la versión 4 de Signature), sin autenticación, autorizadores Lambda (basados en parámetros de solicitud y basados en tokens con encabezado personalizado)
-
APItipos: regionales
-
APIadministración: nombres de API dominio de la API puerta de enlace, API etapa, ruta, parámetros de consulta, cuerpo de la solicitud
-
-
Compatible con la HTTP API integración de Step Functions API Gateway. No se admite la REST API integración de Step Functions API Gateway que ofrece la opción de optimización APIs perimetral.
-
No es compatible con la integración de Step Functions API Gateway:
-
Autorizadores: Amazon Cognito, Open ID ConnectOAuth/2.0 nativo, encabezado de autorización para autorizadores Lambda basados en tokens
-
APItipos: privados
-
APIadministración: nombres de dominio personalizados
-
Para obtener más información sobre API Gateway HTTP y su REST APIs banda, consulte lo siguiente.
-
La página de conceptos de Amazon API Gateway.
-
Elegir entre HTTP APIs y REST APIs en la guía para desarrolladores de API Gateway.
Formato de solicitudes
Al crear la definición de Task
estado, Step Functions valida los parámetros, crea los necesarios URL para realizar la llamada y, a continuación, llama alAPI. La respuesta incluye el código de HTTP estado, los encabezados y el cuerpo de la respuesta. El formato de solicitud tiene parámetros obligatorios y opcionales.
Parámetros de solicitud obligatorios
-
ApiEndpoint
-
Tipo:
String
-
El nombre de host de una API puerta de enlace. URL El formato es
.<API ID>
.execute-api.<region>
.amazonaws.comEl API ID solo puede contener una combinación de los siguientes caracteres alfanuméricos:
0123456789abcdefghijklmnopqrstuvwxyz
-
-
Method
-
Tipo:
Enum
-
El HTTP método, que debe ser uno de los siguientes:
-
GET
-
POST
-
PUT
-
DELETE
-
PATCH
-
HEAD
-
OPTIONS
-
-
Parámetros de solicitudes opcionales
-
Headers
-
Tipo:
JSON
-
HTTPlos encabezados permiten una lista de valores asociados a la misma clave.
-
-
Stage
-
Tipo:
String
-
El nombre de la etapa en la que API se implementa en API Gateway. Es opcional para cualquiera HTTP API que utilice el
$default
escenario.
-
-
Path
-
Tipo:
String
-
Parámetros de ruta que se añaden después del API punto final.
-
-
QueryParameters
-
Tipo:
JSON
-
Las cadenas de consulta solo permiten una lista de valores asociados a la misma clave.
-
-
RequestBody
-
Tipo:
JSON
oString
-
El cuerpo de la HTTP solicitud. Su tipo puede ser un
JSON
objeto oString
.RequestBody
solo se admite para losPUT
HTTP métodosPATCH
POST
, y.
-
-
AllowNullValues
-
Tipo:
BOOLEAN
— valor predeterminado:false
-
Con la configuración predeterminada, los valores nulos que se encuentren en el estado de entrada de la solicitud no se le enviaránAPI. En el siguiente ejemplo, el
category
campo no se incluirá en la solicitud, a menos queAllowNullValues
esté configuradotrue
en la definición de la máquina de estados.{ "NewPet": { "type": "turtle", "price": 123, "category": null } }
nota
De forma predeterminada, los campos con valores nulos en el estado de entrada de la solicitud no se le enviaránAPI. Puede forzar el envío de valores nulos API
AllowNullValues
configurándolotrue
en la definición de su máquina de estados.
-
-
AuthType
-
Tipo:
JSON
-
El método de autenticación. El método predeterminado es
NO_AUTH
. Los valores permitidos son:-
NO_AUTH
-
IAM_ROLE
-
RESOURCE_POLICY
Para obtener más información, consulte Autenticación y autorización.
-
-
nota
Por motivos de seguridad, actualmente no se permiten las siguientes claves de HTTP encabezado:
-
Cualquiera que tenga 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 usar los siguientes métodos de autenticación:
-
Sin autorización: llame API directamente al método sin autorización.
-
IAMrol: Con este método, Step Functions asume el papel de máquina de estados, firma la solicitud con Signature Version 4 (SiGv4) y, a continuación, llama alAPI.
-
Política de recursos: Step Functions autentica la solicitud y, a continuación, llama alAPI. Debe adjuntar una política de recursos API que especifique lo siguiente:
-
La máquina de estados que invocará a API Gateway.
importante
Debe especificar su máquina de estado para limitar el acceso a ella. Si no lo hace, se API concederá acceso a cualquier máquina de estado que autentique su solicitud de API Gateway con la autenticación de la política de recursos dirigida a usted.
-
Ese Step Functions es el servicio que llama a API Gateway:
"Service": "states.amazonaws.com"
. -
El recurso al que desea obtener acceso, que incluye:
-
La
region
. -
La
account-id
en la región especificada. -
La
api-id
. -
La
stage-name
. -
La
HTTP-VERB
(método). -
La
resource-path-specifier
.
-
Para ver un ejemplo de política de recursos, consulte IAMlas políticas de Step Functions y API Gateway.
Para obtener más información sobre el formato de los recursos, consulte el formato de recursos de los permisos para ejecutar API en API Gateway en la Guía para desarrolladores de API Gateway.
nota
Las políticas de recursos solo se admiten para RESTAPI.
-
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 HTTP respuesta.
-
Espera a que te devuelvan la llamada con el token de tarea (
.waitForTaskToken
), que espera a que se devuelva un token de tarea con una carga. Para usar el.waitForTaskToken
patrón, añada. waitForTaskSímbolo al final del campo de recursos de la definición de la tarea, 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
Debe proporcionar los siguientes parámetros de salida:
Nombre | Tipo | Descripción |
---|---|---|
ResponseBody |
JSON o String |
El cuerpo de la respuesta de la API llamada. |
Headers |
JSON |
Encabezados de respuesta. |
StatusCode |
Integer |
El código de HTTP estado de la respuesta. |
StatusText |
String |
Texto de 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, se devuelve error
y cause
de la siguiente manera:
-
Si el código de HTTP estado está disponible, el error se devolverá en el formato
ApiGateway.
.<HTTP Status Code>
-
Si el código de HTTP estado no está disponible, el error se devolverá en el formato
ApiGateway.
.<Exception>
En ambos casos, cause
se devuelve como una cadena.
En el siguiente ejemplo se 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 de 2XX
indica que se ha realizado correctamente y no se devolverá ningún error. El resto de códigos de estado o excepciones emitidas generarán un error.
IAMpolíticas para llamadas a Amazon API Gateway
En las siguientes plantillas de ejemplo se muestra cómo AWS Step Functions genera IAM políticas en función de los recursos de la definición de su máquina de estados. Para obtener más información, consulte Cómo Step Functions genera IAM políticas para servicios integrados y Descubra los patrones de integración de servicios en Step Functions.
Recursos:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:[[region]]
:[[accountId]]
:*"
]
}
]
}
El siguiente ejemplo de código muestra una política de recursos para llamar a API Gateway.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "states.amazonaws.com"
},
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:<region>
:<account-id>
:<api-id>
/<stage-name>
/<HTTP-VERB>
/<resource-path-specifier>
",
"Condition": {
"StringEquals": {
"aws:SourceArn": [
"<SourceStateMachineArn>
"
]
}
}
}
]
}