# Implementación de las API de REST en API Gateway Después de crear la API, debe implementarla para que los usuarios puedan llamarla. Para implementar una API, debe crear una implementación de API y asociarla con una etapa. Una referencia lógica a un estado del ciclo de vida de la API (por ejemplo, `dev`, `prod`, `beta`, `v2`). Las etapas de API se identifican por un ID y un nombre de etapa de API. Se incluyen en la URL que se 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. **importante** Cada vez que actualice una API, debe volver a implementar la API en una etapa existente o en una nueva etapa. La actualización de una API incluye la modificación de rutas, métodos, integraciones, autorizadores, políticas de recursos y cualquier otra cosa que no sea la configuración de la etapa. A medida que la API va evolucionando, se puede seguir implementando en diferentes etapas como versiones distintas. También puede implementar las actualizaciones de API como una [implementación de lanzamiento canary](canary-release.md). Esto permite a sus clientes API acceder, en el mismo escenario, a la versión de producción a través de la edición de producción, y a la versión actualizada a través de la edición canary. Para llamar a una API implementada, el cliente envía una solicitud a una URL de la API. La dirección URL viene determinada por el protocolo de la API (HTTP(S) o (WSS)), el nombre de host, el nombre de la etapa y (para las API de REST) la ruta del recurso. El nombre de host y el nombre de etapa determinan la URL base de la API. Por ejemplo, si se utiliza el nombre de dominio predeterminado de la API, la URL base de una API REST en una determinada etapa (`{stageName}`) tendrá el siguiente formato: ``` https://{restapi-id}.execute-api.{region}.amazonaws.com/{stageName} ``` Para simplificar la URL base predeterminada de una API para los usuarios, puede crear un nombre de dominio personalizado (por ejemplo, `api.example.com`) para sustituir el nombre de host predeterminado de la API. Para administrar varias API bajo el mismo nombre de domino, debe asignar una etapa de API a una ruta de acceso base. Con el nombre de dominio personalizado `{api.example.com}` y la etapa de API mapeada a la ruta base (`{basePath}`) bajo el nombre de dominio personalizado, la URL base de una API de REST sería: ``` https://{api.example.com}/{basePath} ``` Para cada etapa, puede optimizar el rendimiento de la API ajustando los límites de solicitudes de nivel de cuenta predeterminados y habilitando el almacenamiento en caché de la API. También puede activar el registro de las llamadas a la API a CloudTrail o CloudWatch y puede seleccionar un certificado de cliente para que el backend autentique las solicitudes de la API. Además, puede invalidar la configuración de nivel de etapa en los distintos métodos y definir variables de etapa para pasar contextos de entorno específicos de la etapa a la integración de la API en tiempo de ejecución. Las etapas permiten realizar un exhaustivo control de versiones de la API. Por ejemplo, puede implementar una API en una etapa `test` y una etapa `prod`, y utilizar la etapa `test` como compilación de pruebas y la etapa `prod` como compilación estable. Una vez que las actualizaciones superan la prueba, puede promover la etapa `test` como etapa `prod`. La promoción puede hacerse mediante la nueva implementación de la API en la etapa `prod` o la actualización de un valor de variable de etapa del nombre de etapa de `test` a `prod`. En esta sección vamos a hablar sobre cómo implementar una API con la [consola de API Gateway](https://console.aws.amazon.com/apigateway) o llamando a la [API de REST de API Gateway](https://docs.aws.amazon.com/apigateway/latest/api/). Para utilizar otras herramientas, consulte la documentación de la [CLI de AWS](https://docs.aws.amazon.com/cli/latest/reference/apigateway/) o de un [AWS SDK](https://aws.amazon.com/developer/tools/#sdk). **Topics** + [Creación de una implementación de una API de REST en API Gateway](set-up-deployments.md) + [Configuración de una etapa para una API de REST en API Gateway](set-up-stages.md) + [Configuración de una implementación de versión canario de API Gateway](canary-release.md) + [Actualizaciones de las API de REST que requieren reimplementación](updating-api.md) # Creación de una implementación de una API de REST en API Gateway En API Gateway, la implementación de una API de REST se representa mediante un recurso [Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html). Es similar a un ejecutable de una API al cual representa un recurso [RestAPI](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html). Para que el cliente pueda llamar a la API, debe crear una implementación y asociarle una etapa. Las etapas se representan mediante recursos [Stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html). Representa una instantánea de la API que incluye métodos, integraciones, modelos, plantillas de mapeo y autorizadores de Lambda (anteriormente conocidos como autorizadores personalizados). Cuando actualiza la API, puede implementarla de nuevo asociando una nueva etapa a la implementación existente. Explicaremos cómo se crea un etapa en [Configuración de una etapa para una API de REST en API Gateway](set-up-stages.md). **Topics** + [Creación de una implementación](#create-deployment) + [Próximos pasos para la implementación de la API](#apigateway-deployment-next-steps) ## Creación de una implementación En los procedimientos siguientes se muestra cómo crear una implementación para una API de REST. ------ #### [ Consola de administración de AWS ] Debe haber creado una API de REST antes de implementarla por primera vez. Para obtener más información, consulte [Desarrollo de las API de REST en API Gateway](rest-api-develop.md). La consola de API Gateway le permite implementar una API creando una implementación y asociándola a una etapa nueva o una existente. 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. En el panel de navegación **APIs**, elija la API que desea implementar. 1. En el panel **Resources (Recursos)**, elija **Deploy API (Implementar API)**. 1. En **Etapa**, seleccione una de las siguientes opciones: 1. Para crear una nueva etapa, seleccione **Nueva etapa** y, a continuación, ingrese un nombre en **Nombre de la etapa**. Si lo desea, puede proporcionar una descripción de la implementación en **Descripción de la implementación**. 1. Para elegir una etapa existente, seleccione el nombre de la etapa en el menú desplegable. Es posible que desee proporcionar una descripción de la nueva implementación en **Descripción de la implementación**. 1. Para crear una implementación que no esté asociada a una etapa, seleccione **Sin etapa**. Más adelante, puede asociar esta implementación a una etapa. 1. Elija **Deploy (Implementar)**. ------ #### [ AWS CLI ] Cuando se crea una implementación, se crea una instancia del recurso [Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html). El siguiente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) permite crear una implementación: ``` aws apigateway create-deployment --rest-api-id rest-api-id ``` No podrá invocar la API hasta haber asociado esta implementación a una etapa. Para hacerlo con una etapa existente, actualice la propiedad [deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) de la etapa con el ID de la implementación que acaba de crear. El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) actualiza la etapa con una nueva implementación. En la consola, esto se denomina **Implementación activa**. ``` aws apigateway update-stage \ --rest-api-id rest-api-id \ --stage-name 'stage-name' \ --patch-operations op='replace',path='/deploymentId',value='deployment-id' ``` Cuando crea la implementación, también puede asociarla a una nueva etapa al mismo tiempo. El siguiente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) crea una nueva implementación y la asocia a una nueva etapa denominada `beta`: ``` aws apigateway create-deployment \ --rest-api-id rest-api-id \ --stage-name beta ``` ------ Para volver a implementar una API, realice los mismos pasos. Puede reutilizar la misma etapa. ## Próximos pasos para la implementación de la API A continuación, se indican los pasos siguientes para la implementación de la API. Modificación de la configuración de etapa Una vez que se implementa una API, puede modificar la configuración de las etapas para habilitar o deshabilitar el almacenamiento en caché, el registro o los límites de solicitudes de la API. También puede elegir un certificado de cliente para que el backend autentique a API Gateway y definir variables de etapa para pasar el contexto de implementación a la integración de la API en el tiempo de ejecución. Para obtener más información, consulte [Modificación de la configuración de etapa](set-up-stages.md#how-to-stage-settings) Después de modificar la configuración de la etapa, es necesario volver a implementar la API para que los cambios surtan efecto. Si la configuración actualizada, como habilitar el registro, requiere un nuevo rol de IAM, puede agregar el rol de IAM necesario sin tener que volver a implementar la API. No obstante, el nuevo rol de IAM podría tardar unos minutos en empezar a funcionar. Antes de que esto ocurra, los registros de seguimiento de las llamadas a la API no se registran aunque haya habilitado la opción de registro. Elección de diferentes combinaciones de etapas de implementación Como una implementación representa una snapshot de API y una etapa define una ruta en una snapshot, puede elegir diferentes combinaciones de etapas de implementación para controlar la forma en que los usuarios llaman a diferentes versiones de la API. Esto resulta útil, por ejemplo, cuando desea restaurar el estado de la API a una implementación anterior o combinar una "ramificación privada" de la API con una pública. El siguiente procedimiento muestra cómo hacer esto con el **editor de etapas** en la consola de API Gateway. Se supone que debe haber implementado una API más de una vez. 1. Si aún no está en el panel **Etapas**, en el panel de navegación principal, elija **Etapas**. 1. Seleccione la etapa que desea actualizar. 1. En la pestaña **Historial de implementación**, seleccione la implementación que desea que utilice la etapa. 1. Elija **Cambiar implementación activa**. 1. Confirme que desea cambiar la implementación activa y elija **Cambiar implementación activa** en el cuadro de diálogo **Crear implementación activa**. Transfiera los datos específicos de la implementación a su API. Para una implementación, puede definir o modificar variables de etapa para pasar datos específicos de la implementación a la integración de la API en tiempo de ejecución. Puede hacer esto en la pestaña **Stage Variables (Variables de etapa)** en **Stage Editor (Editor de etapas)**. Para obtener más información, consulte las instrucciones de [Uso de variables de etapa para una API de REST en API Gateway](stage-variables.md). # Configuración de una etapa para una API de REST en API Gateway Una etapa es una referencia específica de una implementación, lo que equivale a una instantánea de la API. Puede utilizar una [etapa](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) para administrar y optimizar una implementación concreta. Por ejemplo, puede configurar los ajustes de la etapa para habilitar el almacenamiento en caché, personalizar la limitación controlada de solicitudes, configurar los registros, definir variables de etapa o asociar un lanzamiento canary para realizar pruebas. En la siguiente sección se muestra cómo crear y configurar la etapa. ## Creación de una nueva etapa Después de la implementación inicial, puede añadir más etapas y asociarlas con las implementaciones existentes. Puede utilizar la consola de API Gateway para crear una nueva etapa o puede elegir una etapa existente al implementar una API. En general, puede agregar una nueva etapa a la implementación de una API antes de volver a implementar la API. Para crear una nueva etapa con la consola de API Gateway, siga estos pasos: 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. En el panel de navegación principal, elija **Etapas** en una API. 1. En el panel de navegación **Etapas**, elija **Crear etapa**. 1. En **Nombre de etapa**, ingrese un nombre; por ejemplo, **prod**. **nota** Los nombres de etapas solo pueden contener caracteres alfanuméricos, guiones y caracteres de subrayado. La longitud máxima es de 128 caracteres. 1. (Opcional). En **Descripción**, ingrese una descripción de la etapa. 1. En **Implementación**, seleccione la fecha y la hora de la implementación de la API existente que vaya a asociar con esta etapa. 1. En **Configuración adicional**, puede especificar ajustes adicionales para su etapa. 1. Elija **Crear etapa**. ## Modificación de la configuración de etapa Después de una implementación correcta de una API, la etapa se rellena con la configuración predeterminada. Puede utilizar la consola o la API de REST de API Gateway para cambiar las opciones de configuración de las etapas, incluido el almacenamiento en caché de la API y el registro. Si ha modificado el punto de conexión predeterminado de la API de REST, cuando actualice una etapa, la modificación se propagará a todas las etapas de la API. En los siguientes pasos, se indica cómo hacer esto con el **Editor de etapas** de la consola de API Gateway. 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. En el panel de navegación principal, elija **Etapas** en una API. 1. En el panel **Etapas**, seleccione el nombre de la etapa. 1. En la sección **Detalles de la etapa**, elija **Editar**. 1. (Opcional) En **Descripción de etapa**, escriba una descripción. 1. En **Configuración adicional**, modifique la siguiente configuración: **Configuración de caché** Para habilitar el almacenamiento en caché de la API para la etapa, active **Aprovisionar caché de API**. A continuación, configure **Almacenamiento en caché de nivel de método predeterminado**, **Capacidad de caché**, **Cifrar datos de caché**, **Tiempo de vida (TTL) de caché** y los requisitos de la invalidación de caché para cada clave. El almacenamiento en caché no está activo hasta que se active el almacenamiento en caché en el nivel de método predeterminado o se active la caché en el nivel de método para un método específico. Para obtener más información acerca de la configuración de la caché, consulte [Configuración de caché para las API de REST en API Gateway](api-gateway-caching.md). Si habilita el almacenamiento en caché de la API para una etapa de API, se podrían generar cargos en su cuenta de AWS por el almacenamiento en caché de la API. El almacenamiento en caché no está disponible para la capa gratuita de AWS. **Configuración de limitación** Para definir los objetivos de limitación en el nivel de etapa para todos los métodos asociados a esta API, active **Limitación**. Para**Ratio**, ingrese un ratio objetivo. Esta es la velocidad, en solicitudes por segundo, a la que se añaden los tokens al bucket de tokens. La velocidad a nivel de etapa no debe ser superior a la velocidad a [nivel de cuenta](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits) especificada en [Cuotas para configurar y ejecutar una API de REST en API Gateway](api-gateway-execution-service-limits-table.md). Para **Ráfaga**, ingrese un ratio de ráfaga objetivo. La velocidad de ráfaga es la capacidad del bucket de tokens. Esto permite realizar más solicitudes durante un período de tiempo que el ratio objetivo. Este ratio de ráfaga a nivel de etapa no debe ser superior al ratio de ráfaga a [nivel de cuenta](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits) especificado en [Cuotas para configurar y ejecutar una API de REST en API Gateway](api-gateway-execution-service-limits-table.md). Los ratios de limitación controlada no son límites estrictos y se aplican en la medida de lo posible. En algunos casos, los clientes pueden sobrepasar los objetivos establecidos. Para controlar los costos o bloquear el acceso a una API, no confíe en la limitación controlada. Considere la posibilidad de utilizar [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) para monitorear los costos y [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) para administrar las solicitudes de API. **Configuración de firewall y certificados** Para asociar una ACL web de AWS WAF a la etapa, seleccione una ACL web en la lista desplegable **ACL web**. Si lo desea, elija **Bloquear solicitud de API si no se puede evaluar WebACL (cierre por error)**. Para seleccionar un certificado de cliente para su etapa, seleccione un certificado en el menú desplegable **Certificado de cliente**. 1. Elija **Continuar**. 1. Revise los cambios y elija **Guardar cambios**. 1. Para habilitar los registros de Amazon CloudWatch para todos los métodos asociados con esta etapa de esta API de API Gateway, en la sección **Registros y seguimiento**, elija **Editar**. **nota** Para habilitar los Registros de CloudWatch, también debe especificar el ARN de un rol de IAM que permita a API Gateway escribir información en los Registros de CloudWatch en nombre del usuario. Para ello, elija **Configuración** en el panel de navegación principal **API**. A continuación, ingrese el ARN de un rol de IAM en **Rol de registro de CloudWatch**. En escenarios de aplicación comunes, el rol de IAM podría asociar la política administrada de [AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html). El rol de IAM también debe incluir la siguiente instrucción de relación de confianza: **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` Para obtener más información sobre CloudWatch, consulte la *[guía del usuario de Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)*. 1. Elija un nivel de registro en el menú desplegable **Registros de CloudWatch**. A continuación, se muestran los niveles de registro: + **Desactivado**: el registro no está activado para esta etapa. + **Solo errores**: el registro solo está habilitado para los errores. + **Registros de errores e información**: el registro está habilitado para todos los eventos. 1. Seleccione **Rastreo de datos** para que API Gateway informe a CloudWatch del registro de rastreo de datos de la etapa. Esto puede ser útil para solucionar problemas de la API, pero puede dar como resultado el registro de datos confidenciales. **nota** Le recomendamos que no utilice **Rastreo de datos** para las API de producción. 1. Seleccione **Métricas detalladas** para que API Gateway informe a CloudWatch acerca de las métricas de la API de `API calls`, `Latency`, `Integration latency`, `400 errors` y `500 errors`. Para obtener más información acerca de CloudWatch, consulte [Supervisión básica y supervisión detallada](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html) en la Guía del usuario de Amazon CloudWatch. **importante** Se aplicarán cargos en su cuenta por obtener acceso a las métricas de CloudWatch en el nivel de método, pero no a las métricas en el nivel de API o de etapa. 1. Para habilitar el registro de acceso a un destino, active **Registro de acceso personalizado**. 1. Para **ARN del destino de registro de acceso**, ingrese el ARN de un grupo de registro o un flujo de Firehose. El formato de ARN de Firehose es `arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}`. El nombre del flujo de Firehose debe ser `amazon-apigateway-{your-stream-name}`. 1. En **Formato de registro**, ingrese un formato de registro. Para obtener más información sobre ejemplos de formatos de registro, consulte [Formatos de registro de CloudWatch para API Gateway](set-up-logging.md#apigateway-cloudwatch-log-formats). 1. Para habilitar el rastreo de [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) para la etapa de la API, seleccione **Rastreo de X-Ray**. Para obtener más información, consulte [Rastreo de las solicitudes de usuario a las API de REST mediante X-Ray en API Gateway](apigateway-xray.md). 1. Elija **Guardar cambios**. Vuelva a implementar su API para que la nueva configuración se aplique. ## Anule la configuración a nivel de etapa Después de personalizar la configuración de nivel de etapa, puede anularla para cada método de API. Algunas de estas opciones pueden dar lugar a cargos adicionales en la Cuenta de AWS. 1. Para configurar las anulaciones de métodos, expanda la etapa bajo el panel de navegación secundario y, a continuación, elija un método. ![\[Expanda la etapa en el panel de navegación secundario y elija un método.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/method-override-view-new-console.png) 1. A continuación, en **Anulaciones de métodos**, elija **Editar**. 1. Para activar la configuración de CloudWatch a nivel de método, en **Registros de CloudWatch**, seleccione un nivel de registro. 1. Para activar el registro de rastreo de datos en su método, seleccione **Rastreo de datos**. **nota** Le recomendamos que no utilice **Rastreo de datos** para las API de producción. 1. Para activar las métricas detalladas a nivel de método, seleccione **Métricas detalladas**. Se aplicarán cargos en su cuenta por obtener acceso a las métricas de CloudWatch en el nivel de método, pero no a las métricas en el nivel de API o de etapa. 1. Para activar la limitación en el nivel de método, seleccione **Limitación**. Introduzca las opciones de nivel de método adecuadas. Para obtener más información sobre limitación controlada, consulte [Limitación de las solicitudes a sus API de REST para mejorar el rendimiento en API Gateway](api-gateway-request-throttling.md). 1. Para configurar la caché en el nivel de método, seleccione **Habilitar caché de métodos**. Esta configuración no se verá afectada si en **Detalles de la etapa** cambia la configuración predeterminada del almacenamiento en caché en el nivel de método. 1. Seleccione **Save**. # Agregación de una API de REST de API Gateway como destino para la puerta de enlace de Amazon Bedrock AgentCore Una puerta de enlace de Amazon Bedrock AgentCore proporciona a los desarrolladores de agentes de IA una forma segura de exponer las API de REST de API Gateway como herramientas compatibles con el protocolo de contexto para modelos (MCP). La puerta de enlace AgentCore utiliza los objetivos para definir las herramientas. Cuando agrega la etapa como un destino, la puerta de enlace se convierte en una única URL de MCP que permite el acceso de un agente a las herramientas. Para obtener más información, consulte [Etapas de la API de REST de API Gateway como destinos](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-api-gateway.html) en la *Guía para desarrolladores de la puerta de enlace de Amazon Bedrock AgentCore*. Los destinos de API Gateway conectan la puerta de enlace AgentCore con las etapas de las API de REST. Puede incluir la etapa completa como objetivo o seleccionar recursos. Tras crear el destino de API Gateway, la puerta de enlace AgentCore traduce las solicitudes de MCP entrantes en solicitudes HTTP y gestiona el formato de las respuestas. Los clientes de MCP pueden recuperar la documentación de la API mediante el método `tools/list` e invocar las API mediante el método `tools/call`. ## Consideraciones Es posible que las siguientes consideraciones afecten al uso de la agregación de una etapa como destino a una puerta de enlace AgentCore: + Ya debe tener una puerta de enlace AgentCore. + Solo se admiten API de REST públicas. + El punto de conexión predeterminado de la API no se puede desactivar. + Cada método de la API debe tener un [nombre de operación](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html#apigw-PutMethod-request-operationName) definido para ello o debe crear una invalidación de nombre cuando agregue la etapa como destino. Este nombre se utiliza como el nombre de la herramienta que utilizan los agentes para interactuar con el método. + Puede usar los tipos de proveedor de credenciales `API_KEY`, `NO_AUTH` o `GATEWAY_IAM_ROLE` para la autenticación saliente a fin de permitir que la puerta de enlace acceda a la API. El proveedor de credenciales `API_KEY` lo define la puerta de enlace AgentCore. Puede usar la clave de API Gateway existente. Para obtener más información, consulte [Configuración de la autenticación saliente](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-outbound-auth.html). + Si utiliza un autorizador de Lambda o un grupo de usuarios de Amazon Cognito para controlar el acceso a la API, los clientes de MCP no pueden acceder. + La API debe estar en la misma cuenta y región que la puerta de enlace AgentCore. ## Agregación de una etapa de una API como destino para una puerta de enlace AgentCore En el siguiente procedimiento se muestra cómo agregar una etapa de una API como destino para una puerta de enlace AgentCore. **Agregación de una etapa de una API como destino para una puerta de enlace AgentCore** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST que se implemente en una etapa. 1. En el panel de navegación principal, elija **Etapas**. 1. Elija **Acciones de etapa** y, a continuación, elija **Crear destino de MCP**. 1. Para **Puerta de enlace AgentCore**, seleccione una puerta de enlace AgentCore. 1. Para **Nombre de destino**, escriba un nombre de destino. 1. Para **Descripción de destino**, ingrese una descripción. 1. Conserve la API y la etapa proporcionados. 1. Para **seleccionar los recursos de la API**, seleccione los recursos de la API a los que pueden acceder los agentes que utilizan la puerta de enlace AgentCore. Si no selecciona un recurso, el agente no podrá ver la documentación ni invocar el punto de conexión. 1. La combinación del recurso y el método son las operaciones de la herramienta. Si la operación no tiene un nombre, cree una invalidación de nombre. También puede definir un nombre de operación para un método al crearlo. 1. Para **configuración de autenticación saliente**, elija **rol de IAM**, **sin autorización** o **clave de la API**. 1. Elija **Crear destino**. Para ver todas las puertas de enlace AgentCore que tienen acceso a las API, elija la sección de **destinos de MCP** en el panel de navegación principal. En esta sección, puede crear un destino de MCP para cualquier API de la región implementada en una etapa. Elija **Crear un destino de MCP** y siga los pasos anteriores. También puede ver las herramientas disponibles para el destino y editarlo en la consola de puerta de enlace AgentCore. Para obtener más información, consulte [Agregación de destinos a una puerta de enlace AgentCore existente](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets.html). # Eliminación de una etapa Cuando ya no necesite una etapa, puede eliminarla para evitar pagar por recursos que no utiliza. En los pasos siguientes se enseña cómo utilizar la consola de API Gateway para eliminar una etapa. **aviso** La eliminación de una etapa puede provocar que parte o la totalidad de la API correspondiente quede inservible para los intermediarios de la API. La eliminación de una etapa no se puede deshacer, pero puede volver a crear la etapa y asociarla a la misma implementación. 1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API de REST. 1. En el panel de navegación principal, elija **Etapas**. 1. En el panel **Etapas**, elija la etapa que desea eliminar y, a continuación, elija **Acciones de etapa**, **Eliminar etapa**. 1. Cuando se le pregunte, escriba **confirm** y, a continuación, elija **Eliminar**. # Configuración de etiquetas para una etapa de API en API Gateway API Gateway le permite agregar una etiqueta a una etapa de API, quitarla de la etapa o consultarla. Para ello, puede utilizar la consola de API Gateway, la AWS CLI o un SDK o la API REST de API Gateway. Una etapa también puede heredar etiquetas de su API REST principal. Para obtener más información, consulte [Herencia de etiquetas en la API V1 de Amazon API Gateway](apigateway-tagging-supported-resources.md#apigateway-tagging-inheritance). Para obtener más información acerca de las etiquetas para recursos de API Gateway, consulte [Etiquetado de recursos de API Gateway](apigateway-tagging.md). **Topics** + [Configuración de etiquetas para una etapa de API con la consola de API Gateway](#set-up-tags-using-console) + [Configuración de etiquetas para una etapa de API a través de la AWS CLI](#set-up-tags-using-cli) + [Configuración de etiquetas para una etapa de API con la API de REST de API Gateway](#set-up-tags-using-api) ## Configuración de etiquetas para una etapa de API con la consola de API Gateway En el procedimiento siguiente, se describe cómo configurar etiquetas en una etapa de API. **Para configurar etiquetas para una etapa de API con la consola de API Gateway** 1. Inicie sesión en la consola de API Gateway. 1. Seleccione una API existente o cree una nueva que contenga recursos, métodos y las integraciones correspondientes. 1. Seleccione una etapa o implemente la API en una nueva etapa. 1. En el panel de navegación principal, elija **Etapas**. 1. Elija la pestaña **Etiquetas**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña. 1. Elija **Administrar etiquetas**. 1. En **Editor de etiquetas**, elija **Agregar etiqueta**. Escriba una clave de etiqueta (por ejemplo, `Department`) en el campo **Key (Clave)** y escriba un valor para la etiqueta (por ejemplo, `Sales`) en el campo **Value (Valor)**. Elija **Guardar** para guardar la etiqueta. 1. Si es necesario, repita el paso 5 para agregar más etiquetas a la etapa de API. El número máximo de etiquetas por etapa es 50. 1. Para eliminar una etiqueta de la etapa, haga clic en **Eliminar**. 1. Si la API se ha implementado anteriormente en la consola de API Gateway, usted tiene que volver a implementarla para que los cambios surtan efecto. ## Configuración de etiquetas para una etapa de API a través de la AWS CLI Puede configurar etiquetas para una etapa de API con AWS CLI mediante el comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) o el comando [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html). Puede eliminar una o varias etiquetas de una etapa de API con el comando [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html). El siguiente comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) permite agregar una etiqueta al crear una etapa `test`: ``` aws apigateway create-stage --rest-api-id abc1234 --stage-name test --description 'Testing stage' --deployment-id efg456 --tag Department=Sales ``` El siguiente [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) permite agregar una etiqueta a una etapa `prod`: ``` aws apigateway tag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/prod --tags Department=Sales ``` El siguiente comando [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) permite eliminar la etiqueta `Department=Sales` de la etapa `test`: ``` aws apigateway untag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/test --tag-keys Department ``` ## Configuración de etiquetas para una etapa de API con la API de REST de API Gateway Puede configurar etiquetas para una etapa de API mediante la API de REST de API Gateway con uno de los siguientes procedimientos: + Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) para etiquetar una etapa de API. + Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html) para eliminar una o varias etiquetas de una etapa de API. + Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) para agregar una o varias etiquetas a una etapa de API que vaya a crear. También puede llamar a [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html) para describir las etiquetas en una etapa de API. ### Etiquetado de una etapa de API Una vez que haya implementado una API (`m5zr3vnks7`) en una etapa (`test`), etiquete la etapa llamando a [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html). El nombre de recurso de Amazon (ARN) de la etapa correspondiente (`arn:aws:apigateway:us-east-1::/restapis/m5zr3vnks7/stages/test`) debe estar codificado como URL (`arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest`). ``` PUT /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest { "tags" : { "Department" : "Sales" } } ``` También puede utilizar la solicitud anterior para actualizar una etiqueta a un nuevo valor. Puede agregar etiquetas a una etapa cuando llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) para crear la etapa: ``` POST /restapis//stages { "stageName" : "test", "deploymentId" : "adr134", "description" : "test deployment", "cacheClusterEnabled" : "true", "cacheClusterSize" : "500", "variables" : { "sv1" : "val1" }, "documentationVersion" : "test", "tags" : { "Department" : "Sales", "Division" : "Retail" } } ``` ### Eliminación del etiquetado de una etapa de API Para eliminar la etiqueta `Department` de la etapa, llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html): ``` DELETE /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest?tagKeys=Department Host: apigateway.us-east-1.amazonaws.com Authorization: ... ``` Para eliminar varias etiquetas, utilice una lista separada por comas de claves de etiqueta en la expresión de consulta; por ejemplo, `?tagKeys=Department,Division,…`. ### Descripción de las etiquetas de una etapa de API Para describir las etiquetas existentes en una determinada etapa, llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html): ``` GET /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags Host: apigateway.us-east-1.amazonaws.com Authorization: ... ``` La respuesta correcta será similar a la que se muestra a continuación: ``` 200 OK { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-tags-{rel}.html", "name": "tags", "templated": true }, "tags:tag": { "href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags" }, "tags:untag": { "href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags{?tagKeys}", "templated": true } }, "tags": { "Department": "Sales" } } ``` # 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.}` # Configuración de una implementación de versión canario de API Gateway Una [versión canario](https://martinfowler.com/bliki/CanaryRelease.html) es una estrategia de implementación de software en la que una nueva versión de una API (así como otro software) se implementa con fines de pruebas, mientras que la versión base sigue implementada como versión de producción para las operaciones normales en la misma etapa. En esta documentación, nos referiremos a la versión base como "versión de producción". No obstante, tiene libertad para aplicar la versión canario de una versión que no sea de producción para realizar pruebas. Cuando se implementa una versión canario, el tráfico total de la API se separa aleatoriamente entre la versión de producción y la versión canario en un porcentaje preestablecido. Normalmente, el lanzamiento canary recibe un pequeño porcentaje del tráfico de la API, mientras que la versión de producción se ocupa del resto. Las características de la API actualizada solo están visibles al tráfico de la API a través del lanzamiento canary. Puede ajustar el porcentaje de tráfico de canary para optimizar la cobertura o el desempeño de las pruebas. Si el tráfico del lanzamiento canary es escaso y la selección es aleatoria, muy pocos usuarios se verán afectados en algún momento por los posibles errores de la nueva versión y en ningún caso se verán afectados de forma continuada. Una vez que las métricas de las pruebas se ajusten a sus requisitos, podrá promover el lanzamiento canary como versión de producción y deshabilitar canary de la implementación. De este modo, las nuevas características pasarán a estar disponibles en la etapa de producción. **Topics** + [Implementación de versiones canary en API Gateway](#api-gateway-canary-release-deployment-overview) + [Creación de una implementación del lanzamiento canary](create-canary-deployment.md) + [Actualización de un lanzamiento canary](update-canary-deployment.md) + [Promoción de un lanzamiento canary](promote-canary-deployment.md) + [Desactivación de un lanzamiento Canary](delete-canary-deployment.md) ## Implementación de versiones canary en API Gateway En API Gateway, al implementar un lanzamiento canary se utiliza la etapa de implementación de la versión base de una API y se asocia a la etapa un lanzamiento canary de las nuevas versiones (con respecto a la versión base) de la API. La etapa está asociada a la implementación inicial, mientras que el lanzamiento canary está asociado a las implementaciones posteriores. Al principio, tanto la etapa como canary apuntan a la misma versión de la API. En esta sección, utilizaremos indistintamente "etapa" y "versión de producción", así como "canary" y "lanzamiento canary". Para implementar una API con un lanzamiento canary, cree una implementación del lanzamiento canary agregando las [opciones de configuración del lanzamiento canary](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) a la [etapa](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) de una [implementación](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) normal. Las opciones de configuración de canary describen el lanzamiento canary subyacente, mientras que la etapa representa la versión de producción de la API en esta implementación. Para agregar la configuración de canary, establezca `canarySettings` en la etapa de implementación y especifique lo siguiente: + Un ID de implementación (en un principio, será idéntico al ID de la implementación de la versión base definida en la etapa). + Un [porcentaje del tráfico de la API](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#percentTraffic) (entre 0,0 y 100,0 inclusives) para el lanzamiento canary. + [Variables de etapa para el lanzamiento canary](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#stageVariableOverrides) que puedan sobrescribir las variables de etapa de la versión de producción. + El [uso de la caché de etapas](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) en las solicitudes canary, si se ha definido [useStageCache](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) y el almacenamiento en caché de la API está habilitado en la etapa. Una vez que se habilita un lanzamiento canary, la etapa de implementación no se puede asociar con la implementación que otra versión diferente hasta que el lanzamiento canary se deshabilite y si la configuración de canary se elimina de la etapa. Cuando se habilitan los registros de ejecución de la API, el lanzamiento canary tiene sus propios registros y métricas, que se generan para todas las solicitudes de canary. Se informa al respecto a un grupo de registro de CloudWatch Logs de etapa de producción, así como a un grupo de registro de CloudWatch Logs específico de canary. Lo mismo sucede con los registros de acceso. Tener registros independientes específicos de canary resulta útil para validar los nuevos cambios de la API y decidir si se van a aceptar las modificaciones y, por tanto, se va a promover el lanzamiento canary como etapa de producción o si, por el contrario, se van a descartar los cambios y se va a revertir el lanzamiento canary como etapa de producción. El grupo de registros de ejecución de la etapa de producción se llama `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}`, mientras que el grupo de registros de ejecución del lanzamiento canary se llama `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary`. En el caso de los registros de acceso, debe crear un nuevo grupo de registros o seleccionar uno existente. El nombre del grupo de registros de acceso del lanzamiento canary lleva el sufijo `/Canary`. Un versión canary puede utilizar la caché de etapas (si está habilitada) para guardar las respuestas y utilizar las entradas de esta caché para enviar resultados a las siguientes solicitudes de canary con un tiempo de vida (TTL) preconfigurado. En la implementación de un lanzamiento canary, la versión de producción y el lanzamiento canary de la API pueden asociarse con la misma versión o con versiones diferentes. Cuando se asocian con diferentes versiones, las respuestas de las solicitudes de producción y de canary se guardan en la caché por separado y la caché de etapas devuelve los resultados correspondientes para los dos tipos de solicitudes. Cuando la versión de producción y el lanzamiento canary están asociados con la misma implementación, la caché de etapas utiliza una única clave de caché para los dos tipos de solicitudes y devuelve la misma respuesta cuando la solicitud es la misma en la versión de producción y el lanzamiento canary. # Creación de una implementación del lanzamiento canary La implementación del lanzamiento canary se crea cuando la API se implementa con las [opciones de configuración canary](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings) como datos de entrada, además de con la operación de [creación de la implementación](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html). También puede crear una implementación de lanzamiento canary a partir de una implementación no canary creando una solicitud [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) para agregar la configuración de canary a la etapa. Cuando crea una implementación de una versión que no es canary, puede especificar un nombre de etapa que no existe. Si no existe la etapa especificada no existe, API Gateway la crea. Sin embargo, no puede especificar una etapa que no existe al crear una implementación canary. Si lo hace, aparecerá un error y API Gateway no creará ninguna implementación del lanzamiento canary. Puede crear una implementación de lanzamiento canary en API Gateway con la consola de API Gateway, la AWS CLI o un AWS SDK. **Topics** + [Creación de una implementación canary con la consola de API Gateway](#create-canary-deployment-using-console) + [Creación de una implementación canary a través de la AWS CLI](#create-canary-deployment-using-cli) ## Creación de una implementación canary con la consola de API Gateway Si desea utilizar la consola de API Gateway para crear una implementación de un lanzamiento canary, siga las instrucciones que se indican a continuación: **Para crear la implementación inicial de la versión canario** 1. Inicie sesión en la consola de API Gateway. 1. Elija una API de REST existente o cree una nueva API de REST. 1. En el panel de navegación principal, elija **Recursos** y, a continuación, elija **Implementar API**. Siga las instrucciones en pantalla que se indican en **Implementar API** para implementar la API en una nueva etapa. Hasta ahora, ha implementado la API en una etapa de versión de producción. A continuación, va a configurar los ajustes de la versión canario en la etapa y, si es necesario, también habilitará el almacenamiento en caché, definirá las variables de etapa o configurará los registros de ejecución o acceso de la API. 1. Para habilitar el almacenamiento en caché de la API o asociar una ACL web de AWS WAF a la etapa, en la sección de **Detalles de la etapa**, elija **Editar**. Para obtener más información, consulte [Configuración de caché para las API de REST en API Gateway](api-gateway-caching.md) o [Asociación de una ACL web de AWS WAF a una etapa de la API de API Gateway mediante la consola de API Gateway](apigateway-control-access-aws-waf.md#apigateway-control-access-aws-waf-console). 1. Para configurar los registros de ejecución o acceso, en la sección **Registros y rastreo**, elija **Editar** y siga las instrucciones que aparecen en pantalla. Para obtener más información, consulte [Configuración del registro de CloudWatch para las API de REST en API Gateway](set-up-logging.md). 1. Para definir las variables de etapa, elija la pestaña **Variables de etapa** y siga las instrucciones que aparecen en pantalla para agregar o modificar variables de etapa. Para obtener más información, consulte [Uso de variables de etapa para una API de REST en API Gateway](stage-variables.md). 1. Elija la pestaña **Canary** y, a continuación, elija **Crear Canary**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña **Canary**. 1. En la **Configuración de Canary**, para **Canary**, ingrese el porcentaje de solicitudes que se van a desviar al canary. 1. Si lo desea, seleccione **Caché de etapa** para activar el almacenamiento en caché del lanzamiento canary. La caché no está disponible para el lanzamiento canary hasta que el almacenamiento en caché de la API está habilitado. 1. Para anular las variables de etapa actuales, en **Sustitución de Canary**, ingrese un nuevo valor de variable de etapa. Una vez que el lanzamiento canary se inicialice en la etapa de implementación, cambie la API y pruebe los cambios. Puede volver a implementar la API en la misma etapa para que tanto la versión actualizada como la versión base estén accesibles en la misma etapa. En los pasos siguientes, se describe cómo hacerlo. **Para implementar la última versión de la API en un lanzamiento canary** 1. Con cada actualización de la API, elija **Implementar API**. 1. En **Implementar API**, elija la etapa que contiene un canary en la lista desplegable **Etapa de implementación**. 1. De forma opcional, ingrese una descripción para **Descripción de implementación**. 1. Seleccione **Deploy (Implementar)** para insertar la última versión de la API en el lanzamiento canary. 1. Si lo desea, puede volver a configurar los ajustes, los registros o la configuración de canary de la etapa, tal y como se describe en [Para crear la implementación inicial de la versión canario](#to-create-canary-release-on-new-deployment). Cuando termine, el lanzamiento canary apuntará a la última versión, mientras que la versión de producción seguirá apuntando a la versión inicial de la API. La propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) ahora tiene un nuevo valor **deploymentId**, mientras que la etapa sigue teniendo el valor [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId). En segundo plano, la consola llama a [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html). ## Creación de una implementación canary a través de la AWS CLI **Para crear una implementación canario para una etapa nueva** 1. Utilice el siguiente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) para crear una implementación con dos variables de etapa, pero sin un canario: ``` aws apigateway create-deployment \ --variables sv0=val0,sv1=val1 \ --rest-api-id abcd1234 \ --stage-name 'prod' ``` El resultado será similar al siguiente: ``` { "id": "du4ot1", "createdDate": 1511379050 } ``` 1. Utilice el siguiente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) para crear una implementación canario en la etapa `prod`: ``` aws apigateway create-deployment \ --rest-api-id abcd1234 \ --canary-settings percentTraffic=10.5,stageVariableOverrides={sv1='val2',sv2='val3'},useStageCache=false \ --stage-name 'prod' ``` El resultado será similar al siguiente: ``` { "id": "a6rox0", "createdDate": 1511379433 } ``` La implementación resultante `id` identifica la versión de prueba de la API del lanzamiento canary. Como resultado, la etapa asociada está habilitada para canary. 1. (Opcional) Utilice el siguiente comando [get-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-stage.html) para ver la representación de la etapa: ``` aws apigateway get-stage --rest-api-id acbd1234 --stage-name prod ``` A continuación, se muestra una representación de `Stage` como la salida del comando: ``` { "stageName": "prod", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "du4ot1", "lastUpdatedDate": 1511379433, "createdDate": 1511379050, "canarySettings": { "percentTraffic": 10.5, "deploymentId": "a6rox0", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" } }, "methodSettings": {} } ``` En este ejemplo, la versión de la API utilizará las variables de etapa `{"sv0":val0", "sv1":val1"}`, mientras que la versión de prueba utilizará `{"sv1":val2", "sv2":val3"}`. Tanto la versión de producción como el lanzamiento canary utilizan la variable de etapa `sv1`, pero con diferentes valores: `val1` y `val2`, respectivamente. La variable de etapa `sv0` solo se utiliza en la versión de producción, mientras que `sv2` solo se utiliza en el lanzamiento canary. También puede crear una implementación de versión canario a partir de una implementación normal existente actualizando la etapa para habilitar un canario. **Para crear una implementación de versión canario a partir de una implementación existente** 1. Utilice el comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) para crear una implementación sin un canario: ``` aws apigateway create-deployment \ --variables sv0=val0,sv1=val1 \ --rest-api-id abcd1234 \ --stage-name 'beta' ``` 1. Utilice el comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) para actualizar la etapa y habilitar un canario: ``` aws apigateway update-stage \ --rest-api-id abcd1234 \ --stage-name 'beta' \ --patch-operations '[{ "op": "replace", "value": "0.0", "path": "/canarySettings/percentTraffic" }, { "op": "copy", "from": "/canarySettings/stageVariableOverrides", "path": "/variables" }, { "op": "copy", "from": "/canarySettings/deploymentId", "path": "/deploymentId" }]' ``` El resultado será similar al siguiente: ``` { "stageName": "beta", "variables": { "sv0": "val0", "sv1": "val1" }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "cifeiw", "lastUpdatedDate": 1511381930, "createdDate": 1511380879, "canarySettings": { "percentTraffic": 10.5, "deploymentId": "cifeiw", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" } }, "methodSettings": {} } ``` Como hemos habilitado un canario en una versión existente de la API, tanto la versión de producción (`Stage`) como la versión canario (`canarySettings`) apuntan a la misma implementación. Después de cambiar la API y e implementarla de nuevo en esta etapa, la nueva versión estará en el lanzamiento canary, mientras que la versión base seguirá en la versión de producción. Esto se pone de manifiesto a medida que evoluciona la etapa, cuando el valor de `deploymentId` del lanzamiento canary se actualiza al nuevo `id` de la implementación y el valor de `deploymentId` de la versión de producción se mantiene sin cambios. # Actualización de un lanzamiento canary Una vez que se implemente el lanzamiento canary, es posible que quiera ajustar el porcentaje de tráfico de canary o que desee habilitar o deshabilitar el uso de la caché de etapas para optimizar el rendimiento de las pruebas. También puede modificar las variables de etapa que se utilizan en el lanzamiento canary cuando se actualiza el contexto de ejecución. Para realizar este tipo de actualizaciones, llame a la operación [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) utilizando valores nuevos en [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings). Puede actualizar un lanzamiento canary con la consola de API Gateway, el comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) de la AWS CLI o un AWS SDK. **Topics** + [Actualización de un lanzamiento canary con la consola de API Gateway](#update-canary-deployment-using-console) + [Actualización de un lanzamiento canary a través de la AWS CLI](#update-canary-deployment-using-cli) ## Actualización de un lanzamiento canary con la consola de API Gateway Si desea utilizar la consola de API Gateway para actualizar la configuración de canary de una etapa, haga lo siguiente: **Para actualizar la configuración de canary actual** 1. Inicie sesión en la consola de API Gateway y elija la API de REST actual. 1. En el panel de navegación principal, elija **Etapas** y, a continuación, elija la etapa actuala. 1. Elija la pestaña **Canary** y, a continuación, elija **Editar**. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña **Canary**. 1. Actualice **Distribución de solicitudes** aumentando o reduciendo el porcentaje en un valor comprendido entre 0,0 y 100,0 (ambos incluidos). 1. Active o desactive la casilla de verificación **Caché de etapa**. 1. Agregue, elimine o modifique las **Variables de etapa de Canary**. 1. Seleccione **Guardar**. ## Actualización de un lanzamiento canary a través de la AWS CLI Para usar la AWS CLI para actualizar un canario, utilice el comando [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) y modifique la operación de parche para cada parámetro del canario. El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) se actualiza si el canario usa la caché de etapas: ``` aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations op=replace,path=/canarySettings/useStageCache,value=true ``` El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) permite actualizar el porcentaje de tráfico del canario: ``` aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations op=replace,path=/canarySettings/percentTraffic,value=25.0 ``` El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) actualiza las variables de etapa. En el ejemplo se muestra cómo crear una nueva variable de etapas llamada `newVar`, invalidar la variable de etapas `var2` y eliminar la variable de etapas `var1`: ``` aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations '[{ "op": "replace", "path": "/canarySettings/stageVariableOverrides/newVar", "value": "newVal" }, { "op": "replace", "path": "/canarySettings/stageVariableOverrides/var2", "value": "val4" }, { "op": "remove", "path": "/canarySettings/stageVariableOverrides/var1" }]' ``` Puede realizar todas las actualizaciones anteriores combinando las operaciones en un solo valor `patch-operations`: ``` aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations '[{ "op": "replace", "path": "/canarySettings/percentTraffic", "value": "20.0" }, { "op": "replace", "path": "/canarySettings/useStageCache", "value": "true" }, { "op": "remove", "path": "/canarySettings/stageVariableOverrides/var1" }, { "op": "replace", "path": "/canarySettings/stageVariableOverrides/newVar", "value": "newVal" }, { "op": "replace", "path": "/canarySettings/stageVariableOverrides/val2", "value": "val4" }]' ``` # Promoción de un lanzamiento canary Cuando promocione un lanzamiento de canario, dicha versión reemplaza la configuración de etapa actual. Cuando se promueve un lanzamiento canary, no se deshabilita canary en la etapa. Para deshabilitar canary, debe eliminar la configuración de canary de la etapa. Para promocionar un canario, haga lo siguiente. + Restablezca el [ID de implementación](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) de la etapa con el [ID de implementación](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) del lanzamiento canary. De este modo, la instantánea de API de la etapa se actualiza con la instantánea de canary, lo que convierte la versión de prueba también en versión de producción. + Actualice las variables de etapa con las variables de canary, si hay alguna. De este modo, el contexto de ejecución de la etapa de la API se actualiza con el de canary. Sin esta actualización, la nueva versión de la API puede producir resultados inesperados si la versión de prueba utiliza otras variables de etapa o los valores de las variables de etapa existentes son diferentes. + Establezca el porcentaje del tráfico de canary en 0,0 %. **Topics** + [Promoción de un lanzamiento canary con la consola de API Gateway](#promote-canary-release-deployment-console) + [Promoción de un lanzamiento canary a través de la AWS CLI](#promote-canary-release-cli) ## Promoción de un lanzamiento canary con la consola de API Gateway Si desea utilizar la consola de API Gateway para promover la implementación de un lanzamiento canary, haga lo siguiente: **Para promocionar una implementación del lanzamiento canary** 1. Inicie sesión en la consola de API Gateway y seleccione una API existente en el panel de navegación principal. 1. En el panel de navegación principal, elija **Etapas** y, a continuación, elija la etapa actuala. 1. Elija la pestaña **Canary**. 1. Elija **Promocionar Canary**. 1. Confirme los cambios que desea realizar y elija **Promocionar Canary**. Tras realizar la promoción, la versión de producción hace referencia a la misma versión de la API (**deploymentId**) que el lanzamiento canary. Puede comprobarlo a través de la AWS CLI. Por ejemplo, consulte [Promoción de un lanzamiento canary a través de la AWS CLI](#promote-canary-release-cli). ## Promoción de un lanzamiento canary a través de la AWS CLI Para promover un lanzamiento canary como versión de producción utilizando los comandos de la AWS CLI, llame al comando `update-stage` para copiar el `deploymentId` asociado a canary en el `deploymentId` asociado a la etapa, para restablecer el porcentaje del tráfico de canary en cero (`0.0`) y para copiar las variables de etapa vinculadas a canary en las variables correspondientes vinculadas a la etapa. Supongamos que contamos con una implementación de un lanzamiento canary, descrita por una etapa similar a la siguiente: ``` { "_links": { ... }, "accessLogSettings": { ... }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "canarySettings": { "deploymentId": "eh1sby", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" }, "percentTraffic": 10.5 }, "createdDate": "2017-11-20T04:42:19Z", "deploymentId": "nfcn0x", "lastUpdatedDate": "2017-11-22T00:54:28Z", "methodSettings": { ... }, "stageName": "prod", "variables": { "sv1": "val1" } } ``` Utilice el siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) para promocionar el canario: ``` aws apigateway update-stage \ --rest-api-id {rest-api-id} \ --stage-name '{stage-name}' \ --patch-operations '[{ "op": "replace", "value": "0.0", "path": "/canarySettings/percentTraffic" }, { "op": "copy", "from": "/canarySettings/stageVariableOverrides", "path": "/variables" }, { "op": "copy", "from": "/canarySettings/deploymentId", "path": "/deploymentId" }]' ``` El resultado será similar al siguiente: ``` { "_links": { ... }, "accessLogSettings": { ... }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "canarySettings": { "deploymentId": "eh1sby", "useStageCache": false, "stageVariableOverrides": { "sv2": "val3", "sv1": "val2" }, "percentTraffic": 0 }, "createdDate": "2017-11-20T04:42:19Z", "deploymentId": "eh1sby", "lastUpdatedDate": "2017-11-22T05:29:47Z", "methodSettings": { ... }, "stageName": "prod", "variables": { "sv2": "val3", "sv1": "val2" } } ``` La promoción de un lanzamiento de canario según la etapa no desactiva el canario y la implementación sigue siendo una implementación de un lanzamiento de canario. Para convertirla en una implementación de una versión de producción ordinaria, debe desactivar la configuración de canary. Para obtener más información acerca de cómo desactivar la implementación de un lanzamiento canary, consulte [Desactivación de un lanzamiento Canary](delete-canary-deployment.md). # Desactivación de un lanzamiento Canary Para desactivar la implementación de un lanzamiento canary, establezca [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) en null; de esta forma, se eliminará de la etapa. Puede desactivar la implementación de un lanzamiento canary con la consola de API Gateway, la AWS CLI o un AWS SDK. **Topics** + [Desactivación de un lanzamiento canary con la consola de API Gateway](#delete-canary-release-console) + [Desactivación de un lanzamiento canary a través de la AWS CLI](#delete-canary-release-cli) ## Desactivación de un lanzamiento canary con la consola de API Gateway Si desea utilizar la consola de API Gateway para desactivar una implementación de lanzamiento canary, siga estos pasos: **Para desactivar la implementación de un lanzamiento Canary** 1. Inicie sesión en la consola de API Gateway y elija una API existente en el panel de navegación principal. 1. En el panel de navegación principal, elija **Etapas** y, a continuación, elija la etapa actuala. 1. Elija la pestaña **Canary**. 1. Elija **Eliminar**. 1. Confirme que desea eliminar el lanzamiento canary seleccionando **Delete (Eliminar)**. Como resultado, la propiedad [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) pasa a ser `null` y se elimina de la [etapa](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) de implementación. Puede comprobarlo a través de la AWS CLI. Por ejemplo, consulte [Desactivación de un lanzamiento canary a través de la AWS CLI](#delete-canary-release-cli). ## Desactivación de un lanzamiento canary a través de la AWS CLI El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) permite desactivar la implementación de la versión canario: ``` aws apigateway update-stage \ --rest-api-id abcd1234 \ --stage-name canary \ --patch-operations '[{"op":"remove", "path":"/canarySettings"}]' ``` El resultado es similar al siguiente: ``` { "stageName": "prod", "accessLogSettings": { ... }, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": "nfcn0x", "lastUpdatedDate": 1511309280, "createdDate": 1511152939, "methodSettings": { ... } } ``` Tal como se muestra en el resultado, la propiedad [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) ya no está presente en la [etapa](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) de una implementación con la versión canario desactivada. # Actualizaciones de las API de REST que requieren reimplementación Mantener una API equivale a visualizar, actualizar y eliminar las configuraciones existentes de la API. Puede mantener una API con la consola de API Gateway, la AWS CLI, el CloudFormation, un SDK o la API de REST de API Gateway. La actualización de una API implica modificar determinadas propiedades de recursos u opciones de configuración de la API. Las actualizaciones de recursos requieren volver a implementar la API, pero no las actualizaciones de configuración. En la siguiente tabla, se describen los recursos de la API que requieren volver a implementar la API al actualizarlos. | Recurso | Notas | | --- | --- | | [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [apikey:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateApiKey.html). La actualización requiere volver a implementar la API. | | [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [authorizer:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAuthorizer.html). La actualización requiere volver a implementar la API. | | [disableExecuteApiEndpoint](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html#apigw-UpdateRestApi-response-disableExecuteApiEndpoint) | La actualización requiere modificar cualquier etapa de la API, como volver a implementar la API en una etapa. | | [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html). La actualización requiere volver a implementar la API. | | [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [documentationversion:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationVersion.html). La actualización requiere volver a implementar la API. | | [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html#remarks). La actualización requiere volver a implementar la API. | | [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [integration:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegration.html). La actualización requiere volver a implementar la API. | | [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [integrationresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegrationResponse.html). La actualización requiere volver a implementar la API. | | [Método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [method:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html). La actualización requiere volver a implementar la API. | | [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [methodresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethodResponse.html). La actualización requiere volver a implementar la API. | | [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [model:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateModel.html). La actualización requiere volver a implementar la API. | | [RequestValidator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [requestvalidator:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRequestValidator.html). La actualización requiere volver a implementar la API. | | [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [resource:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). La actualización requiere volver a implementar la API. | | [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html). La actualización requiere volver a implementar la API. Esto incluye la modificación de las políticas de recursos. | | [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [vpclink:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateVpcLink.html). La actualización requiere volver a implementar la API. | En la siguiente tabla, se describen las configuraciones de la API que no requieren volver a implementar la API al actualizarlos. | Configuración | Notas | | --- | --- | | [Cuenta](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [account:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html). La actualización no requiere volver a implementar la API. | | [Implementación](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [deployment:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDeployment.html). | | [DomainName](https://docs.aws.amazon.com/apigateway/latest/api/API_DomainName.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html). La actualización no requiere volver a implementar la API. | | [BasePathMapping](https://docs.aws.amazon.com/apigateway/latest/api/API_BasePathMapping.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [basepathmapping:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateBasePathMapping.html). La actualización no requiere volver a implementar la API. | | [Tipo de dirección IP](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateRestApi.html) | La actualización no requiere volver a implementar la API. | | [Stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html). La actualización no requiere volver a implementar la API. | | [Uso](https://docs.aws.amazon.com/apigateway/latest/api/API_GetUsage.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [usage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsage.html). La actualización no requiere volver a implementar la API. | | [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) | Para saber cuáles son las propiedades aplicables y las operaciones que se pueden realizar, consulte [usageplan:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html). La actualización no requiere volver a implementar la API. |