Criar estágios para APIs de WebSocket no API Gateway

O estágio de uma API é uma referência lógica a um estado do ciclo de vida de sua API (por exemplo, dev, prod, beta ou v2). Os estágios de API são identificados por seu ID de API e nome de estágio e são incluídos no URL que você usa para chamar a API. Cada estágio é uma referência nomeada a uma implantação da API e é disponibilizado para chamadas feitas por aplicativos cliente.

Uma implantação é um instantâneo da configuração da API. Depois de implantar uma API em um estágio, ela estará disponível para ser chamada por clientes. Você deve implantar uma API para que as alterações entrem em vigor.

Variáveis de estágio

As variáveis de estágio são pares chave-valor que você pode definir para um estágio de uma API WebSocket. Elas atuam como variáveis de ambiente e podem ser usadas na configuração da API.

Por exemplo, você pode definir uma variável de estágio e, depois, definir seu valor como um endpoint HTTP para uma integração de proxy HTTP. Posteriormente, você pode fazer referência ao endpoint usando o nome da variável de estágio associada. Fazendo isso, você pode usar a mesma configuração de API com um endpoint diferente em cada estágio. Da mesma forma, você pode usar variáveis de estágio para especificar uma integração de função diferente do AWS Lambda para cada estágio da API.

nota

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

Exemplos

Para usar uma variável de estágio para personalizar o endpoint de integração HTTP, primeiro defina o nome e o valor da variável de estágio (por exemplo, url) com um valor de example.com. Depois, 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 do estágio da API.

É possível fazer referência a variáveis de estágio de forma semelhante para especificar um nome de função do Lambda ou um ARN de função da AWS.

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. Você pode usar a AWS Command Line Interface (AWS CLI) para fazer isso.

aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction

Referência de variáveis de estágio do API Gateway

URIs de integração HTTP

Uma variável de estágio pode ser usada como parte de um URI de integração HTTP, como mostram os exemplos a seguir.

• Um URI completo sem protocol – http://${stageVariables.<variable_name>}

• Um domínio complet – http://${stageVariables.<variable_name>}/resource/operation

• Um subdomíni – http://${stageVariables.<variable_name>}.example.com/resource/operation

• Um caminh – http://example.com/${stageVariables.<variable_name>}/bar

• Uma string de consult – http://example.com/foo?q=${stageVariables.<variable_name>}

Funções do Lambda

É possível usar uma variável de estágio no lugar de um nome de função ou alias do Lambda, conforme mostrado nos exemplos a seguir.

• arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:${stageVariables.<function_variable_name>}/invocations

• arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/arn:aws:lambda:<region>:<account_id>:function:<function_name>:${stageVariables.<version_variable_name>}/invocations

nota

Para usar uma variável de estágio para uma função do Lambda, a função deve estar na mesma conta que a API. As variáveis de estágio não suportam funções do Lambda entre contas.

AWSCredenciais de integração da

É possível usar uma variável de estágio como parte de um ARN de credencial de usuário ou de função da AWS, conforme mostrado no exemplo a seguir.

• arn:aws:iam::<account_id>:${stageVariables.<variable_name>}