# 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.