# Usar planos e chaves de API para APIs REST no APIs Gateway Depois que criar, testar e implantar suas APIs, você poderá usar planos de uso do API Gateway para disponibilizá-las como ofertas de produto aos seus clientes. É possível configurar planos de uso e chaves de API para permitir que os clientes acessem APIs selecionadas e inaugurem o controle de utilização de solicitações para essas APIs com base em limites e cotas definidos. Eles podem ser configurados na API ou no nível do método da API. ## O que são planos de uso e chaves de API? Um *plano de uso* especifica quem poderá acessar um ou mais estágios e métodos da API implantada e, opcionalmente, define a taxa de solicitação de destino para iniciar o controle de utilização de solicitações. O plano usa chaves de API para identificar clientes de APIs e quem poderá acessar os estágios da API associada para cada chave. *Chaves de API* são valores de strings alfanuméricas distribuídas para clientes de desenvolvedores de aplicativos para conceder acesso à API. Você pode usar chaves de API com [autorizadores do Lambda](apigateway-use-lambda-authorizer.md), [funções do IAM](permissions.md) ou o [Amazon Cognito](apigateway-integrate-with-cognito.md) para controlar o acesso às suas APIs. O API Gateway pode gerar chaves de API em seu nome ou você pode importá-las para um [arquivo CSV](api-key-file-format.md). Você pode gerar uma chave de API no API Gateway ou importá-la para o API Gateway a partir de uma fonte externa. Para obter mais informações, consulte [Configurar chaves de API para a API REST no API Gateway](api-gateway-setup-api-keys.md). Uma chave de API tem um nome e um valor. (Os termos "chave de API" e "valor de chave de API" são frequentemente usados de forma intercambiável.) O nome não pode exceder 1.024 caracteres. O valor é uma string alfanumérica com tamanho entre 20 e 128 caracteres; por exemplo, `apikey1234abcdefghij0123456789`. **Importante** Os valores de chaves de API devem ser exclusivos. Se você tentar criar duas chaves de API com nomes diferentes e o mesmo valor, o API Gateway as considera a mesma chave de API. 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. Um *limite de controle de utilização* define o ponto de destino em que o controle de utilização de solicitações deverá ser iniciado. Isso pode ser configurado na API ou no nível do método da API. Um *limite de cota* define o número máximo alvo de solicitações com uma determinada chave de API que poderão ser enviadas em um intervalo de tempo especificado. Você pode configurar métodos de API particulares para exigir a autorização da chave de API com base na configuração do plano de uso. Limites de controle de utilização e cotas são aplicáveis a solicitações para chaves de API particulares que estão agregadas por todos os estágios de API em um plano de uso. **nota** O controle de utilização e cotas do plano de uso não são limites rígidos e são aplicados de acordo com os melhores esforços. Em alguns casos, os clientes podem exceder as cotas definidas por você. Não dependa de cotas e controle de utilização de planos de uso para controlar custos ou bloquear o acesso a uma API. Considere usar o [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) para monitorar custos e o [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) para gerenciar solicitações de APIs. ## Práticas Recomendadas para chaves de API e planos de uso Veja a seguir sugestões de práticas recomendadas a serem seguidas ao usar chaves de API e planos de uso. **Importante** Não use chaves de API para autenticação ou autorização para controlar as APIs. Se você tiver várias APIs em um plano de uso, um usuário com uma chave de API válida para uma API nesse plano de uso poderá acessar *todas* as APIs desse plano. Em vez disso, para controlar o acesso à API, use um perfil do IAM, um [autorizador do Lambda](apigateway-use-lambda-authorizer.md) ou um [grupo de usuários do Amazon Cognito](apigateway-integrate-with-cognito.md). Use as chaves de API geradas pelo API Gateway. As chaves de API não devem incluir informações confidenciais; os clientes geralmente as transmitem em cabeçalhos que podem ser registrados em log. + Se você estiver usando um portal do desenvolvedor para publicar as APIs, observe que todas as APIs em determinado plano de uso podem ser assinadas por clientes, mesmo que você não as tenha tornado visíveis para os clientes. + Em alguns casos, os clientes podem exceder as cotas definidas por você. Não dependa de planos de uso para controlar custos. Considere usar [AWS Budgets](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) para monitorar custos e [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) para gerenciar solicitações de APIs. + Depois que você adiciona uma chave de API a um plano de uso, a operação de atualização pode levar alguns minutos para ser concluída. # Escolher uma origem de chaves de API no API Gateway Quando você associa um plano de uso a uma API e habilita chaves de API em métodos de API, toda solicitação recebida para a API deve conter uma [chave de API](api-gateway-basic-concept.md#apigateway-definition-api-key). O API Gateway lê a chave e a compara com as chaves no plano de uso. Se houver correspondência, o API Gateway fará o controle de utilização das solicitações de acordo com o limite de solicitação e a cota do plano. Caso contrário, ele lançará uma exceção de `InvalidKeyParameter`. Como resultado, o autor da chamada recebe uma resposta `403 Forbidden`. A API do API Gateway pode receber chaves de API de duas origens: **`HEADER`** Distribua chaves de API aos seus clientes e exija que eles repassem a chave de API como o cabeçalho `X-API-Key` de cada solicitação de entrada. **`AUTHORIZER`** Um autorizador do Lambda pode retornar a chave de API como parte da resposta de autorização. Para obter mais informações sobre a resposta de autorização, consulte [Saída de um autorizador do Lambda para o API Gateway](api-gateway-lambda-authorizer-output.md). **nota** Para ver as práticas recomendadas a serem consideradas, consulte [Práticas Recomendadas para chaves de API e planos de uso](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). O procedimento a seguir mostra como escolher uma origem de chave de API. ------ #### [ Console de gerenciamento da AWS ] **Como escolher uma origem de chave de API para uma API** 1. Inicie uma sessão no console do API Gateway. 1. Escolha uma API existente ou crie uma nova. 1. No painel de navegação principal, selecione **Configurações da API**. 1. Na seção **Detalhes da API**, escolha **Editar**. 1. Em **Origem de chave de API**, selecione `Header` ou `Authorizer` na lista suspensa. 1. Escolha **Salvar alterações**. ------ #### [ AWS CLI ] O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo atualiza uma API para definir a origem da chave de API como `AUTHORIZER`: ``` aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER ``` Para que o cliente envie uma chave de API, defina o `value` como `HEADER` no comando anterior. ------ #### [ REST API ] Para escolher uma origem de chave de API para uma API usando a API REST do API Gateway, chame [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) da seguinte forma: ``` 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 um autorizador retorne uma chave de API, defina `value` para `AUTHORIZER` na entrada `patchOperations` anterior. ------ # Formato de arquivo da chave de API do API Gateway O API Gateway pode importar chaves de API de arquivos externos com um formato de valores separados por vírgula (CSV) e, depois, associar as chaves importadas a um ou mais planos de uso. O arquivo importado deve conter as colunas `Name` e `Key`. Os nomes de cabeçalhos de coluna não fazem distinção entre maiúsculas e minúsculas, e as colunas podem estar em qualquer ordem, como mostra o exemplo a seguir: ``` Key,name apikey1234abcdefghij0123456789,MyFirstApiKey ``` Um valor de `Key` deve ter entre 20 e 128 caracteres. Um valor `Name` não pode exceder 1.024 caracteres. Um arquivo de chave de API também pode ter a coluna `Description`, `Enabled` ou `UsagePlanIds`, como mostra o exemplo a seguir: ``` Name,key,description,Enabled,usageplanIds MyFirstApiKey,apikey1234abcdefghij0123456789,An imported key,TRUE,c7y23b ``` Quando uma chave está associada a mais de um plano de uso, o valor de `UsagePlanIds` é uma string separada por vírgulas dos IDs do plano de uso e delimitada por um par de cotas duplas ou simples, como mostra o exemplo a seguir: ``` Enabled,Name,key,UsageplanIds true,MyFirstApiKey,apikey1234abcdefghij0123456789,"c7y23b,glvrsr" ``` Colunas não reconhecidas são permitidas, mas são ignoradas. O valor padrão é uma string vazia ou um valor booliano `true`. A mesma chave de API pode ser importada várias vezes, com a versão mais recente substituindo a anterior. Duas chaves de API serão idênticas se tiverem o mesmo valor de `key`. **nota** Para ver as práticas recomendadas a serem consideradas, consulte [Práticas Recomendadas para chaves de API e planos de uso](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). # Configurar chaves de API para a API REST no API Gateway Para configurar as chaves de API, faça o seguinte: + Configure métodos de API para exigir uma chave de API. + Crie ou importe uma chave de API para a API em uma região. Antes de configurar chaves de API, é necessário ter criado a API e tê-la implantado em uma etapa. Depois que um valor de chave de API for atribuído, ele não poderá ser alterado. Para obter instruções sobre como criar e implantar uma API usando o console do API Gateway, consulte [Desenvolver APIs REST no API Gateway](rest-api-develop.md) e [Implantar APIs REST no API Gateway](how-to-deploy-api.md), respectivamente. Depois de criar uma chave de API, você deve associá-la a um plano de uso. Para obter mais informações, consulte [Configurar planos de uso para APIs REST no API Gateway](api-gateway-create-usage-plans.md). **nota** Para ver as práticas recomendadas a serem consideradas, consulte [Práticas Recomendadas para chaves de API e planos de uso](api-gateway-api-usage-plans.md#apigateway-usage-plans-best-practices). **Topics** + [ ## Exigir uma chave de API em um método ](#api-gateway-usage-plan-configure-apikey-on-method) + [ ## Criar uma chave de API ](#api-gateway-usage-plan-create-apikey) + [ ## Importar chaves de API ](#api-gateway-usage-pan-import-apikey) ## Exigir uma chave de API em um método O procedimento a seguir descreve como configurar um método de API para exigir uma chave de API. ------ #### [ Console de gerenciamento da AWS ] **Para configurar um método de API para exigir uma chave de API** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. No painel de navegação principal do API Gateway, escolha **Resources (Recursos)**. 1. Em **Resources (Recursos)**, crie um novo método ou escolha um existente. 1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, escolha **Editar**. ![\[Adicionar uma chave de API a um método\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-new-console-add-key-to-method.png) 1. Selecione a **Chave de API obrigatória**. 1. Escolha **Salvar**. 1. Implante ou reimplante a API para que o requisito entre em vigor. Se a opção **Chave de API obrigatória** estiver definida como `false` e você não executar as etapas anteriores, nenhuma chave de API associada a um estágio de API será usada para o método. ------ #### [ AWS CLI ] O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo cria um método `PUT` que exige uma chave de API: ``` aws apigateway put-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --authorization-type "NONE" \ --api-key-required ``` O comando [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) indicado abaixo atualiza um método existente para exigir uma chave 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 uma chave de API em um método, siga um destes procedimentos: + Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html) para criar um método. Defina `apiKeyRequired` como `true` na carga da solicitação. + Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html) para definir `apiKeyRequired` como `true`. ------ ## Criar uma chave de API O procedimento a seguir mostra como criar uma chave de API. Se você quiser importar a chave de API, ignore esta etapa. ------ #### [ Console de gerenciamento da AWS ] **Para criar uma chave de API** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. No painel de navegação principal do API Gateway, escolha **Chaves de API**. 1. Escolha **Criar chave de API**. ![\[Criar chaves de API para planos de uso\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-choose-create-api-key-from-actions-menu.png) 1. Em **Nome**, insira um nome. 1. (Opcional) Em **Description (Descrição)**, insira uma descrição. 1. Em **Chave de API**, escolha **Gerar automaticamente** para que o API Gateway gere o valor da chave ou escolha **Personalizado** para criar seu próprio valor de chave. 1. Escolha **Salvar**. ------ #### [ AWS CLI ] O comando [create-api-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-api-key.html) indicado abaixo cria uma chave de API: ``` aws apigateway create-api-key \ --name 'Dev API key' \ --description 'API key for Devs' \ --enabled ``` ------ #### [ REST API ] Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateApiKey.html) para criar uma chave de API. ------ ## Importar chaves de API O procedimento a seguir descreve como importar chaves de API. Se você já tiver criado uma chave de API, ignore esta etapa. ------ #### [ Console de gerenciamento da AWS ] **Para importar chaves de API** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. No painel de navegação principal, selecione **Chaves de API**. 1. Selecione o menu suspenso **Ações** e **Importar chaves de API**. 1. Para carregar um arquivo de chave separado por vírgula, selecione **Escolher arquivo**. Você também pode inserir as chaves no editor de texto. Para obter informações sobre o formato do arquivo, consulte [Formato de arquivo da chave de API do API Gateway](api-key-file-format.md). 1. Escolha **Falhar nos avisos** para interromper a importação em caso de erro ou escolha **Ignorar avisos** para continuar a importar entradas de chave válidas quando houver um erro. 1. Escolha **Importar** para importar as chaves de API. ------ #### [ AWS CLI ] O comando [import-api-keys](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-api-keys.html) indicado abaixo importa uma chave de API: ``` aws apigateway import-api-key \ a--body fileb://keys.csv \ --format csv ``` ------ #### [ REST API ] Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) para importar uma chave de API de um arquivo. Para saber o formato de arquivo, consulte [Formato de arquivo da chave de API do API Gateway](api-key-file-format.md). ------ Não é possível alterar o valor da nova chave de API. Depois de criar a API, configure um plano de uso. Para obter mais informações, consulte [Configurar planos de uso para APIs REST no API Gateway](api-gateway-create-usage-plans.md). # Configurar planos de uso para APIs REST no API Gateway Antes de criar um plano de uso, você deve configurar as chaves de API. Para obter mais informações, consulte [Configurar chaves de API para a API REST no API Gateway](api-gateway-setup-api-keys.md). **Topics** + [ ## Migrar a API para planos de uso padrão (se necessário) ](#api-gateway-usage-plan-migrate-to-default) + [ ## Criar um plano de uso ](#api-gateway-usage-plan-create) + [ ## Adicionar um estágio de API a um plano de uso ](#api-gateway-usage-plan-add-stage) + [ ## Adicionar uma chave de API a um plano de uso ](#api-gateway-usage-plan-add-key) ## Migrar a API para planos de uso padrão (se necessário) Se você começou a usar o API Gateway *depois* que o recurso de planos de uso foi lançado em 11 de agosto de 2016, terá planos de uso habilitados automaticamente em todas as regiões compatíveis. Se começou a usar o API Gateway antes dessa data, poderá ser necessário migrar para os planos de uso padrão. Você receberá a opção **Enable Usage Plans (Habilitar planos de uso)** antes de usar os planos de uso pela primeira vez na região selecionada. Quando você habilita essa opção, você tem planos de uso padrão criados para cada estágio de API exclusivo que está associado a chaves de API existentes. No plano de uso padrão, nenhum limite de controle ou limite de cota é definido inicialmente, e as associações entre chaves de API e estágios de API são copiadas para os planos de uso. A API tem o mesmo comportamento de antes. Contudo, você deve usar a propriedade de [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) `apiStages` para associar valores especificados de estágios de API (`apiId` e `stage`) com as chaves de API incluídas (via [https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlanKey.html)), em vez de usar a propriedade `stageKeys` da [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html). Para verificar se você já migrou para os planos de uso padrão, use o 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) da CLI. Na saída do comando, a lista `features` inclui uma entrada de `"UsagePlans"` quando os planos de uso estão habilitados. Você também pode migrar as APIs para os planos de uso padrão usando a AWS CLI da seguinte maneira: **Para migrar para os planos de uso padrão usando a AWS CLI** 1. Chame este comando da 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. No parâmetro `cli-input-json`, use o seguinte JSON: ``` [ { "op": "add", "path": "/features", "value": "UsagePlans" } ] ``` ## Criar um plano de uso O procedimento a seguir descreve como criar um plano de uso. ------ #### [ Console de gerenciamento da AWS ] **Para criar um plano de uso** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. No painel de navegação principal do API Gateway, escolha **Planos de uso** e **Criar plano de uso**. ![\[Entidades de plano de uso de API\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-setup.png) 1. Em **Nome**, insira um nome. 1. (Opcional) Em **Description (Descrição)**, insira uma descrição. 1. Por padrão, os planos de uso permitem o controle de utilização. Insira uma **Taxa** e um **Pico** para seu plano de uso. Escolha **Controle de utilização** para desativar o controle de utilização. 1. Por padrão, os planos de uso permitem uma cota por um período. Em **Solicitações**, insira o número total de solicitações que um usuário pode fazer no período do plano de uso. Escolha **Cota** para desativar a cota. 1. Escolha **Criar plano de uso**. ------ #### [ AWS CLI ] O comando [create-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan.html) indicado abaixo criar um plano de uso que é redefinido no início do mês: ``` 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 ] Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlan.html) para criar um plano de uso. ------ ## Adicionar um estágio de API a um plano de uso O procedimento a seguir descreve como adicionar um estágio a um plano de uso. ------ #### [ Console de gerenciamento da AWS ] **Como adicionar um estágio a um plano de uso** 1. Selecione o plano de uso. 1. Na guia **Estágios associados**, escolha **Adicionar estágio**. ![\[Adicione um estágio de API a um plano de uso.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-stage.png) 1. Em **API**, selecione uma API. 1. Em **Estágio**, selecione um estágio. 1. (Opcional) Para ativar o controle de utilização no nível do método, faça o seguinte: 1. Escolha **Controle de utilização no nível do método** e **Adicionar método**. 1. Em **Recurso**, selecione um recurso da API. 1. Em **Método**, selecione um método da API. 1. Insira uma **Taxa** e um **Pico** para seu plano de uso. 1. Escolha **Adicionar ao plano de uso**. ------ #### [ AWS CLI ] O comando [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html) indicado abaixo adiciona o estágio `Prod` de uma API a um plano de uso: ``` aws apigateway update-usage-plan \ --usage-plan-id abc123 \ --patch-operations op="add",path="/apiStages",value="a1b1c2:Prod" ``` ------ #### [ REST API ] Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) para atualizar um plano de uso. ------ ## Adicionar uma chave de API a um plano de uso O procedimento a seguir mostra como adicionar uma chave de API a um plano de uso. ------ #### [ Console de gerenciamento da AWS ] **Como adicionar uma chave a um plano de uso** 1. Na guia **Chaves de API associadas**, escolha **Adicionar chave de API**. ![\[Entidades de plano de uso de API\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-new-console-usage-plan-keys-create-add-key.png) 1. 1. Para associar uma chave existente ao plano de uso, selecione **Adicionar chave existente** e escolha a respectiva chave no menu suspenso. 1. Para criar uma chave de API, selecione **Criar e adicionar nova chave** e crie uma chave. Para obter mais informações sobre como criar uma chave, consulte [Criar uma chave de API](api-gateway-setup-api-keys.md#api-gateway-usage-plan-create-apikey). 1. Escolha **Adicionar chave de API**. ------ #### [ AWS CLI ] O comando [create-usage-plan-key](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-usage-plan-key.html) indicado abaixo associa uma chave de API existente a um plano de uso: ``` aws apigateway create-usage-plan-key \ --usage-plan-id a1b2c3 \ --key-type "API_KEY" \ --key-id aaa111bbb ``` ------ #### [ REST API ] Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateUsagePlanKey.html) para associar uma chave de API existente a um plano de uso. Você também pode associar diretamente as chaves de API a um plano de uso ao importá-las. Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportApiKeys.html) 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. # Manter um plano de uso para APIs REST no API Gateway A manutenção de um plano de uso requer o monitoramento das cotas usadas e restantes durante determinado período e, se necessário, a extensão das cotas restantes de acordo com uma quantidade especificada. Os procedimentos a seguir descrevem como monitorar cotas. ------ #### [ Console de gerenciamento da AWS ] **Para monitorar as cotas usadas e restantes** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. No painel de navegação principal do API Gateway, escolha **Planos de uso**. 1. Selecione um plano de uso. 1. Escolha a guia **Chaves de API associadas** para ver o número de solicitações restantes no período de cada chave. 1. (Opcional) Escolha **Exportar dados de uso** e escolha uma data para **De** e uma data para **Até**. Depois, escolha **JSON** ou **CSV** para o formato de dados exportados e selecione **Exportar**. O exemplo a seguir mostra um arquivo exportado. ``` { "px1KW6...qBazOJH": [ [ 0, 5000 ], [ 0, 5000 ], [ 0, 10 ] ] } ``` Os dados de uso no exemplo mostram os dados de uso diários para um cliente de API, conforme identificado pela chave de API (`px1KW6...qBazOJH`), entre 1º de agosto de 2016 e 3 de agosto de 2016. Cada dado de uso diário mostra as cotas usadas e restantes. Nesse exemplo, o assinante não utilizou as cotas alocadas ainda, e o proprietário ou o administrador da API reduziu a cota restante de 5000 para 10 no terceiro dia. Os procedimentos a seguir descrevem como modificar cotas. **Para estender as cotas restantes** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. No painel de navegação principal do API Gateway, escolha **Planos de uso**. 1. Selecione um plano de uso. 1. Escolha a guia **Chaves de API associadas** para ver o número de solicitações restantes no período de cada chave. 1. Selecione uma chave de API e escolha **Conceder extensão de uso**. 1. Insira um número para a cota de **Solicitações restantes**. Você pode aumentar as solicitações de renomeação ou diminuir as solicitações restantes durante o período do plano de uso. 1. Escolha **Atualizar cota**. ------ #### [ AWS CLI ] Os exemplos de código [update-usage-plan](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-usage-plan.html) a seguir adicionam, removem ou modificam as configurações de controle de utilização em nível de método em um plano de uso. **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}}"' ``` ------ #### [ REST API ] Chame [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html) para manter um plano de uso. ------ # Criar e configurar chaves de API e planos de uso com o CloudFormation É possível usar o CloudFormation para exigir chaves de API em métodos de API e criar um plano de uso para uma API. O modelo do CloudFormation de exemplo faz o seguinte: + Cria uma API do API Gateway com os métodos `GET` e `POST`. + Exige uma chave de API para os métodos `GET` e `POST`. Essa API recebe chaves do cabeçalho `X-API-KEY` de cada solicitação recebida. + Cria uma chave de API. + Cria um plano de uso para especificar uma cota mensal de 1.000 solicitações por mês, um limite de taxa de controle de utilização de 100 solicitações por segundo e um limite de intermitência de controle de utilização de 200 solicitações por segundo. + Especifica um limite de taxa de controle de utilização no nível do método de 50 solicitações por segundo e um limite de intermitência de controle de utilização no nível do método de 100 solicitações por segundo para o método `GET`. + Associa o estágio da API e a chave de API ao plano 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}' ``` # Configurar um método para usar chaves de API com uma definição OpenAPI Você pode usar uma definição OpenAPI para exigir chaves de API em um método. Para cada método, crie um objeto de requisito de segurança a fim de exigir uma chave de API para invocar esse método. Em seguida, defina `api_key` na configuração de segurança. Depois de criar a API, adicione o estágio da nova API ao plano de uso. O exemplo a seguir cria uma API e exige uma chave de API para os métodos `POST` e `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" } } } } ``` ------ # Testar planos de uso para APIs REST no API Gateway Como exemplo, vamos usar a API PetStore, que foi criada em [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). 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. No entanto, registrará uma mensagem de erro de `Usage Plan check failed due to an internal error` no CloudWatch. Você pode ignorar esses erros ocasionais. # Chamar um método usando uma chave de API Dependendo do tipo escolhido de origem da chave de API, use um dos seguintes procedimentos para usar chaves de API originadas de cabeçalho ou chaves de API retornadas por um autorizador em um método de invocação: **Para usar chaves de API originadas de cabeçalho:** 1. Crie uma API com os métodos de API desejados e implante a API em um estágio. 1. Crie um novo plano de uso ou escolha um novo. Adicione o estágio de API implantado ao plano de uso. Anexe uma chave de API ao plano de uso ou escolha uma chave de API existente no plano. Observe o valor da chave de API escolhido. 1. Configure métodos de API para exigir uma chave de API. 1. Reimplante a API para o mesmo estágio. Se você implantar a API para um novo estágio, certifique-se de atualizar o plano de uso a fim de anexar o novo estágio de API. 1. Chame a API usando a chave de API. O exemplo de comando curl a seguir invoca o método `GET`no recurso `getUsers` do estágio `prod` de uma API usando uma chave de API. ``` curl -H "X-API-Key: abcd1234" 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers' ``` Agora o cliente pode chamar métodos de API enquanto fornece o cabeçalho `x-api-key` com a chave de API escolhida como o valor do cabeçalho. Uma chamada pode ser semelhante ao seguinte: **Para usar chaves de API originadas de um autorizador:** 1. Crie uma API com os métodos de API desejados e implante a API em um estágio. 1. Crie um novo plano de uso ou escolha um novo. Adicione o estágio de API implantado ao plano de uso. Anexe uma chave de API ao plano de uso ou escolha uma chave de API existente no plano. Observe o valor da chave de API escolhido. 1. Crie um autorizador do Lambda com base em token. Inclua `usageIdentifierKey:{api-key}` como uma propriedade em nível de raiz da resposta de autorização. Para encontrar instruções sobre como criar um autorizador baseado em token, consulte [Exemplo de função do Lambda do autorizador `TOKEN`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create). 1. Configure métodos de API para exigir uma chave de API e habilite o autorizador do Lambda nos métodos. 1. Reimplante a API para o mesmo estágio. Se você implantar a API para um novo estágio, certifique-se de atualizar o plano de uso a fim de anexar o novo estágio de API. Agora, o cliente pode chamar os métodos de API que exigem chave sem fornecer explicitamente qualquer chave de API. A chave de API retornada pelo autorizador é usada automaticamente.