Configurar variáveis de estágio para a implantação de uma API REST

Variáveis de estágio são pares de nome/valor que você pode definir como atributos de configuração associados a um estágio de implantação de uma API REST. Elas atuam como variáveis de ambiente e podem ser usadas em seus modelos de configuração e mapeamento de API.

Por exemplo, você pode definir uma variável de estágio em uma configuração de estágio e, em seguida, definir seu valor como a string de URL de uma integração HTTP para um método na sua API REST. Posteriormente, você pode fazer referência à string do URL usando o nome da variável de estágio associada da configuração da API. Dessa forma, é possível usar a mesma configuração de API com um endpoint diferente em cada estágio, redefinindo o valor da variável de estágio para os URLs correspondentes.

Você também pode acessar variáveis de estágio em modelos de mapeamento ou passar parâmetros de configuração ao backend HTTP ou AWS Lambda .

Para obter mais informações sobre modelos de mapeamento, consulte Referência de variáveis de registro em log de acesso e modelo de mapeamento do API Gateway.

nota

As variáveis de estágio não se destinam a ser usadas para dados confidenciais, como credenciais. Para passar dados confidenciais para integrações, use um AWS Lambda autorizador. Você pode passar dados confidenciais para integrações na saída do autorizador do Lambda. Para saber mais, consulte Saída de um autorizador do Lambda do Amazon API Gateway.

Casos de uso

Com estágios de implantação no API Gateway, você pode gerenciar vários estágios de versão para cada API, como alfa, beta e produção. Usando variáveis de estágio, você pode configurar um estágio de implantação da API para interagir com diferentes endpoints de backend.

Por exemplo, sua API pode passar uma solicitação GET como um proxy HTTP ao host da Web do backend (por exemplo, http://example.com). Nesse caso, o host da Web do backend está configurado em uma variável de estágio de forma que, quando os desenvolvedores chamarem seu endpoint de produção, o API Gateway chamará example.com. Quando você chama o endpoint beta, o API Gateway usa o valor configurado na variável de estágio para o estágio beta e chama um host da Web diferente (por exemplo, beta.example.com). Da mesma forma, as variáveis de estágio podem ser usadas para especificar um nome de AWS Lambda função diferente para cada estágio em sua API.

Você também pode usar variáveis de estágio para transmitir parâmetros de configuração para uma função do Lambda por meio de seus modelos de mapeamento. Por exemplo, talvez você queira reutilizar a mesma função do Lambda para vários estágios na sua API, mas a função deve ler dados de outra tabela do Amazon DynamoDB, dependendo de qual estágio está sendo chamado. Nos modelos de mapeamento que geram a solicitação para a função do Lambda, você pode usar variáveis de estágio para transmitir o nome da tabela ao Lambda.

Exemplos

Para usar uma variável de estágio para personalizar o endpoint de integração HTTP, primeiro configure uma variável de estágio com um nome especificado (por exemplo, url) e depois atribua a ela um valor, (por exemplo, example.com). Depois, em seu método de configuração, configure uma integração de proxy HTTP. Em vez de inserir o URL do endpoint, você pode instruir o API Gateway a usar o valor da variável de estágio, http://${stageVariables.url}. Esse valor instrui o API Gateway a substituir sua variável de estágio ${} em tempo de execução, dependendo de qual estágio sua API está executando.

Você pode referenciar variáveis de estágio de forma semelhante para especificar um nome de função Lambda, um caminho do AWS Service Proxy ou um AWS ARN de função no campo de credenciais.

Ao especificar um nome de função do Lambda como um valor de variável de estágio, você deve configurar as permissões nessa função do Lambda manualmente. Quando você especifica uma função Lambda no console do API Gateway, um AWS CLI comando aparece para configurar as permissões adequadas. Você também pode usar o AWS Command Line Interface (AWS CLI) para fazer isso.

aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction