Criar, configurar e testar planos de uso com a API REST e a CLI do API Gateway

Antes de configurar um plano de uso, você já deve ter feito o seguinte: configurado métodos de uma API selecionada para exigir chaves de API, implantado ou reimplantado a API em um estágio e criado ou importado uma ou mais chaves de API. Para obter mais informações, consulte Configurar chaves de API usando a API REST do API Gateway.

Para configurar um plano de uso usando a API REST do API Gateway, use as seguintes instruções, supondo que você já criou as APIs a serem adicionadas ao plano de uso.

Migrar para planos de uso padrão

Ao criar um plano de uso pela primeira vez, é possível migrar estágios de API existentes que estão associadas a chaves de API selecionadas para um plano de uso, chamando account:update com o seguinte corpo:

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/features",
    "value" : "UsagePlans"
  } ]
}

Para obter mais informações sobre como migrar estágios de API associados a chaves de API, consulte Migrar para planos de uso padrão no console do API Gateway.

Criar um plano de uso

O procedimento a seguir descreve como criar um plano de uso.

Para criar um plano de uso com a API REST

1. Chame usageplan:create para criar um plano de uso. Na carga, especifique o nome e a descrição do plano, estágios de API associados, limites de taxa e cotas.

   Anote o identificador de plano de uso resultante. Você precisa dele na próxima etapa.

2. Execute um destes procedimentos:

   1. Chame usageplankey:create para adicionar uma chave de API ao plano de uso. Especifique keyId e keyType na carga.

      Para adicionar mais chaves de API ao plano de uso, repita a chamada anterior, trabalhando com uma chave de API de cada vez.

   2. Chame apikey:import para adicionar uma ou mais chaves de API diretamente ao plano de uso especificado. A carga da solicitação deve conter valores de chaves de API, o identificador de plano de uso associado, os sinalizadores boolianos para indicar que as chaves estão habilitadas para o plano de uso e, possivelmente, os nomes e as descrições das chaves de API.

      O exemplo a seguir da solicitação apikey:import adiciona três chaves de API (identificadas por key, name e description) a um plano de um uso (identificado por 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, três recursos UsagePlanKey são criados e adicionados ao UsagePlan.

      Você também pode adicionar chaves de API a mais de um plano de uso dessa maneira. Para fazer isso, altere cada valor de coluna usageplanIds para uma string separada por vírgulas que contenha os identificadores do plano de uso selecionado e que esteja dentro de um par de aspas ("n371pt,m282qs" ou 'n371pt,m282qs').

      nota

      Uma chave de API pode ser associada a mais de um plano de uso. Um plano de uso pode ser associado a mais de um estágio. No entanto, uma determinada chave de API só pode ser associada a um único plano de uso para cada estágio de sua API.

Gerencie um plano de uso usando a AWS CLI

Os exemplos de código a seguir mostram como adicionar, remover ou modificar as configurações de controle de utilização em nível de método em um plano de uso chamando o comando update-usage-plan.

nota

Altere o us-east-1 para o valor de região apropriado para sua API.

Para adicionar ou substituir um limite de taxa para limitação de uso de um recurso e método específico:

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 adicionar ou substituir um limite de intermitência para limitação de uso de um recurso e método específico:

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 remover as configurações de limitação de uso de um recurso e método específico:

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 remover todas as configurações de limitação de uso em nível de método para uma API:

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="remove",path="/apiStages/<apiId>:<stage>/throttle ",value=""

Veja um exemplo que usa a API de exemplo 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}}"'

Testar planos de uso

Como exemplo, vamos usar a PetStore API, que foi criada emTutorial: Criar uma API REST importando um exemplo. Suponha que essa API esteja configurada para usar uma chave de API de Hiorr45VR...c4GJc. As etapas a seguir descrevem como testar um plano de uso.

Para testar seu plano de uso

• Faça uma solicitação GET no recurso Pets (/pets), com os parâmetros de consulta ?type=...&page=..., da API (por exemplo, xbvxlpijch) em um plano 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

  É necessário enviar essa solicitação ao componente execute-api do API Gateway e fornecer a chave de API necessária (por exemplo, Hiorr45VR...c4GJc) no cabeçalho x-api-key exigido.

  A resposta bem-sucedida retorna um código de status 200 OK e uma carga que contém os resultados solicitados do backend. Se você se esquecer de definir o cabeçalho x-api-key ou se defini-lo com uma chave incorreta, você recebe uma resposta 403 Forbidden. No entanto, se você não configurou o método para exigir uma chave de API, provavelmente obterá uma resposta 200 OK independentemente ou não de definir o cabeçalho x-api-key corretamente e os limites de cota e controle de fluxo do plano de uso serão ignorados.

  Ocasionalmente, quando ocorrer um erro interno em que o API Gateway fica incapaz de impor limites de controle de utilização ou cotas para a solicitação, o API Gateway atenderá a essa solicitação sem aplicar esses limites ou cotas, conforme especificado no plano de uso. Mas registra uma mensagem de erro de Usage Plan check failed due to an internal error no CloudWatch. Você pode ignorar esses erros ocasionais.