Trabajar con etapas para API HTTP - Amazon API Gateway
Variables de etapaReferencia de variables de etapa

Trabajar con etapas para API HTTP

Una referencia lógica a un estado del ciclo de vida de la API (por ejemplo, dev, prod, beta o v2). Las etapas de API se identifican por su ID de API y su nombre de etapa, y se incluyen en la URL que utiliza para invocar la API. Cada etapa es una referencia con nombre a una implementación de la API y está disponible para que las aplicaciones cliente la invoquen.

Puede crear una etapa $default que se ofrezca desde la base de la URL de su API, por ejemplo, https://{api_id}.execute-api.{region}.amazonaws.com/. Utilice esta URL para invocar una etapa de la API.

Una implementación es una instantánea de la configuración de la API. Después de implementar una API en una etapa, esta está disponible para que los clientes la invoquen. Debe implementar una API para que los cambios surtan efecto. Si habilita implementaciones automáticas, los cambios realizados en una API se liberarán automáticamente.

Variables de etapa

Las variables de etapa son pares clave-valor que se pueden definir para una etapa de una API HTTP. Actúan como variables de entorno y se pueden usar en la configuración de la API.

Por ejemplo, puede definir una variable de etapa y, a continuación, establecer su valor como extremo HTTP para una integración de proxy HTTP. Posteriormente, puede hacer referencia al punto de enlace mediante el nombre de variable de etapa asociada. Al hacer esto, puede usar la misma configuración de API con un punto de enlace diferente en cada etapa. Del mismo modo, puede utilizar variables de etapa para especificar una integración de funciones de AWS Lambda diferente para cada etapa de su API.

nota

Las variables de etapa no están pensadas a fin de ser utilizadas para datos confidenciales, como credenciales. Para transferir información confidencial a las integraciones, utilice un autorizador de AWS Lambda. Puede pasar datos confidenciales a integraciones en la salida del autorizador de Lambda. Para obtener más información, consulte Formato de respuesta del autorizador de Lambda.

Ejemplos

Para utilizar una variable de etapa para personalizar el punto de enlace de integración HTTP, primero debe establecer el nombre y el valor de la variable de etapa (por ejemplo, url) con un valor de example.com. A continuación, configure una integración de proxy HTTP. En lugar de escribir la URL del punto de enlace, puede indicar a API Gateway que use el valor de la variable de etapa, http://${stageVariables.url}. Este valor indica a API Gateway que sustituya la variable de etapa ${} en el tiempo de ejecución en función de la etapa de la API.

Puede hacer referencia a variables de etapa de una manera similar para especificar el nombre de una función de Lambda o el ARN de un rol de AWS.

Cuando especifica el nombre de una función de Lambda como un valor de variable de etapa, debe configurar manualmente los permisos en la función de Lambda. Para ello, puede utilizar la AWS Command Line Interface (AWS CLI).

aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction

Referencia de variables de etapa de API Gateway

URI de integración HTTP

Puede utilizar una variable de etapa como parte de una URI de integración HTTP, tal y como se muestra en los siguientes ejemplos.

  • Una URI completa sin protocol – http://${stageVariables.<variable_name>}

  • Un dominio complet – http://${stageVariables.<variable_name>}/resource/operation

  • Un subdomini – http://${stageVariables.<variable_name>}.example.com/resource/operation

  • Una rut – http://example.com/${stageVariables.<variable_name>}/bar

  • Una cadena de consult – http://example.com/foo?q=${stageVariables.<variable_name>}

Funciones de Lambda

Puede utilizar una variable de etapa en lugar de un nombre o alias de integración de una función de Lambda, como se muestra en los ejemplos siguientes.

  • arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:${stageVariables.<function_variable_name>}/invocations

  • arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:<function_name>:${stageVariables.<version_variable_name>}/invocations

nota

Para utilizar una variable de etapa para una función de Lambda, la función debe estar en la misma cuenta que la API. Las variables de etapa no admiten funciones de Lambda entre cuentas.

AWSCredenciales de integración de

Puede utilizar una variable de etapa como parte de un ARN de credenciales de usuario o rol de AWS, como se muestra en el siguiente ejemplo.

  • arn:aws:iam::<account_id>:${stageVariables.<variable_name>}