Creación, configuración y prueba de planes de uso con la CLI y la API de REST de API Gateway
Antes de configurar un plan de uso, debe haber hecho lo siguiente: haber configurado métodos de una API seleccionada para exigir claves de API, haber implementado o reimplementado la API en una etapa y haber creado o importado una o varias claves de API. Para obtener más información, consulte Configuración de claves de API mediante la API de REST de API Gateway.
Para configurar un plan de uso mediante la API de REST de API Gateway, use las siguientes instrucciones, siempre que ya haya creado las API que se van a agregar al plan de uso.
Temas
Migrar a planes de uso predeterminados
Cuando cree un plan de uso por primera vez, puede migrar al plan de uso las etapas de API existentes asociadas con las claves de API seleccionadas; para ello, llame a account:update
con el cuerpo siguiente:
{ "patchOperations" : [ { "op" : "add", "path" : "/features", "value" : "UsagePlans" } ] }
Para obtener más información acerca de cómo migrar las etapas de API asociadas con las claves de API, consulte Migrar a planes de uso predeterminados con la consola de API Gateway.
Crear un plan de uso
El siguiente procedimiento describe cómo crear un plan de uso.
Para crear un plan de uso con la API de REST
-
Llame a
usageplan:create
para crear un plan de uso. En la carga, especifique el nombre y la descripción del plan, las etapas de API asociadas, los límites de velocidad y las cuotas.Anote el identificador del plan de uso resultante. Lo necesitará en el siguiente paso.
-
Aplique alguna de las siguientes acciones:
-
Llame a
usageplankey:create
para agregar una clave de API al plan de uso. EspecifiquekeyId
ykeyType
en la carga.Para agregar más claves de API al plan de uso, repita la llamada anterior usando una clave de API cada vez.
-
Llame a
apikey:import
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 mediantekey
,name
ydescription
) a un plan de uso (identificado medianteusageplanIds
):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 aUsagePlan
.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.
-
Administración de un plan de uso con la CLI de AWS
Los siguientes ejemplos de código muestran cómo agregar, quitar o modificar la configuración de limitación controlada de nivel de método en un plan de uso mediante el comando update-usage-plan
.
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}}"'
Probar planes de uso
A modo de ejemplo, vamos a utilizar la API PetStore, que se creó en Tutorial: Crear una API de REST importando un ejemplo. 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 encabezadox-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 encabezadox-api-key
o lo estableció con una clave incorrecta, obtendrá una respuesta403 Forbidden
. Sin embargo, si no configuró el método para que solicite una clave de API, probablemente obtendrá una respuesta200 OK
tanto si estableció el encabezadox-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.