Compatibilidad con características de API Gateway Formato de las solicitudes Autenticación y autorización Patrones de integración de servicios Formato de salida Gestión de errores Políticas de IAM

Cree API Gateway REST APIs con Step Functions

Aprenda a utilizar Amazon API Gateway para crear, publicar, mantener y supervisar HTTP y REST APIs con Step Functions. Para la integración con API Gateway, se debe definir un estado Task en Step Functions que llame directamente a un punto de conexión HTTP o REST de API Gateway, sin necesidad de escribir código ni depender de otra infraestructura. Una definición de estado Task incluye toda la información necesaria para la llamada a la API. También puede seleccionar distintos métodos de autorización.

Para obtener más información sobre la integración con AWS los servicios de Step Functions, consulte Integración de los servicios de yCómo pasar parámetros a una API de servicio en Step Functions.

Características principales de la integración optimizada de API Gateway

apigateway:invoke:no tiene equivalente en la integración de servicios del AWS SDK. En su lugar, el servicio optimizado de API Gateway llama directamente a su punto de conexión de API Gateway.

Compatibilidad con características de API Gateway

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

Compatible con las integraciones de la API de REST y HTTP de API Gateway de Step Functions:
- Autorizadores: IAM (con Signature Version 4), sin autenticación, autorizadores Lambda (basados en parámetros de solicitud y basados en tokens con encabezado personalizado)
- Tipos de API: regionales
- Administración de API: nombres de dominio de API Gateway, etapa de API, ruta, parámetros de consulta, cuerpo de la solicitud
Compatible con la integración de la API de HTTP de API Gateway de Step Functions. No se admite la integración de la API REST de Step Functions API Gateway que ofrece la opción de optimización APIs perimetral.
No compatible con la integración de la API Gateway de Step Functions:
- Autorizadores: Amazon Cognito, Open ID Connect OAuth /2.0 nativo, encabezado de autorización para autorizadores Lambda basados en tokens
- Tipos de API: privadas
- Administración de API: nombres de dominio personalizados

Para obtener más información sobre API Gateway y sus protocolos HTTP y REST APIs, consulte lo siguiente.

La página Conceptos de Amazon API Gateway.
Cómo elegir entre HTTP APIs y REST APIs en la guía para desarrolladores de API Gateway.

Formato de las solicitudes

Al crear la definición de estado Task, Step Functions valida los parámetros, genera la URL necesaria para realizar la llamada y, posteriormente, llama a la API. La respuesta incluye el código de estado HTTP, los encabezados y el cuerpo de 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 URL de API Gateway. El formato es <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
- Tipo: Enum
- El método HTTP, que debe ser uno de los siguientes:
  - GET
  - POST
  - PUT
  - DELETE
  - PATCH
  - HEAD
  - OPTIONS

Parámetros de solicitudes opcionales

Headers
- Tipo: JSON
- Los encabezados HTTP permiten una lista de valores asociados a la misma clave.
Stage
- Tipo: String
- El nombre de la fase en la que se implementa la API en API Gateway. Es opcional para cualquier API de HTTP que utilice la fase $default.
Path
- Tipo: String
- Parámetros de ruta que se anexan después del punto de conexión de la API.
QueryParameters
- Tipo: JSON
- Las cadenas de consulta solo permiten una lista de valores asociados a la misma clave.
RequestBody
- Tipo: JSON o String
- El cuerpo de la solicitud HTTP Su tipo puede ser un objeto JSON oString. RequestBody solo es compatible con los métodos HTTP PATCH, POST y PUT.
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 enviarán a su API. En el siguiente ejemplo, el campo category no se incluirá en la solicitud, a menos que AllowNullValues esté configurado como true en la definición de la máquina de estado.
```
{
    "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 enviarán a su API. Puede forzar el envío de valores nulos a su API configurando AllowNullValues como true en su definición de máquina de estado.
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 encabezado HTTP:

Cualquiera que tenga el prefijo X-Forwarded, X-Amz o X-Amzn.
Authorization
Connection
Content-md5
Expect
Host
Max-Forwards
Proxy-Authenticate
Server
TE
Transfer-Encoding
Trailer
Upgrade
Via
Www-Authenticate

En el siguiente ejemplo de código se muestra cómo invocar API Gateway mediante Step Functions.


{
    "Type": "Task", 
    "Resource":"arn:aws:states:::apigateway:invoke", 
    "Arguments": {
        "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: llama a la API directamente sin ningún método de autorización.
Rol de IAM: con este método, Step Functions asume el rol de la máquina de estado, firma la solicitud con Signature Version 4 (SiGv4) y, posteriormente, llama a la API.
Política de recursos: Step Functions autentica la solicitud y luego llama a la API. Debe adjuntar una política de recursos a la API que especifique lo siguiente:
1. La máquina de estado que invocará API Gateway.
  
  importante
  Debe especificar su máquina de estado para limitar el acceso a ella. Si no lo hace, se 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 en su API.
2. Esa Step Functions es el servicio que llama a API Gateway: "Service": "states.amazonaws.com".
3. El recurso al que desea obtener acceso, que incluye:
  - La region.
  - account-idEn la región especificada.
  - La api-id.
  - La stage-name.
  - El HTTP-VERB (método).
  - La resource-path-specifier.
Para ver una política de recursos de ejemplo, consulte las Políticas de IAM para Step Functions y API Gateway.

Para obtener más información acerca del formato de recursos, consulte Formato de Resource de permisos para ejecutar la API en API Gateway en la Guía para desarrolladores de API Gateway.

nota
Las políticas de recursos solo se admiten en la API de 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 justo después de recibir una respuesta HTTP.

Cómo esperar una devolución de 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", 
    "Arguments": {
        "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
        "Method": "POST", 
        "Headers": { 
            "TaskToken": "{% $states.context.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`	Cuerpo de la respuesta de la llamada a la API.
`Headers`	`JSON`	Encabezados de respuesta.
`StatusCode`	`Integer`	Código de estado HTTP de la respuesta.
`StatusText`	`String`	Texto de estado de la respuesta.

Respuesta de ejemplo:


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

Gestión de errores

Cuando se produce un error, se devuelve error y cause 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, 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.

Políticas de IAM para llamadas a Amazon API Gateway

En las siguientes plantillas de ejemplo, se muestra cómo se AWS Step Functions generan las políticas de IAM en función de los recursos de la definición de su máquina de estados. Para obtener más información, consulte Generación de políticas de IAM para servicios integrados por Steps Functions y Descubrimiento de 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:account-id:*"
            ]
        }
    ]
}

En el siguiente ejemplo de código se 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>"
                    ]
                }
            }
        }
    ]
}

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Integración de los servicios optimizados

Amazon Athena

Cree API Gateway REST APIs con Step Functions

Características principales de la integración optimizada de API Gateway

Compatibilidad con características de API Gateway

Formato de las solicitudes

Parámetros de solicitud obligatorios

Parámetros de solicitudes opcionales

nota

nota

Autenticación y autorización

importante

nota

Patrones de integración de servicios

Formato de salida

Gestión de errores

nota

Políticas de IAM para llamadas a Amazon API Gateway