Compatibilidad con la función API Gateway Formato de las solicitudes Autenticación y autorización Patrones de integración de servicios Formato de salida Control de errores

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.

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 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.
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.

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

Amazon EKS

AWS Glue DataBrew