# Uso de variables de etapa para una API de REST en API Gateway
Las variables de etapa son pares clave-valor que puede definir como atributos de configuración asociados a una etapa de implementación de una API de REST. Actúan como variables de entorno y se pueden usar en la configuración y las plantillas de asignación de la API. Las etapas de implementación de API Gateway le permiten administrar varias etapas de versión para cada API y usar variables de etapa. Puede configurar una etapa de implementación de API para interactuar con distintos puntos de conexión de backend.
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 [Salida de un autorizador de Lambda de API Gateway](api-gateway-lambda-authorizer-output.md).
## Casos de uso de variables de etapa
A continuación, se indican los casos de uso de las variables de etapa.
**Especificación de un punto de conexión de backend diferente**
La API puede enviar una solicitud `GET` como un proxy HTTP al host web del backend). Puede usar una variable de etapa de modo que, cuando los intermediarios de la API invoquen su punto de conexión de producción, API Gateway llama a `example.com`. A continuación, cuando los intermediarios de la API invocan la etapa beta, API Gateway llama a un host web diferente, como `beta.example.com`. Asimismo, se pueden utilizar variables de etapa para especificar otro nombre de función de AWS Lambda para cada etapa de la API. No puede usar una variable de etapa para establecer un punto de conexión de integración diferente, como dirigir la solicitud `GET` a una integración de proxy HTTP en una etapa y a una integración de proxy Lambda en otra etapa.
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. Al especificar una función de Lambda en la consola de API Gateway, aparecerá un comando de la AWS CLI para configurar los permisos adecuados. También puede usar el siguiente comando de la AWS CLI para hacerlo.
```
aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
**Transferencia de la información mediante plantillas de asignación**
Puede tener acceso a las variables de etapa de las plantillas de asignación o transferir parámetros de configuración al backend de AWS Lambda o HTTP. Por ejemplo, es posible que desee volver a utilizar la misma función de Lambda para varias etapas de la API, pero la función debe leer los datos de una tabla de Amazon DynamoDB diferente según la etapa. En las plantillas de mapeo que generan la solicitud de la función de Lambda, puede utilizar variables de etapa para pasar el nombre de la tabla a Lambda.
Para usar una variable de etapa, primero configure una variable de etapa y, a continuación, asígnele un valor. Por ejemplo, para personalizar el punto de conexión de integración de HTTP, primero cree la variable de etapa `url` y, a continuación, en la solicitud de integración de la API, especifique el valor de la variable de etapa, **http://\$1\$1stageVariables.url\$1**. Este valor indica a API Gateway que sustituya la variable de etapa `${}` en el tiempo de ejecución según la etapa que esté ejecutando la API. Para obtener más información, consulte [Configuración de variables de etapa para las API de REST en API Gateway](how-to-set-stage-variables-aws-console.md).
# Configuración de variables de etapa para las API de REST en API Gateway
En esta sección se muestra cómo diferentes configurar variables de etapa para dos etapas de implementación de una API de muestra mediante la consola de Amazon API Gateway. Para entender cómo usar las variables de etapa en API Gateway, le recomendamos que siga todos los procedimientos de esta sección.
## Requisitos previos
Antes de comenzar, asegúrese de que se cumplen los siguientes requisitos previos:
+ Debe tener una API disponible en API Gateway. Siga las instrucciones en [Desarrollo de las API de REST en API Gateway](rest-api-develop.md).
+ Debe haber implementado la API al menos una vez. Siga las instrucciones en [Implementación de las API de REST en API Gateway](how-to-deploy-api.md).
+ Debe haber creado la primera etapa de una API implementada. Siga las instrucciones en [Creación de una nueva etapa](set-up-stages.md#how-to-create-stage-console).
## Invocación de un punto de conexión HTTP a través de una API con una variable de etapa
En este procedimiento se describe cómo crear una variable de etapa para un punto de conexión HTTP y dos etapas para la API. Además, creará las variables de etapa `url`, `stageName` y `function` que se utilizan en los siguientes procedimientos de esta sección.
**Invocación de un punto de conexión HTTP a través de una API con una variable de etapa**
1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Cree una API y cree un método `GET` en el recurso raíz de la API. Establezca el tipo de integración en **HTTP** y la **URL del punto de conexión** en **http://\$1\$1stageVariables.url\$1**.
1. Implemente la API en una nueva etapa llamada **beta**.
1. En el panel de navegación principal, elija **Etapas** y, a continuación, elija la etapa **beta**.
1. En la pestaña **Variables de etapa**, elija **Editar**.
1. Elija **Agregar variable de etapa**.
1. En **Nombre**, escriba **url**. En **Valor**, ingrese **httpbin.org/get**.
1. Elija **Agregar variable de etapa** y, a continuación, haga lo siguiente:
En **Nombre**, escriba **stageName**. En **Valor**, ingrese **beta**.
1. Elija **Agregar variable de etapa** y, a continuación, haga lo siguiente:
En **Nombre**, escriba **function**. En **Valor**, ingrese **HelloWorld**.
1. Seleccione **Guardar**.
1. Ahora cree una segunda etapa. En el panel de navegación **Etapas**, elija **Crear etapa**. En **Stage name (Nombre de etapa)**, escriba **prod**. Seleccione una implementación reciente en **Implementación** y, a continuación, elija **Crear etapa**.
1. Al igual que con la etapa **beta**, establezca las mismas tres variables de etapa (**url**, **stageName** y **function**) en diferentes valores (**petstore-demo-endpoint.execute-api.com/petstore/pets**, **prod** y **HelloEveryone**), respectivamente.
1. En el panel de navegación **Stages (Etapas)**, elija **beta**. En **Detalles de la etapa**, elija el icono de copiar para copiar la URL de invocación de la API y, a continuación, ingrese la URL de invocación de la API en un navegador web. Comenzará la solicitud `GET` de la etapa **beta** en el recurso raíz de la API.
**nota**
El enlace **Invoke URL (Invocar URL)** apunta al recurso raíz de la API en su etapa **beta**. Al ingresar la dirección URL en un navegador web se llama al método `GET` de la etapa **beta** en el recurso raíz. Si los métodos se definen en recursos secundarios y no en el propio recurso raíz, al ingresar la URL en un navegador web se devuelve una respuesta de error `{"message":"Missing Authentication Token"}`. En este caso, debe añadir el nombre de un recurso secundario específico al enlace **Invoke URL (Invocar URL)**.
1. La respuesta obtenida de la solicitud `GET` de la etapa **beta** se muestra a continuación. También puede verificar el resultado usando un navegador para ir a **http://httpbin.org/get**. Este valor se asignó a la variable `url` en la etapa **beta**. Las dos respuestas son idénticas.
1. En el panel de navegación **Stages (Etapas)**, elija la etapa **prod**. En **Detalles de la etapa**, elija el icono de copiar para copiar la URL de invocación de la API y, a continuación, ingrese la URL de invocación de la API en un navegador web. Comenzará la solicitud `GET` de la etapa **prod** en el recurso raíz de la API.
1. La respuesta obtenida de la solicitud `GET` de la etapa **prod** se muestra a continuación. También puede verificar el resultado usando un navegador para ir a **http://petstore-demo-endpoint.execute-api.com/petstore/pets**. Este valor se asignó a la variable `url` en la etapa **prod**. Las dos respuestas son idénticas.
## Transferencia de metadatos específicos de la etapa a un backend HTTP
Este procedimiento describe cómo utilizar el valor de una variable de etapa en una expresión de parámetro de consulta para pasar los metadatos específicos en una etapa a un backend HTTP. Utilizaremos la variable de etapa `stageName` declarada en el procedimiento anterior.
**Transferencia de metadatos específicos de la etapa a un backend HTTP**
1. En el panel de navegación **Resource (Recurso)**, elija el método **GET**.
Para agregar un parámetro de cadena de consulta a la URL del método, elija la pestaña **Solicitud de método** y, a continuación, en la sección **Configuración de solicitud de método**, elija **Editar**.
1. Elija **Parámetros de cadenas de consulta de URL** y haga lo siguiente:
1. Elija **Add query string (Añadir cadena de consulta)**.
1. En **Nombre**, escriba **stageName**.
1. Mantenga desactivados **Obligatorio** y **Almacenamiento en caché**.
1. Seleccione **Guardar**.
1. Elija la pestaña **Solicitud de integración** y, a continuación, en la sección **Configuración de solicitud de integración**, elija **Editar**.
1. En **URL del punto de conexión**, anexe **?stageName=\$1\$1stageVariables.stageName\$1** al valor de URL definido previamente, de modo que toda la **URL del punto de conexión** sea **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1**.
1. Elija **Implementar API** y seleccione la etapa **beta**.
1. En el panel de navegación principal, elija **Etapas**. En el panel de navegación **Stages (Etapas)**, elija **beta**. En **Detalles de la etapa**, elija el icono de copiar para copiar la URL de invocación de la API y, a continuación, ingrese la URL de invocación de la API en un navegador web.
**nota**
Utilizamos la etapa beta aquí porque el punto de conexión HTTP, tal como lo especifica la variable `url`, "http://httpbin.org/get", acepta expresiones de parámetro de consulta y las devuelve como el objeto `args` en su respuesta.
1. Obtendrá la siguiente respuesta. Observe que el valor `beta`, asignado a la variable de etapa `stageName`, se transmite al backend como el argumento `stageName`.
![\[Respuesta del método GET de la API con un punto de conexión HTTP mediante la variable de etapa de la url.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)
## Invocación de una función de Lambda a través de una API con una variable de etapa
Este procedimiento describe cómo utilizar una variable de etapa para llamar a una función de Lambda como un backend de la API. Utilice la variable de etapa `function` declarada en [Invocación de un punto de conexión HTTP a través de una API con una variable de etapa](#how-to-set-stage-variables-aws-console-http-endpoint).
Cuando configure una función de Lambda como el valor de una variable de etapa, utilice el nombre local de la función y, si es posible, incluya su alias o especificación de la versión, como en **HelloWorld**, **HelloWorld:1** o **HelloWorld:alpha**. No utilice el ARN de la función (por ejemplo, **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**). La consola de API Gateway asume que el valor de la variable de etapa de una función de Lambda es el nombre incompleto de la función y expande la variable de etapa especificada en un ARN.
**Invocación de una función de Lambda a través de una API con una variable de etapa**
1. Cree una función de Lambda llamada **HelloWorld** mediante el tiempo de ejecución predeterminado de Node.js. El código debe contener lo siguiente:
```
export const handler = function(event, context, callback) {
if (event.stageName)
callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
else
callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
};
```
Para obtener más información sobre cómo crear una función de Lambda, consulte [Introducción a la consola de la API de REST](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function).
1. En el panel **Recursos**, seleccione **Crear recurso** y, a continuación, haga lo siguiente:
1. En **Ruta de recurso**, seleccione **/**.
1. En **Nombre del recurso**, escriba **lambdav1**.
1. Elija **Crear recurso**.
1. Elija el recurso **/lambdav1** y, a continuación, elija **Crear método**.
A continuación, proceda del modo siguiente:
1. En **Tipo de método**, seleccione **GET**.
1. En **Tipo de integración**, seleccione **Función de Lambda**.
1. Mantenga desactivada la **Integración de proxy Lambda**.
1. En **Función Lambda**, introduzca `${stageVariables.function}`.
![\[Cree un método GET integrado con una función de Lambda tal como lo especifica la variable de etapa function.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**sugerencia**
Cuando se le solicite con el **comando Agregar permiso**, copie el comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Ejecute el comando en cada función de Lambda que se vaya a asignar a la variable de etapa `function`. Por ejemplo, si el valor `$stageVariables.function` es `HelloWorld`, ejecute el siguiente comando de la AWS CLI:
```
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
```
En caso contrario, se producirá una respuesta `500 Internal Server Error` al llamar al método. Sustituya `${stageVariables.function}` por el nombre de la función de Lambda asignada a la variable de etapa.
![\[Comando AWS CLI para agregar permiso a la función de Lambda que va a invocar el método que ha creado.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)
1. Elija **Crear método**.
1. Implemente la API en las etapas **prod** y **beta**.
1. En el panel de navegación principal, elija **Etapas**. En el panel de navegación **Stages (Etapas)**, elija **beta**. En **Detalles de la etapa**, elija el icono de copiar para copiar la URL de invocación de la API y, a continuación, ingrese la URL de invocación de la API en un navegador web. Anexe **/lambdav1** a la URL antes de pulsar Intro.
Obtendrá la siguiente respuesta.
```
"Hello, World! I'm not sure where I'm calling from..."
```
## Transferencia de metadatos específicos de una etapa a una función de Lambda a través de una variable de etapa
Este procedimiento describe cómo utilizar una variable de etapa para pasar metadatos de configuración específicos de una etapa a funciones de Lambda. Usted crea un método `POST` y una plantilla de mapeo de entrada para generar la carga mediante la variable de etapa `stageName` declarada anteriormente.
**Transferencia de metadatos específicos de la etapa a una función de Lambda a través de una variable de etapa**
1. Elija el recurso **/lambdav1** y, a continuación, elija **Crear método**.
A continuación, proceda del modo siguiente:
1. En **Tipo de método**, seleccione **POST**.
1. En **Tipo de integración**, seleccione **Función de Lambda**.
1. Mantenga desactivada la **Integración de proxy Lambda**.
1. En **Función Lambda**, introduzca `${stageVariables.function}`.
1. Cuando se le solicite con el **comando Agregar permiso**, copie el comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html). Ejecute el comando en cada función de Lambda que se vaya a asignar a la variable de etapa `function`.
1. Elija **Crear método**.
1. Elija la pestaña **Solicitud de integración** y, a continuación, en la sección **Configuración de solicitud de integración**, elija **Editar**.
1. Elija **Plantillas de mapeo** y, a continuación, elija **Agregar plantilla de mapeo**.
1. En **Tipo de contenido**, ingrese **application/json**.
1. En **Cuerpo de la plantilla**, ingrese la siguiente plantilla:
```
#set($inputRoot = $input.path('$'))
{
"stageName" : "$stageVariables.stageName"
}
```
**nota**
En una plantilla de asignación, se debe hacer referencia a una variable de etapa entre comillas (como en `"$stageVariables.stageName"` o `"${stageVariables.stageName}"`). En otros lugares, debe referenciarse sin comillas (como en `${stageVariables.function}`).
1. Seleccione **Guardar**.
1. Implemente la API en las etapas **beta** y **prod**.
1. Para usar un cliente de API de REST para transferir metadatos específicos de la etapa, haga lo siguiente:
1. En el panel de navegación **Stages (Etapas)**, elija **beta**. En **Detalles de la etapa**, elija el icono de copiar para copiar la URL de invocación de la API y, a continuación, ingrese la URL de invocación de la API en el campo de entrada de un cliente de API de REST. Anexe **/lambdav1** antes de enviar la solicitud.
Obtendrá la siguiente respuesta.
```
"Hello, World! I'm calling from the beta stage."
```
1. En el panel de navegación **Etapas**, elija **prod**. En **Detalles de la etapa**, elija el icono de copiar para copiar la URL de invocación de la API y, a continuación, ingrese la URL de invocación de la API en el campo de entrada de un cliente de API de REST. Anexe **/lambdav1** antes de enviar la solicitud.
Obtendrá la siguiente respuesta.
```
"Hello, World! I'm calling from the prod stage."
```
1. Para usar la característica **Pruebas** para transferir metadatos específicos de la etapa, haga lo siguiente:
1. En el panel de navegación **Recursos**, elija la pestaña **Pruebas**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.
1. En **function** , ingrese **HelloWorld**.
1. En **stageName**, ingrese **beta**.
1. Seleccione **Probar**. No necesita agregar un cuerpo a su solicitud `POST`.
Obtendrá la siguiente respuesta.
```
"Hello, World! I'm calling from the beta stage."
```
1. Puede repetir los pasos anteriores para probar la etapa **Prod**. En **stageName**, ingrese **Prod**.
Obtendrá la siguiente respuesta.
```
"Hello, World! I'm calling from the prod stage."
```
# Referencia de variables de etapa de API Gateway para las API de REST en API Gateway
Puede utilizar variables de etapa de API Gateway en los siguientes casos.
## Expresiones de mapeo de parámetros
Una variable de etapa se puede usar en una expresión de asignación de parámetros para un parámetro de encabezado de solicitud o respuesta de un método de la API sin ninguna sustitución parcial. En el siguiente ejemplo, se hace referencia a la variable de etapa sin `$` y sin utilizar `{...}`.
+ `stageVariables.`
## Plantillas de mapeo
Una variable de etapa se puede utilizar en cualquier lugar de una plantilla de asignación, tal y como se muestra en los siguientes ejemplos.
+ `{ "name" : "$stageVariables."}`
+ `{ "name" : "${stageVariables.}"}`
## URI de integración HTTP
Una variable de etapa se puede utilizar como parte de una URL de integración HTTP, tal y como se muestra en los siguientes ejemplos:
+ Una URI completa sin protocol – `http://${stageVariables.}`
+ Un dominio complet – `http://${stageVariables.}/resource/operation`
+ Un subdomini – `http://${stageVariables.}.example.com/resource/operation`
+ Una rut – `http://example.com/${stageVariables.}/bar`
+ Una cadena de consult – `http://example.com/foo?q=${stageVariables.}`
## AWSURI de integración de
Una variable de etapa se puede utilizar como parte de los componentes de acción o ruta de un URI de AWS, tal y como se muestra en el siguiente ejemplo.
+ `arn:aws:apigateway:::${stageVariables.}`
## AWSURI de integración con (funciones de Lambda)
Las variables de etapa pueden utilizarse en lugar de un nombre de función de Lambda o versión/alias, tal y como se muestra en los siguientes ejemplos.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/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.
## Grupo de usuarios de Amazon Cognito
Se puede usar una variable de etapa en lugar de un grupo de usuarios de Amazon Cognito como autorizador de `COGNITO_USER_POOLS`.
+ `arn:aws:cognito-idp:::userpool/${stageVariables.}`
## AWSCredenciales de integración de
Una variable de etapa se puede utilizar como parte del ARN de credenciales de roles/usuarios de AWS, tal y como se muestra en el siguiente ejemplo.
+ `arn:aws:iam:::${stageVariables.}`