# Planes de uso y clave de API para las API de REST en API Gateway Después de crear, probar e implementar las API, puede utilizar los planes de uso de API Gateway para ponerlos a disposición de sus clientes como ofertas de productos. Puede configurar planes de uso y claves de API para permitir que los clientes accedan a las API seleccionadas, y comenzar la limitación controlada de las solicitudes a esas API en función de los límites y cuotas definidos. Se pueden configurar a nivel de API o método API. ## ¿Qué son los planes de uso y las claves de API? Un *plan de uso* especifica quién puede acceder a una o más etapas y métodos de la API implementada, y opcionalmente establece el ratio de solicitudes objetivo para comenzar la limitación controlada de las solicitudes. El plan utiliza claves de API para identificar los clientes de API y a quienes pueden acceder a las etapas de la API asociadas a cada clave. Las *claves de API* son valores de cadenas alfanuméricas que distribuye a los clientes desarrolladores de aplicaciones para concederles acceso a su API. Puede utilizar claves de API junto con [autorizadores de Lambda](apigateway-use-lambda-authorizer.md), [roles de IAM](permissions.md) o [Amazon Cognito](apigateway-integrate-with-cognito.md) para controlar el acceso a sus API. API Gateway puede generar claves de API en su nombre o usted puede importarlas desde un [archivo CSV](api-key-file-format.md). Puede generar una clave de API en API Gateway o importarla a API Gateway desde un origen externo. Para obtener más información, consulte [Configuración de claves API para API de REST en API Gateway](api-gateway-setup-api-keys.md). Una clave de API tiene un nombre y un valor. (Los términos "clave de API" y "valor de clave de API" suelen utilizarse indistintamente). El nombre no puede superar los 1024 caracteres. El valor es una cadena alfanumérica con un tamaño entre 20 y 128 caracteres, por ejemplo, `apikey1234abcdefghij0123456789`. **importante** Los valores de claves de API deben ser únicos. Si intenta crear dos claves de API con nombres distintos pero con el mismo valor, API Gateway considerará que son la misma clave de API. Una clave de API se puede asociar a más de un plan de uso. Un plan de uso se puede asociar a más de una etapa. Sin embargo, una clave de API determinada solo se puede asociar a un plan de uso para cada etapa de la API. Un *límite de limitación controlada* establece el punto objetivo en el que debe comenzar la limitación controlada de solicitudes. Esto se puede configurar a nivel de API o de método de API. Un *límite de cuota* establece el número máximo de solicitudes con una clave de API determinada que se pueden enviar en un intervalo de tiempo especificado. Puede configurar distintos métodos de la API para exigir la autorización de la clave de API en función de la configuración del plan de uso. La limitación de solicitudes y los límites de cuota se aplican a las solicitudes de claves de API individuales que se van acumulando en todas las etapas de la API dentro de un plan de uso. **nota** La limitación controlada del plan de uso y las cuotas no son límites estrictos y se aplican en la medida de lo posible. En algunos casos, los clientes pueden sobrepasar las cuotas establecidas. Para controlar los costes o bloquear el acceso a una API, no confíe en las cuotas del plan de uso ni en la limitación controlada. Considerar la posibilidad de utilizar [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) para monitorear los costes y [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) para administrar las solicitudes de API. ## Prácticas recomendadas para claves de API y planes de uso A continuación, se sugieren prácticas recomendadas cuando se utilizan claves de API y planes de uso. **importante** No utilice claves de API para la autenticación o la autorización del control de acceso a las API. Si tiene varias API en un plan de uso, un usuario con una clave de API válida para una API en ese plan de uso puede acceder a *todas* las API de ese plan de uso. En su lugar, para controlar el acceso a su API, utilice un rol de IAM, un [autorizador de Lambda](apigateway-use-lambda-authorizer.md) o un [grupo de usuarios de Amazon Cognito](apigateway-integrate-with-cognito.md). Use las claves de API que genera la puerta de enlace de la API. Las claves de API no deben incluir información confidencial; los clientes suelen transmitirlas en encabezados que se pueden registrar. + Si está utilizando un portal para desarrolladores para publicar las API, tenga en cuenta que los clientes se pueden suscribir a todas las API de un determinado plan de uso, incluso si no ha hecho que sean visibles para los clientes. + En algunos casos, los clientes pueden sobrepasar las cuotas establecidas. Para controlar los costos, no confíe en los planes de uso. 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. + Después de agregar una clave de API a un plan de uso, es posible que la operación de actualización tarde unos minutos en completarse. # Elección de un origen de clave de API en API Gateway Al asociar un plan de uso a una API y habilitar claves de API en los métodos de API, cada solicitud de entrada para la API debe contener una [clave de API](api-gateway-basic-concept.md#apigateway-definition-api-key). API Gateway lee la clave y la compara con las claves del plan de uso. Si hay una coincidencia, API Gateway limita las solicitudes en función del límite de solicitudes y la cuota del plan. De lo contrario, inicia una excepción `InvalidKeyParameter`. Como resultado, el intermediario recibe una respuesta `403 Forbidden`. Su API de API Gateway puede recibir claves de API de una de dos fuentes: **`HEADER`** Distribuye las claves de API a sus clientes y les pide que pasen la clave de API como el encabezado `X-API-Key` de cada solicitud de entrada. **`AUTHORIZER`** Hace que un autorizador de Lambda devuelva la clave de API como parte de la respuesta de autorización. Para obtener más información sobre la respuesta de autorización, consulte [Salida de un autorizador de Lambda de API Gateway](api-gateway-lambda-authorizer-output.md). **nota** Para conocer las prácticas recomendadas a tener en cuenta, consulte [Prácticas recomendadas para claves de API y planes de uso](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). En el procedimiento siguiente muestra cómo elegir un origen de clave de API para una API. ------ #### [ Consola de administración de AWS ] **Elección de un origen de claves para una API** 1. Inicie sesión en la consola de API Gateway. 1. Seleccione una API existente o cree una nueva. 1. En el panel de navegación principal, elija **Configuración de la API**. 1. En la sección **Detalles de la API**, elija **Editar**. 1. En **Origen de clave de API**, seleccione `Header` o `Authorizer` de la lista desplegable. 1. Seleccione **Save changes (Guardar cambios)**. ------ #### [ AWS CLI ] El siguiente comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) permite actualizar una API para establecer el origen de clave de API en `AUTHORIZER`: ``` aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER ``` Para que el cliente envíe una clave de API, establezca el `value` en `HEADER` en el comando anterior. ------ #### [ REST API ] Si desea elegir un origen de clave de API a través de la API de REST de API Gateway, llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html), tal y como se indica a continuación: ``` PATCH /restapis/fugvjdxtri/ HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20160603T205348Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash} { "patchOperations" : [ { "op" : "replace", "path" : "/apiKeySource", "value" : "HEADER" } ] } ``` Para que el autorizador devuelva una clave de API, establezca `value` en `AUTHORIZER` en la entrada `patchOperations` anterior. ------ # Formato de archivo de clave de API de API Gateway API Gateway puede importar claves de API de archivos externos con un formato de valores separados por comas (CSV) y asociar las claves importadas a uno o varios planes de uso. El archivo importado debe contener las columnas `Name` y `Key`. Los nombres de encabezado de columna no distinguen entre mayúsculas y minúsculas y las columnas pueden estar en cualquier orden, tal y como se muestra en el ejemplo siguiente: ``` Key,name apikey1234abcdefghij0123456789,MyFirstApiKey ``` Un valor `Key` debe estar comprendido entre 20 y 128 caracteres. Un valor `Name` no puede superar los 1024 caracteres. Un archivo de claves de API puede tener las columnas `Description`, `Enabled`o `UsagePlanIds`, como se muestra en el ejemplo siguiente: ``` Name,key,description,Enabled,usageplanIds MyFirstApiKey,apikey1234abcdefghij0123456789,An imported key,TRUE,c7y23b ``` Cuando una clave está asociada a varios planes de uso, el valor de `UsagePlanIds` es una cadena separada por comas con los identificadores del plan de uso incluidos entre comillas simples o dobles, tal y como se muestra en el ejemplo siguiente: ``` Enabled,Name,key,UsageplanIds true,MyFirstApiKey,apikey1234abcdefghij0123456789,"c7y23b,glvrsr" ``` Se pueden usar columnas no reconocidas, pero se omitirán. El valor predeterminado es una cadena vacía o un valor booleano `true`. Se puede importar varias veces la misma clave de API, pero la versión más reciente sobrescribirá la anterior. Dos claves de API son idénticas si tienen el mismo valor de `key`. **nota** Para conocer las prácticas recomendadas a tener en cuenta, consulte [Prácticas recomendadas para claves de API y planes de uso](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). # Configuración de claves API para API de REST en API Gateway Para configurar las claves de API, haga lo siguiente: + Configure los métodos de la API para que exijan una clave de API. + Cree o importe una clave de API para la API de una región. Antes de configurar las claves de API, debe haber creado una API y haberla implementado hasta una fase. Después de crear un valor de clave de API, no se puede cambiar. Para obtener instrucciones acerca de cómo crear e implementar una API a través de la consola de API Gateway, consulte [Desarrollo de las API de REST en API Gateway](rest-api-develop.md) y [Implementación de las API de REST en API Gateway](how-to-deploy-api.md), respectivamente. Después de crear una clave de API, debe asociarla al plan de uso. Para obtener más información, consulte [Configuración de planes de uso para API de REST en API Gateway](api-gateway-create-usage-plans.md). **nota** Para conocer las prácticas recomendadas a tener en cuenta, consulte [Prácticas recomendadas para claves de API y planes de uso](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). **Topics** + [ ## Exigir una clave de API en un método ](#api-gateway-usage-plan-configure-apikey-on-method) + [ ## Crear una clave de API ](#api-gateway-usage-plan-create-apikey) + [ ## Importar claves de API ](#api-gateway-usage-pan-import-apikey) ## Exigir una clave de API en un método El siguiente procedimiento describe cómo configurar un método de API para exigir una clave de API. ------ #### [ Consola de administración de AWS ] **Para configurar un método de API para exigir una clave de API** 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 de API Gateway, elija **Resources (Recursos)**. 1. En **Resources (Recursos)**, cree un método nuevo o elija uno existente. 1. En la pestaña **Solicitud de método**, en **Configuración de solicitud de método**, elija **Editar**. ![\[Agregación de una clave de API a un método\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/api-gateway-new-console-add-key-to-method.png) 1. Seleccione **Clave de API obligatoria**. 1. Seleccione **Save**. 1. Implemente o redistribuya la API para que el requisito surta efecto. Si la opción **Clave de API obligatoria** está establecida en `false` y no realiza los pasos anteriores, las claves de API asociadas a una etapa de API no se usarán con el método. ------ #### [ AWS CLI ] El siguiente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) crea un método `PUT` que requiere una clave de API: ``` aws apigateway put-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --authorization-type "NONE" \ --api-key-required ``` El siguiente comando [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) actualiza un método existente para que requiera una clave de API: ``` aws apigateway update-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --patch-operations op="replace",path="/apiKeyRequired",value="true" ``` ------ #### [ REST API ] Para exigir una clave de API en un método, realice alguna de las siguientes operaciones: + Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html) para crear un método. Establezca `apiKeyRequired` en `true` en la carga de la solicitud. + Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html) para establecer `apiKeyRequired` en `true`. ------ ## Crear una clave de API El procedimiento siguiente muestra cómo crear una clave de API. Si desea importar la clave de API, omita este paso. ------ #### [ Consola de administración de AWS ] **Para crear una clave de API** 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 de API Gateway, elija **Claves de API**. 1. Elija **Crear clave de la API**. ![\[Crear claves de API para planes de uso\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-choose-create-api-key-from-actions-menu.png) 1. En **Nombre**, ingrese un nombre. 1. (Opcional) En **Description (Descripción)**, introduzca una descripción. 1. En **Clave de API**, elija **Generar automáticamente** para que API Gateway genere el valor de la clave o elija **Personalizar** para crear su propio valor de la clave. 1. Seleccione **Save**. ------ #### [ AWS CLI ] El siguiente comando [create-api-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-api-key.html) crea una clave de API: ``` aws apigateway create-api-key \ --name 'Dev API key' \ --description 'API key for Devs' \ --enabled ``` ------ #### [ REST API ] Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html) para crear una clave de API. ------ ## Importar claves de API En el procedimiento siguiente se describe cómo importar claves de API. Si ya ha creado una clave de API, omita este paso. ------ #### [ Consola de administración de AWS ] **Para importar claves de API** 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 **Claves de API**. 1. Elija el menú desplegable **Acciones** y, a continuación, elija **Importar claves de API**. 1. Para cargar un archivo de claves separado por comas, elija **Elegir archivo**. También puede ingresar las claves en el editor de texto. Para obtener información sobre el formato de los archivos, consulte [Formato de archivo de clave de API de API Gateway](api-key-file-format.md). 1. Elija **Error en advertencias** para que la importación se detenga cuando se produzca un error o elija **Omitir advertencias** para que se sigan importando las entradas de clave válidas cuando se produzca una advertencia. 1. Elija **Importar** para importar las claves de API. ------ #### [ AWS CLI ] El siguiente comando [import-api-keys](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-api-keys.html) importa una clave de API: ``` aws apigateway import-api-key \ a--body fileb://keys.csv \ --format csv ``` ------ #### [ REST API ] Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) para importar una clave de API desde un archivo. Para el formato de archivo, consulte [Formato de archivo de clave de API de API Gateway](api-key-file-format.md). ------ No se puede cambiar el valor de la nueva clave de API. Después de crear la API, configure un plan de uso. Para obtener más información, consulte [Configuración de planes de uso para API de REST en API Gateway](api-gateway-create-usage-plans.md). # Configuración de planes de uso para API de REST en API Gateway Antes de crear un plan de uso, asegúrese de que ha configurado las claves de API que desea. Para obtener más información, consulte [Configuración de claves API para API de REST en API Gateway](api-gateway-setup-api-keys.md). **Topics** + [ ## Migrar la API a planes de uso predeterminados (si es necesario) ](#api-gateway-usage-plan-migrate-to-default) + [ ## Crear un plan de uso ](#api-gateway-usage-plan-create) + [ ## Adición de una etapa a un plan de uso ](#api-gateway-usage-plan-add-stage) + [ ## Adición de una clave API a un plan de uso ](#api-gateway-usage-plan-add-key) ## Migrar la API a planes de uso predeterminados (si es necesario) Si comenzó a utilizar API Gateway *después* del 11 de agosto de 2016 (fecha en la que se implementó la característica de planes de uso), los planes de uso estarán habilitados de forma predeterminada en todas las regiones compatibles. Si comenzó a utilizar API Gateway antes de dicha fecha, es posible que tenga que migrar a planes de uso predeterminados. Se le solicitará la opción **Enable Usage Plans (Habilitar planes de uso)** antes de utilizar los planes de uso por primera vez en la región seleccionada. Cuando habilite esta opción, dispondrá de planes de uso predeterminados para cada etapa de API asociada con las claves de API existentes. En el plan de uso predeterminado, no se establece inicialmente ningún límite de cuota o limitación y las asociaciones entre las claves de la API y las etapas de la API se copian en los planes de uso. La API se comportará igual que antes. Sin embargo, debe utilizar la propiedad `apiStages` de [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) para asociar los valores de la etapa de la API especificados (`apiId` y `stage`) con las claves de la API incluidas (mediante [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html)), en lugar de utilizar la propiedad `stageKeys` de [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html). Para comprobar si ya se ha migrado a planes de uso predeterminados, utilice el comando [https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-account.html) de la CLI. En la salida del comando, la lista `features` incluye una entrada de `"UsagePlans"` cuándo los planes de uso están habilitados. También puede migrar sus API a planes de uso predeterminados utilizando la AWS CLI tal y como se indica a continuación: **Para migrar a planes de uso predeterminados mediante la AWS CLI** 1. Llame a este comando de la CLI: [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html). 1. Para el parámetro `cli-input-json`, utilice el siguiente JSON: ``` [ { "op": "add", "path": "/features", "value": "UsagePlans" } ] ``` ## Crear un plan de uso El siguiente procedimiento describe cómo crear un plan de uso. ------ #### [ Consola de administración de AWS ] **Para crear un plan de uso** 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 principal de API Gateway, elija **Planes de uso** y, a continuación, elija **Crear plan de uso**. ![\[Entidades del plan de uso de la API\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-setup.png) 1. En **Nombre**, ingrese un nombre. 1. (Opcional) En **Description (Descripción)**, introduzca una descripción. 1. De forma predeterminada, los planes de uso habilitan la limitación. Ingrese una **tasa** y una **ráfaga** para el plan de uso. Elija **Limitación** para desactivar la limitación. 1. De forma predeterminada, los planes de uso habilitan una cuota durante un periodo de tiempo. En **Solicitudes**, ingrese el número total de solicitudes que un usuario puede realizar en el periodo de tiempo del plan de uso. Elija **Cuota** para desactivar la cuota. 1. Elija **Crear plan de uso**. ------ #### [ AWS CLI ] El siguiente comando [create-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan.html) crea un plan de uso que se reinicia a principios de mes: ``` aws apigateway create-usage-plan \ --name "New Usage Plan" \ --description "A new usage plan" \ --throttle burstLimit=10,rateLimit=5 \ --quota limit=500,offset=0,period=MONTH ``` ------ #### [ REST API ] Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html) para crear un plan de uso. ------ ## Adición de una etapa a un plan de uso El siguiente procedimiento describe cómo agregar una etapa a un plan de uso. ------ #### [ Consola de administración de AWS ] **Adición de una etapa a un plan de uso** 1. Seleccione el plan de uso. 1. En la pestaña **Etapas asociadas**, elija **Agregar etapa**. ![\[Agregue una fase de la API a un plan de uso.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-stage.png) 1. En **API**, seleccione una API. 1. En **Etapa**, seleccione una etapa. 1. (Opcional) Para activar la regulación en el nivel de método, haga lo siguiente: 1. Elija **Limitación en el nivel de método** y, a continuación, elija **Agregar método**. 1. En **Recurso**, seleccione un recurso de la API. 1. En **Método**, seleccione un método de la API. 1. Ingrese una **tasa** y una **ráfaga** para el plan de uso. 1. Elija **Agregar al plan de uso**. ------ #### [ AWS CLI ] El siguiente comando [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html) agrega la etapa `Prod` de una API a un plan de uso: ``` aws apigateway update-usage-plan \ --usage-plan-id abc123 \ --patch-operations op="add",path="/apiStages",value="a1b1c2:Prod" ``` ------ #### [ REST API ] Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) para actualizar un plan de uso. ------ ## Adición de una clave API a un plan de uso El procedimiento siguiente muestra cómo agregar una clave de API a un plan de uso. ------ #### [ Consola de administración de AWS ] **Adición de una clave a un plan de uso** 1. En la pestaña **Claves de API asociadas**, elija **Agregar clave de API**. ![\[Entidades del plan de uso de la API\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-key.png) 1. 1. Para asociar una clave existente al plan de uso, seleccione **Agregar clave existente** y, a continuación, seleccione la clave existente en el menú desplegable. 1. Para crear una clave de API nueva, seleccione **Crear y agregar una clave nueva** y, a continuación, cree una clave nueva. Para obtener más información sobre cómo crear una clave nueva, consulte [Crear una clave de API](api-gateway-setup-api-keys.md#api-gateway-usage-plan-create-apikey). 1. Elija **Agregar clave de la API**. ------ #### [ AWS CLI ] El siguiente comando [create-usage-plan-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan-key.html) asocia una clave de API existente a un plan de uso: ``` aws apigateway create-usage-plan-key \ --usage-plan-id a1b2c3 \ --key-type "API_KEY" \ --key-id aaa111bbb ``` ------ #### [ REST API ] Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html) para asociar una clave de API existente a un plan de uso. También puede asociar directamente las claves de API a un plan de uso cuando las importe. Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) para agregar una o varias claves de API directamente al plan de uso especificado. La carga de solicitudes debe incluir los valores de las claves de API, el identificador del plan de uso asociado, los indicadores booleanos que indican que las claves están habilitadas para el plan de uso y, posiblemente, los nombres y descripciones de las claves de API. En el siguiente ejemplo de la solicitud `apikey:import`, se agregarán tres claves de API (identificadas mediante `key`, `name`y `description`) a un plan de uso (identificado mediante `usageplanIds`): ``` POST /apikeys?mode=import&format=csv&failonwarnings=fase HTTP/1.1 Host: apigateway.us-east-1.amazonaws.com Content-Type: text/csv Authorization: ... key,name, description, enabled, usageplanIds abcdef1234ghijklmnop8901234567, importedKey_1, firstone, tRuE, n371pt abcdef1234ghijklmnop0123456789, importedKey_2, secondone, TRUE, n371pt abcdef1234ghijklmnop9012345678, importedKey_3, , true, n371pt ``` Como resultado, se crearán tres recursos `UsagePlanKey` y se agregarán a `UsagePlan`. También puede añadir claves de API a varios planes de uso de esta manera. Para ello, cambie cada valor de la columna `usageplanIds` por una cadena separada por comas que contenga los identificadores del plan de uso seleccionado entre comillas (`"n371pt,m282qs"` o `'n371pt,m282qs'`). ------ **nota** Una clave de API se puede asociar a más de un plan de uso. Un plan de uso se puede asociar a más de una etapa. Sin embargo, una clave de API determinada solo se puede asociar a un plan de uso para cada etapa de la API. # Mantenimiento de un plan de uso para las API de REST en API Gateway El mantenimiento de un plan de uso implica monitorear las cuotas usadas y restantes durante un período de tiempo determinado, si es necesario, y ampliar las cuotas restantes en una cantidad específica. Los siguientes procedimientos describen cómo monitorear las cuotas. ------ #### [ Consola de administración de AWS ] **Para monitorear las cuotas usadas y restantes** 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 principal de API Gateway, elija **Planes de uso**. 1. Seleccione un plan de uso. 1. Elija la pestaña **Claves de API asociadas** para ver el número de solicitudes pendientes de cada clave durante el periodo de tiempo. 1. (Opcional) Elija **Exportar datos de uso** y, a continuación, elija una fecha **de inicio** y una fecha de **finalización**. A continuación, elija **JSON** o **CSV** como formato de datos exportados y, a continuación, elija **Exportar**. El siguiente ejemplo muestra un archivo exportado. ``` { "px1KW6...qBazOJH": [ [ 0, 5000 ], [ 0, 5000 ], [ 0, 10 ] ] } ``` Los datos de uso del ejemplo representan los datos de uso diario de un cliente de API identificado por la clave de API (`px1KW6...qBazOJH`), entre el 1 de agosto de 2016 y el 3 de agosto de 2016. Cada dato de uso diario muestra las cuotas usadas y restantes. En este ejemplo, el suscriptor aún no ha utilizado ninguna de las cuotas asignadas y el propietario o administrador de la API redujo la cuota restante de 5000 a 10 durante el tercer día. Los siguientes procedimientos describen cómo modificar las cuotas. **Para ampliar las cuotas restantes** 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 principal de API Gateway, elija **Planes de uso**. 1. Seleccione un plan de uso. 1. Elija la pestaña **Claves de API asociadas** para ver el número de solicitudes pendientes de cada clave durante el periodo de tiempo. 1. Seleccione una clave de API y, a continuación, elija **Conceder extensión de uso**. 1. Escriba un número para la cuota de las **solicitudes restantes**. Puede aumentar las solicitudes de cambio de nombre o reducir las solicitudes restantes durante el periodo de tiempo del plan de uso. 1. Elija **Actualizar cuota**. ------ #### [ AWS CLI ] Los siguientes ejemplos [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html) permiten agregar, quitar o modificar la configuración de limitación de nivel de método en un plan de uso. **nota** Asegúrese de cambiar `us-east-1` al valor de región adecuado para la API. Para agregar o sustituir un límite de frecuencia a fin de limitar de forma controlada un recurso y un método individuales: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/rateLimit",value="0.1" ``` Para agregar o sustituir un límite de ráfaga a fin de limitar de forma controlada un recurso y un método individuales: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod/burstLimit",value="1" ``` Para quitar la configuración de limitación controlada de nivel de método para un recurso y un método individuales: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle/resourcePath/httpMethod",value="" ``` Para quitar toda la configuración de limitación controlada de nivel de método para una API: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="remove",path="/apiStages/apiId:stage/throttle ",value="" ``` A continuación se muestra un ejemplo con la API de ejemplo PetStore: ``` aws apigateway --region us-east-1 update-usage-plan --usage-plan-id planId --patch-operations op="replace",path="/apiStages/apiId:stage/throttle",value='"{\"/pets/GET\":{\"rateLimit\":1.0,\"burstLimit\":1},\"//GET\":{\"rateLimit\":1.0,\"burstLimit\":1}}"' ``` ------ #### [ REST API ] Llame a [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) para mantener un plan de uso. ------ # Creación y configuración de claves de API y planes de uso con CloudFormation Puede utilizar CloudFormation para solicitar claves de API en los métodos de la API y crear un plan de uso para una API. En la plantilla de CloudFormation de ejemplo se realiza lo siguiente: + Crea una API de API Gateway con los métodos `GET` y `POST`. + Requiere una clave de API para los métodos `GET` y `POST`. Esta API recibe claves del encabezado `X-API-KEY` de cada solicitud entrante. + Crea una clave de API. + Crea un plan de uso para especificar una limitación de 1000 solicitudes al mes, una limitación de velocidad controlada de 100 solicitudes por segundo y una limitación de ráfagas controlada de 200 solicitudes por segundo. + Especifica una limitación controlada de velocidad en el nivel de método de 50 solicitudes por segundo y una limitación controlada de ráfaga en el nivel de método de 100 solicitudes por segundo para el método `GET`. + Asocia la etapa de API y la clave de API con el plan de uso. ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: StageName: Type: String Default: v1 Description: Name of API stage. KeyName: Type: String Default: MyKeyName Description: Name of an API key Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: keys-api ApiKeySourceType: HEADER PetsResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'pets' PetsMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: GET ApiKeyRequired: true AuthorizationType: NONE Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ PetsMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: POST ApiKeyRequired: true AuthorizationType: NONE Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' UsagePlan: Type: AWS::ApiGateway::UsagePlan DependsOn: - ApiDeployment Properties: Description: Example usage plan with a monthly quota of 1000 calls and method-level throttling for /pets GET ApiStages: - ApiId: !Ref Api Stage: !Sub '${StageName}' Throttle: "/pets/GET": RateLimit: 50.0 BurstLimit: 100 Quota: Limit: 1000 Period: MONTH Throttle: RateLimit: 100.0 BurstLimit: 200 UsagePlanName: "My Usage Plan" ApiKey: Type: AWS::ApiGateway::ApiKey Properties: Description: API Key Name: !Sub '${KeyName}' Enabled: True UsagePlanKey: Type: AWS::ApiGateway::UsagePlanKey Properties: KeyId: !Ref ApiKey KeyType: API_KEY UsagePlanId: !Ref UsagePlan Outputs: ApiRootUrl: Description: Root Url of the API Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}' ``` # Configuración de un método para usar claves de API con una definición de OpenAPI Puede usar una definición de OpenAPI para requerir claves de API en un método. Para cada método, cree un objeto de requisito de seguridad que requiera una clave de API para invocar ese método. A continuación, defina `api_key` en la definición de seguridad. Después de crear la API, agregue la etapa de API nueva al plan de uso. En el siguiente ejemplo, se crea una API y se requiere una clave de API para los métodos `POST` y `GET`: ------ #### [ OpenAPI 2.0 ] ``` { "swagger" : "2.0", "info" : { "version" : "2024-03-14T20:20:12Z", "title" : "keys-api" }, "basePath" : "/v1", "schemes" : [ "https" ], "paths" : { "/pets" : { "get" : { "responses" : { }, "security" : [ { "api_key" : [ ] } ], "x-amazon-apigateway-integration" : { "type" : "http_proxy", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/", "passthroughBehavior" : "when_no_match" } }, "post" : { "responses" : { }, "security" : [ { "api_key" : [ ] } ], "x-amazon-apigateway-integration" : { "type" : "http_proxy", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/", "passthroughBehavior" : "when_no_match" } } } }, "securityDefinitions" : { "api_key" : { "type" : "apiKey", "name" : "x-api-key", "in" : "header" } } } ``` ------ #### [ OpenAPI 3.0 ] ``` { "openapi" : "3.0.1", "info" : { "title" : "keys-api", "version" : "2024-03-14T20:20:12Z" }, "servers" : [ { "url" : "{basePath}", "variables" : { "basePath" : { "default" : "v1" } } } ], "paths" : { "/pets" : { "get" : { "security" : [ { "api_key" : [ ] } ], "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/", "passthroughBehavior" : "when_no_match", "type" : "http_proxy" } }, "post" : { "security" : [ { "api_key" : [ ] } ], "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/", "passthroughBehavior" : "when_no_match", "type" : "http_proxy" } } } }, "components" : { "securitySchemes" : { "api_key" : { "type" : "apiKey", "name" : "x-api-key", "in" : "header" } } } } ``` ------ # Prueba de planes de uso para API de REST en API Gateway A modo de ejemplo, vamos a utilizar la API PetStore, que se creó en [Tutorial: Crear una API de REST importando un ejemplo](api-gateway-create-api-from-example.md). Supongamos que la API está configurada para utilizar una clave de API de `Hiorr45VR...c4GJc`. Los siguientes pasos describen cómo probar un plan de uso. **Para probar su plan de uso** + Realice una solicitud `GET` en el recurso Pets (`/pets`), con los parámetros de consulta `?type=...&page=...` de la API (por ejemplo, `xbvxlpijch`) en un plan de uso: ``` GET /testStage/pets?type=dog&page=1 HTTP/1.1 x-api-key: Hiorr45VR...c4GJc Content-Type: application/x-www-form-urlencoded Host: xbvxlpijch.execute-api.ap-southeast-1.amazonaws.com X-Amz-Date: 20160803T001845Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160803/ap-southeast-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature={sigv4_hash} ``` **nota** Debe enviar esta solicitud al componente `execute-api` de la API Gateway y proporcionar la clave de API necesaria (por ejemplo, `Hiorr45VR...c4GJc`) en el encabezado `x-api-key` correspondiente. La respuesta, si se ejecuta correctamente, devuelve un código de estado `200 OK` y una carga que contiene los resultados solicitados del backend. Si olvidó establecer el encabezado `x-api-key` o lo estableció con una clave incorrecta, obtendrá una respuesta `403 Forbidden`. Sin embargo, si no configuró el método para que solicite una clave de API, probablemente obtendrá una respuesta `200 OK` tanto si estableció el encabezado `x-api-key` correctamente como si no, y las limitaciones de solicitudes y los límites de cuota del plan de uso se omitirán. Ocasionalmente, cuando se produce un error interno que impide a API Gateway imponer limitaciones controladas en el plan de uso o límites de cuota en la solicitud, API Gateway proporciona la solicitud sin aplicar los límites ni las cuotas especificados en el plan de uso. Sin embargo, registra un mensaje de error `Usage Plan check failed due to an internal error` en CloudWatch. Puede obviar este tipo de errores ocasionales. # Llamada a un método con una clave de API En función del tipo de origen de clave de API que elija, utilice uno de los siguientes procedimientos para usar claves de API proporcionadas por un encabezado o claves de API proporcionadas por un autorizador en la invocación de método: **Para utilizar claves de API proporcionadas por un encabezado:** 1. Cree una API con los métodos de la API que desee y, a continuación, implemente la API en una etapa. 1. Cree un nuevo plan de uso o elija uno existente. Añada la etapa de API implementada al plan de uso. Asocie una clave de API al plan de uso o elija una clave de API existente en el plan. Anote el valor de la clave de API elegida. 1. Configure los métodos de la API para que exijan una clave de API. 1. Vuelva a implementar la API en la misma etapa. Si implementa la API en una nueva etapa, asegúrese de actualizar el plan de uso para asociar la nueva etapa de API. 1. Llame a la API utilizando la clave de API. El siguiente comando curl de ejemplo invoca el método `GET` en el recurso `getUsers` de la etapa `prod` de una API utilizando una clave de API. ``` curl -H "X-API-Key: abcd1234" 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers' ``` El cliente puede llamar ahora a los métodos de la API proporcionando al encabezado `x-api-key` la clave de API elegida como valor de encabezado. Una llamada tendría un aspecto similar al siguiente: **Para utilizar claves de API proporcionadas por un autorizador:** 1. Cree una API con los métodos de la API que desee y, a continuación, implemente la API en una etapa. 1. Cree un nuevo plan de uso o elija uno existente. Añada la etapa de API implementada al plan de uso. Asocie una clave de API al plan de uso o elija una clave de API existente en el plan. Anote el valor de la clave de API elegida. 1. Cree un autorizador de Lambda basado en token Incluya `usageIdentifierKey:{api-key}` como propiedad de nivel de raíz de la respuesta de autorización. Para obtener instrucciones sobre cómo crear un autorizador basado en token, consulte [Ejemplo de función de Lambda con un autorizador `TOKEN`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create). 1. Configure los métodos de la API para que exijan una clave de API y habilite el autorizador de Lambda en los métodos. 1. Vuelva a implementar la API en la misma etapa. Si implementa la API en una nueva etapa, asegúrese de actualizar el plan de uso para asociar la nueva etapa de API. El cliente puede llamar ahora a los métodos requeridos por la clave de API sin proporcionar explícitamente una clave de API. La clave de API proporcionada por un autorizador se usa de forma automática.