# Desenvolver APIs HTTP no API Gateway Esta seção fornece detalhes sobre os recursos necessários do API Gateway durante o desenvolvimento de suas APIs do API Gateway. Ao desenvolver a API do API Gateway, você decidirá uma série de características da API. Essas características dependem do caso de uso da sua API. Por exemplo, talvez você queira permitir que somente determinados clientes chamem sua API ou talvez queira disponibilizá-las a todos. É recomendável que uma chamada de API execute uma função do Lambda, faça uma consulta de banco de dados ou chame uma aplicação. **Topics** + [Criar uma API HTTP](#http-api-examples) + [Criar rotas para APIs HTTP no API Gateway](http-api-develop-routes.md) + [Tipos de endereço IP para APIs HTTP no API Gateway](http-api-ip-address-type.md) + [Controlar e gerenciar o acesso a APIs HTTP no API Gateway](http-api-access-control.md) + [Criar integrações para APIs HTTP no API Gateway](http-api-develop-integrations.md) + [Configurar CORS para APIs HTTP no API Gateway](http-api-cors.md) + [Transformar solicitações e respostas de API para APIs HTTP no API Gateway](http-api-parameter-mapping.md) + [Usar definições do OpenAPI para APIs HTTP no API Gateway](http-api-open-api.md) ## Criar uma API HTTP Para criar uma API funcional, você deve ter pelo menos uma rota, integração, estágio e implantação. Os exemplos a seguir mostram como criar uma API com uma integração de AWS Lambda ou HTTP, uma rota e um estágio padrão configurado para implantar alterações automaticamente. Este guia pressupõe que você já está familiarizado com o API Gateway e o Lambda. Para obter uma lista mais detalhada, consulte [Começar a usar o API Gateway](getting-started.md) **Topics** + [Crie uma API HTTP usando o Console de gerenciamento da AWS](#apigateway-http-api-create.console) + [Criar uma API HTTP usando a CLI da AWS](#http-api-examples.cli.quick-create) ### Crie uma API HTTP usando o Console de gerenciamento da AWS 1. Abra o [console do API Gateway](https://console.aws.amazon.com/apigateway). 1. Selecione **Create API** (Criar API). 1. Em **HTTP API (API HTTP)**, escolha **Build (Criar)**. 1. Escolha **Add integration (Adicionar integração)** e, em seguida, escolha uma função do AWS Lambda ou insira um endpoint HTTP. 1. Em **Name (Nome)**, insira um nome para a sua API. 1. Selecione **Review and create**. 1. Escolha **Create** (Criar). Agora sua API está pronta para invocar. Você pode testar sua API inserindo seu URL de invocação em um navegador ou usando Curl. ``` curl https://api-id.execute-api.us-east-2.amazonaws.com ``` ### Criar uma API HTTP usando a CLI da AWS É possível usar a criação rápida para criar uma API com uma integração do Lambda ou HTTP, uma rota padrão genérica e um estágio padrão configurado para implantar alterações automaticamente. O comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) a seguir usa criação rápida para criar uma API que se integra a uma função do Lambda no backend. **nota** Para invocar uma integração do Lambda, o API Gateway deve ter as permissões obrigatórias. Você pode usar uma política baseada em recursos ou uma função do IAM para conceder permissões do API Gateway para invocar uma função do Lambda. Para saber mais, consulte [AWS Lambda Permissões](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html) no *Guia do desenvolvedor do AWS Lambda*. **Example** ``` aws apigatewayv2 create-api --name my-api --protocol-type HTTP --target arn:aws:lambda:us-east-2:123456789012:function:function-name ``` Agora sua API está pronta para invocar. Você pode testar sua API inserindo seu URL de invocação em um navegador ou usando Curl. ``` curl https://api-id.execute-api.us-east-2.amazonaws.com ``` # Criar rotas para APIs HTTP no API Gateway Roteia solicitações diretas recebidas de API para recursos de backend. As rotas consistem em duas partes: um método HTTP e um caminho de recurso, por exemplo, `GET /pets`. É possível definir métodos HTTP específicos para a rota. Ou usar o método `ANY` para corresponder a todos os métodos não definidos para um recurso. Você pode criar uma rota `$default` que funciona como um catch-all para solicitações que não correspondem a nenhuma outra rota. **nota** O API Gateway decodifica parâmetros de solicitação codificados em URL antes de passá-los para integrações de back-end. ## Trabalhar com variáveis de caminho É possível usar variáveis de caminho em rotas de API HTTP. Por exemplo, a rota `GET /pets/{petID}` captura uma solicitação `GET` que um cliente envia para `https://api-id.execute-api.us-east-2.amazonaws.com/pets/6`. Uma *variável de caminho voraz* captura todos os recursos filho de uma rota. Para criar uma variável de caminho voraz, adicione `+` ao nome da variável, por exemplo, `{proxy+}`. O parâmetro de caminho voraz deve estar no final do caminho do recurso. ## Trabalhar com parâmetros de string de consulta Por padrão, o API Gateway enviará parâmetros de string de consulta para a integração de backend se eles estiverem incluídos em uma solicitação para uma API Gateway. Por exemplo, quando um cliente envia uma solicitação para `https://api-id.execute-api.us-east-2.amazonaws.com/pets?id=4&type=dog`, os parâmetros de string de consulta `?id=4&type=dog` são enviados para a integração. ## Trabalhar com a rota `$default` A rota `$default` captura solicitações que não correspondem explicitamente a outras rotas na API. Quando a rota `$default` recebe uma solicitação, o API Gateway envia o caminho de solicitação completo para a integração. Por exemplo, é possível criar uma API com apenas uma rota `$default` e integrá-la ao método `ANY` com o endpoint do HTTP `https://petstore-demo-endpoint.execute-api.com`. Quando uma solicitação é enviada para `https://api-id.execute-api.us-east-2.amazonaws.com/store/checkout`, o API Gateway envia uma solicitação para `https://petstore-demo-endpoint.execute-api.com/store/checkout`. Para saber mais sobre integrações HTTP, consulte [Criar integrações de proxy HTTP para APIs HTTP](http-api-develop-integrations-http.md). ## Rotear solicitações de API Quando um cliente envia uma solicitação de API, o API Gateway primeiro determina para qual [estágio](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-stages.html) rotear a solicitação. Se a solicitação corresponder explicitamente a um estágio, o API Gateway enviará a solicitação para esse estágio. Se nenhum estágio corresponder totalmente à solicitação, o API Gateway enviará a solicitação para o estágio `$default`. Se não houver estágio `$default`, a API retornará `{"message":"Not Found"}` e não gerará logs do CloudWatch. Depois de selecionar um estágio, o API Gateway seleciona uma rota. Ele seleciona a rota com a correspondência mais específica, usando as seguintes prioridades: 1. Correspondência completa para uma rota e um método. 1. Correspondência para uma rota e um método com uma variável de caminho voraz (`{proxy+}`). 1. A rota `$default`. Se nenhuma rota corresponder a uma solicitação, o API Gateway retornará `{"message":"Not Found"}` ao cliente. Por exemplo, considere uma API com um estágio `$default` e as seguintes rotas de exemplo: 1. `GET /pets/dog/1` 1. `GET /pets/dog/{id}` 1. `GET /pets/{proxy+}` 1. `ANY /{proxy+}` 1. `$default` A tabela a seguir resume como o API Gateway roteia solicitações para as rotas demonstrativas. | Solicitação | Rota selecionada | Explicação | | --- | --- | --- | | `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/1` | `GET /pets/dog/1` | A solicitação corresponde totalmente a esta rota estática. | | `GET https://api-id.execute-api.region.amazonaws.com/pets/dog/2` | `GET /pets/dog/{id}` | A solicitação corresponde totalmente a essa rota. | | `GET https://api-id.execute-api.region.amazonaws.com/pets/cat/1` | `GET /pets/{proxy+}` | A solicitação não corresponde totalmente a uma rota. A rota com um método `GET` e uma variável de caminho voraz captura essa solicitação. | | `POST https://api-id.execute-api.region.amazonaws.com/test/5` | `ANY /{proxy+}` | O método `ANY` corresponde a todos os métodos não definidos para uma rota. Rotas com variáveis de caminho voraz têm prioridade mais alta que a rota `$default`. | # Tipos de endereço IP para APIs HTTP no API Gateway Ao criar uma API, você especifica o tipo de endereços IP que podem invocar sua API. É possível escolher IPv4 para resolver endereços IPv4 e invocar sua API ou escolher pilha dupla para permitir que endereços IPv4 e IPv6 invoquem sua API. Recomendamos que você defina o tipo de endereço IP como pilha dupla para aliviar o esgotamento do espaço IP ou para seu procedimento de segurança. Para ter mais informações sobre os benefícios de um tipo de endereço IP de pilha dupla, consulte [IPv6 na AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html). ## Considerações sobre tipos de endereço IP As seguintes considerações podem afetar o uso de tipos de endereço IP: + O tipo de endereço IP padrão para APIs HTTP é IPv4. + Se você alterar o tipo de endereço IP de uma API existente de IPv4 para pilha dupla, confirme se todas as políticas que controlam o acesso às suas APIs foram atualizadas para considerar as chamadas IPv6. Quando você altera o tipo de endereço IP, a alteração entra em vigor imediatamente. + Sua API pode ser associada a um nome de domínio personalizado com um tipo de endereço IP diferente do da sua API. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar sua API. ## Alterar o tipo de endereço IP de uma API HTTP É possível alterar o tipo de endereço IP atualizando a configuração da API. É possível atualizar a configuração da API usando o Console de gerenciamento da AWS, a AWS CLI, o CloudFormation ou um SDK da AWS. Se você alterar o tipo de endereço IP da API, não poderá reimplantá-la para que as alterações entrem em vigor. ------ #### [ Console de gerenciamento da AWS ] **Como alterar o tipo de endereço IP de uma API HTTP** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione uma API HTTP. 1. Em **Configurações da API**, escolha **Editar**. 1. Em Tipo de endereço IP, escolha **IPv4** ou **Pilha dupla**. 1. Escolha **Salvar**. A alteração na configuração da sua API entrará em vigor imediatamente. ------ #### [ AWS CLI ] O comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) a seguir atualiza uma API para ter um tipo de endereço IP de pilha dupla: ``` aws apigatewayv2 update-api \ --api-id abcd1234 \ --ip-address-type dualstack ``` A saída será exibida da seguinte forma: ``` { "ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com", "ApiId": "abcd1234", "ApiKeySelectionExpression": "$request.header.x-api-key", "CreatedDate": "2025-02-04T22:20:20+00:00", "DisableExecuteApiEndpoint": false, "Name": "My-HTTP-API", "ProtocolType": "HTTP", "RouteSelectionExpression": "$request.method $request.path", "Tags": {}, "NotificationUris": [], "IpAddressType": "dualstack" } ``` ------ # Controlar e gerenciar o acesso a APIs HTTP no API Gateway O API Gateway é compatível com vários mecanismos de controle de acesso à sua API HTTP: + **Autorizadores do Lambda** usam funções do Lambda para controlar o acesso a APIs. Para obter mais informações, consulte [Controlar o acesso a APIs HTTP com autorizadores do AWS Lambda](http-api-lambda-authorizer.md). + **Os autorizadores do JWT** usam tokens da Web JSON para controlar o acesso a APIs. Para obter mais informações, consulte [Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway](http-api-jwt-authorizer.md). + As **funções e políticas padrão do AWS IAM** oferecem controles de acesso flexíveis e robustos. É possível usar as funções e políticas do IAM para controlar quem pode criar e gerenciar suas APIs, bem como quem pode invocá-las. Para obter mais informações, consulte [Controlar o acesso a APIs HTTP com autorização do IAM no API Gateway](http-api-access-control-iam.md). Para melhorar seu procedimento de segurança, recomendamos que você configure um autorizador para todas as rotas na sua API HTTP. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) no *Guia do usuário do AWS Security Hub*. # Controlar o acesso a APIs HTTP com autorizadores do AWS Lambda Use um autorizador do Lambda para utilizar uma função do Lambda a fim de controlar o acesso à sua API HTTP. Depois, quando um cliente chamar a API, o API Gateway invocará sua função do Lambda. O API Gateway usará a resposta da função do Lambda para determinar se o cliente pode acessar sua API. ## Versão do formato da carga útil A versão do formato de carga do autorizador especifica o formato dos dados que o API Gateway envia a um autorizador do Lambda e como o API Gateway interpreta a resposta do Lambda. Por padrão, se você não especificar uma versão de formato de carga útil, o Console de gerenciamento da AWS usará a versão mais recente. Se você criar um autorizador do Lambda usando a AWS CLI, o CloudFormation ou um SDK, será necessário especificar um `authorizerPayloadFormatVersion`. Os valores suportados são `1.0` e `2.0`. Se precisar de compatibilidade com APIs REST, use a versão `1.0`. Os exemplos a seguir mostram a estrutura de cada versão do formato de carga útil. ------ #### [ 2.0 ] ``` { "version": "2.0", "type": "REQUEST", "routeArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request", "identitySource": ["user1", "123"], "routeKey": "$default", "rawPath": "/my/path", "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", "cookies": ["cookie1", "cookie2"], "headers": { "header1": "value1", "header2": "value2" }, "queryStringParameters": { "parameter1": "value1,value2", "parameter2": "value" }, "requestContext": { "accountId": "123456789012", "apiId": "api-id", "authentication": { "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "http": { "method": "POST", "path": "/my/path", "protocol": "HTTP/1.1", "sourceIp": "IP", "userAgent": "agent" }, "requestId": "id", "routeKey": "$default", "stage": "$default", "time": "12/Mar/2020:19:03:58 +0000", "timeEpoch": 1583348638390 }, "pathParameters": { "parameter1": "value1" }, "stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" } } ``` ------ #### [ 1.0 ] ``` { "version": "1.0", "type": "REQUEST", "methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request", "identitySource": "user1,123", "authorizationToken": "user1,123", "resource": "/request", "path": "/request", "httpMethod": "GET", "headers": { "X-AMZ-Date": "20170718T062915Z", "Accept": "*/*", "HeaderAuth1": "headerValue1", "CloudFront-Viewer-Country": "US", "CloudFront-Forwarded-Proto": "https", "CloudFront-Is-Tablet-Viewer": "false", "CloudFront-Is-Mobile-Viewer": "false", "User-Agent": "..." }, "queryStringParameters": { "QueryString1": "queryValue1" }, "pathParameters": {}, "stageVariables": { "StageVar1": "stageValue1" }, "requestContext": { "path": "/request", "accountId": "123456789012", "resourceId": "05c7jb", "stage": "test", "requestId": "...", "identity": { "apiKey": "...", "sourceIp": "...", "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "resourcePath": "/request", "httpMethod": "GET", "apiId": "abcdef123" } } ``` ------ ## Formato de resposta do autorizador do Lambda A versão do formato de carga também determina a estrutura da resposta que deve ser retornada pela função do Lambda. ### Resposta de função do Lambda para o formato 1.0 Se você escolher a versão de formato `1.0`, os autorizadores do Lambda deverão retornar uma política do IAM que permita ou negue acesso à sua rota da API. É possível usar a sintaxe de política do IAM padrão na política. Para obter políticas demonstrativas do IAM, consulte [Controlar o acesso para chamar uma API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). É possível transmitir propriedades de contexto para integrações do Lambda ou logs de acesso usando `$context.authorizer.property`. O objeto `context` é opcional e `claims` é um espaço reservado que não pode ser usado como objeto de contexto. Para saber mais, consulte [Personalizar logs de acesso à API HTTP](http-api-logging-variables.md). **Example** **** ``` { "principalId": "abcdef", "policyDocument": { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow|Deny", "Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]" } ] }, "context": { "exampleKey": "exampleValue" } } ``` ### Resposta de função do Lambda para o formato 2.0 Se você escolher a versão de formato `2.0`, poderá retornar um valor booliano ou uma política do IAM que use a sintaxe de política padrão do IAM da sua função do Lambda. Para retornar um valor booliano, ative respostas simples para o autorizador. Os exemplos a seguir demonstram o formato que você deve codificar para ser retornado pela sua função do Lambda. O objeto `context` é opcional. É possível transmitir propriedades de contexto para integrações do Lambda ou logs de acesso usando `$context.authorizer.property`. Para saber mais, consulte [Personalizar logs de acesso à API HTTP](http-api-logging-variables.md). ------ #### [ Simple response ] ``` { "isAuthorized": true/false, "context": { "exampleKey": "exampleValue" } } ``` ------ #### [ IAM policy ] **** ``` { "principalId": "abcdef", "policyDocument": { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow|Deny", "Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]" } ] }, "context": { "exampleKey": "exampleValue" } } ``` ------ ## Funções demonstrativas do autorizador do Lambda As funções demonstrativas do Lambda Node.js a seguir mostram os formatos de resposta que você precisa retornar de sua função do Lambda para a versão de formato de carga `2.0`. ------ #### [ Simple response - Node.js ] ``` export const handler = async(event) => { let response = { "isAuthorized": false, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": true, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } }; if (event.headers.authorization === "secretToken") { console.log("allowed"); response = { "isAuthorized": true, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": true, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } }; } return response; }; ``` ------ #### [ Simple response - Python ] ``` import json def lambda_handler(event, context): response = { "isAuthorized": False, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": True, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } } try: if (event["headers"]["authorization"] == "secretToken"): response = { "isAuthorized": True, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": True, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } } print('allowed') return response else: print('denied') return response except BaseException: print('denied') return response ``` ------ #### [ IAM policy - Node.js ] ``` export const handler = async(event) => { if (event.headers.authorization == "secretToken") { console.log("allowed"); return { "principalId": "abcdef", // The principal user identification associated with the token sent by the client. "policyDocument": { "Version": "2012-10-17", "Statement": [{ "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": event.routeArn }] }, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": true, "arrayKey": ["value1", "value2"], "mapKey": { "value1": "value2" } } }; } else { console.log("denied"); return { "principalId": "abcdef", // The principal user identification associated with the token sent by the client. "policyDocument": { "Version": "2012-10-17", "Statement": [{ "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": event.routeArn }] }, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": true, "arrayKey": ["value1", "value2"], "mapKey": { "value1": "value2" } } }; } }; ``` ------ #### [ IAM policy - Python ] ``` import json def lambda_handler(event, context): response = { # The principal user identification associated with the token sent by # the client. "principalId": "abcdef", "policyDocument": { "Version": "2012-10-17", "Statement": [{ "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": event["routeArn"] }] }, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": True, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } } try: if (event["headers"]["authorization"] == "secretToken"): response = { # The principal user identification associated with the token # sent by the client. "principalId": "abcdef", "policyDocument": { "Version": "2012-10-17", "Statement": [{ "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": event["routeArn"] }] }, "context": { "stringKey": "value", "numberKey": 1, "booleanKey": True, "arrayKey": ["value1", "value2"], "mapKey": {"value1": "value2"} } } print('allowed') return response else: print('denied') return response except BaseException: print('denied') return response ``` ------ ## Fontes de identidade Também é possível especificar fontes de identidade para um autorizador do Lambda. As fontes de identidade especificam a localização dos dados necessários para autorizar uma solicitação. Por exemplo, é possível especificar valores de cabeçalho ou string de consulta como origens de identidade. Se você especificar fontes de identidade, os clientes deverão incluí-las na solicitação. Se a solicitação do cliente não incluir as fontes de identidade, o API Gateway não invocará o autorizador do Lambda, e o cliente receberá um erro `401`. A tabela a seguir descreve as fontes de identidade compatíveis com um autorizador do Lambda. | **Tipo** | **Exemplo do** | **Observações** | | --- | --- | --- | | Valor de cabeçalho | \$1request.header.nome | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. | | Valor da string de consulta | \$1request.querystring.nome | Os nomes de strings de consulta diferenciam maiúsculas e minúsculas | | Variável de contexto | \$1context.variableName | O valor de uma [variável de contexto](http-api-logging-variables.md) compatível. | | Variável de estágio | \$1stageVariables.variableName | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). | Você também pode retornar diretamente ` {"errorMessage" : "Unauthorized"}` da função do Lambda para exibir um erro `401` aos clientes. Se você retornar diretamente um erro `401` da função do Lambda para os clientes, não especifique nenhuma fonte de identidade ao criar o autorizador do Lambda. ## Armazenar em cache respostas do autorizador É possível habilitar o armazenamento em cache para um autorizador do Lambda especificando um [authorizerResultTtlInSeconds](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers.html#apis-apiid-authorizers-prop-createauthorizerinput-authorizerresultttlinseconds). Quando o cache está habilitado para um autorizador, o API Gateway usa as fontes de identidade do autorizador como a chave de cache. Se um cliente especificar os mesmos parâmetros em fontes de identidade dentro do TTL configurado, o API Gateway usará o resultado do autorizador em cache em vez de invocar sua função do Lambda. Para habilitar o cache, seu autorizador deve ter pelo menos uma fonte de identidade. Se você habilitar respostas simples para um autorizador, a resposta do autorizador permitirá ou negará totalmente todas as solicitações de API que correspondam aos valores da fonte de identidade armazenados em cache. Para obter permissões mais granulares, desative respostas simples e retorne uma política do IAM. Dependendo do seu autorizador, sua política de IAM pode precisar controlar o acesso a vários recursos. Por padrão, o API Gateway usa a resposta do autorizador em cache para todas as rotas de uma API que usam o autorizador. Para armazenar em cache as respostas por rota, adicione `$context.routeKey` às fontes de identidade do seu autorizador. ## Criar um autorizador do Lambda Ao criar um autorizador do Lambda, especifique a função do Lambda a ser usada pelo API Gateway. É necessário conceder permissão do API Gateway para invocar a função do Lambda usando a política de recursos da função ou uma função do IAM. O comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) indicado abaixo cria um autorizador do Lambda: ``` aws apigatewayv2 create-authorizer \ --api-id abcdef123 \ --authorizer-type REQUEST \ --identity-source '$request.header.Authorization' \ --name lambda-authorizer \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:my-function/invocations' \ --authorizer-payload-format-version '2.0' \ --enable-simple-responses ``` O comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) a seguir atualiza a política de recursos da função do Lambda para conceder permissão ao API Gateway para invocar a função. Se o API Gateway não tiver permissão para invocar sua função, os clientes receberão um `500 Internal Server Error`. ``` aws lambda add-permission \ --function-name my-authorizer-function \ --statement-id apigateway-invoke-permissions-abc123 \ --action lambda:InvokeFunction \ --principal apigateway.amazonaws.com \ --source-arn "arn:aws:execute-api:us-west-2:123456789012:api-id/authorizers/authorizer-id" ``` Depois de criar um autorizador e conceder ao API Gateway permissão para invocá-lo, atualize sua rota para usar o autorizador. O comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) a seguir adiciona o autorizador do Lambda à rota. Se seu autorizador do Lambda usa o armazenamento em cache de política, atualize a política para controlar o acesso ao método adicional. ``` aws apigatewayv2 update-route \ --api-id abcdef123 \ --route-id abc123 \ --authorization-type CUSTOM \ --authorizer-id def123 ``` ## Solução de problemas em autorizadores do Lambda Se o API Gateway não conseguir invocar o autorizador do Lambda, ou se o autorizador do Lambda retornar uma resposta em um formato inválido, os clientes receberão um arquivo `500 Internal Server Error`. Para solucionar erros, [habilite o registro em log de acesso](http-api-logging.md) para o estágio da API. Inclua a variável de registro em log `$context.authorizer.error` em seu formato de log. Se os logs indicarem que o API Gateway não tem permissão para invocar sua função, atualize a política de recursos da função ou forneça uma função do IAM para conceder ao API Gateway permissão para invocar o autorizador. Se os logs indicarem que a função do Lambda retorna uma resposta inválida, verifique se a função do Lambda retorna uma resposta no [formato necessário](#http-api-lambda-authorizer.payload-format-response). # Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway O JSON Web Tokens (JWTs) pode ser usado como parte das estruturas [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html) e [OAuth 2.0](https://oauth.net/2/) para que você possa restringir o acesso do cliente às suas APIs. Se você configurar um autorizador JWT para uma rota da sua API, o API Gateway valida os JWTs enviados pelos clientes com solicitações de API. O API Gateway aceita ou rejeita solicitações com base na validação de tokens e, opcionalmente, escopos no token. Se você configurar escopos para uma rota, o token deverá incluir pelo menos um dos escopos da rota. Você pode configurar autorizadores distintos para cada rota de uma API ou usar o mesmo autorizador para várias rotas. **nota** Não existe nenhum mecanismo padrão para diferenciar tokens de acesso JWT de outros tipos de JWTs, como os tokens OpenID e Connect ID. Exceto se precisar de tokens de ID para autorização de API, recomendamos que você configure suas rotas para exigir escopos de autorização. Você também pode configurar seus autorizadores do JWT para exigir emissores ou públicos que seu provedor de identidade usa somente ao emitir tokens de acesso do JWT. ## Autorização de solicitações de API com um autorizador JWT O API Gateway usa o fluxo de trabalho geral a seguir para autorizar solicitações para rotas configuradas para usar um autorizador JWT. 1. Verifique se há um token em [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-prop-authorizer-identitysource). O `identitySource` pode incluir apenas o token ou o token com o prefixo `Bearer`. 1. Decodifique o token. 1. Verifique o algoritmo e a assinatura do token usando a chave pública obtida do do emisso `jwks_uri`. No momento, somente algoritmos baseados em RSA são compatíveis. O API Gateway pode armazenar a chave pública em cache por duas horas. Como prática recomendada, ao alternar as chaves, aguarde um período de carência durante o qual as chaves antigas e novas sejam válidas. 1. Valide reivindicações. O API Gateway avalia as seguintes reivindicações de token: + [https://datatracker.ietf.org/doc/html/rfc7517#section-4.5](https://datatracker.ietf.org/doc/html/rfc7517#section-4.5): o token deve ter uma reivindicação de cabeçalho que corresponda à chave no `jwks_uri` que assinou o token. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1): deve corresponder ao [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configurado para o autorizador. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3) ou `client_id`: deve corresponder a uma das entradas [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-authorizers-authorizerid.html#apis-apiid-authorizers-authorizerid-model-jwtconfiguration) configuradas para o autorizador. O API Gateway valida `client_id` somente se `aud` não estiver presente. Quando `aud` e `client_id` estão presentes, o API Gateway avalia `aud`. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) – deve ser após a hora atual em UTC. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) – deve ser antes da hora atual em UTC. + [https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) – deve ser antes da hora atual em UTC. + [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) ou `scp`: o token deve incluir pelo menos um dos escopos em [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid.html#apis-apiid-routes-routeid-prop-updaterouteinput-authorizationscopes) da rota. Se qualquer uma dessas etapas falhar, o API Gateway negará a solicitação de API. Depois de validar o JWT, o API Gateway passa as alegações no token para a integração da rota da API. Recursos de backend, como as funções do Lambda, podem acessar as alegações de JWT. Por exemplo, se o JWT incluiu um `emailID` de alegação de identidade, ele estará disponível para uma integração do Lambda em `$event.requestContext.authorizer.jwt.claims.emailID`. Para obter mais informações sobre a carga útil que o API Gateway envia para integrações do Lambda, consulte [Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway](http-api-develop-integrations-lambda.md). ## Criar um autorizador de JWT Antes de criar um autorizador de JWT, você deve registrar um aplicativo cliente com um provedor de identidade. Também deve ter criado uma API HTTP. Para obter exemplos de criação de uma API HTTP, consulte [Criar uma API HTTP](http-api-develop.md#http-api-examples). ### Criar um autorizador JWT usando o console As etapas a seguir mostram como criar o autorizador JWT usando o console. **Criar um autorizador JWT usando o console** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione uma API HTTP. 1. No painel de navegação principal, selecione **Autorização**. 1. Escolha a guia **Gerenciar autorizadores**. 1. Escolha **Criar**. 1. Em **Tipo de autorizador**, escolha **JWT**. 1. Configure o autorizador JWT e especifique uma **Origem da identidade** que defina a origem do token. 1. Escolha **Criar**. #### Criar um autorizador JWT usando a AWS CLI O comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-authorizer.html) a seguir cria um autorizador de JWT. Para `jwt-configuration`, especifique o `Audience` e o `Issuer` para seu provedor de identidades. Se você usa o Amazon Cognito como provedor de identidade, o `IssuerUrl` é `https://cognito-idp.us-east-2.amazonaws.com/userPoolID`. ``` aws apigatewayv2 create-authorizer \ --name authorizer-name \ --api-id api-id \ --authorizer-type JWT \ --identity-source '$request.header.Authorization' \ --jwt-configuration Audience=audience,Issuer=IssuerUrl ``` ##### Criar um autorizador de AWS CloudFormation O modelo CloudFormation a seguir cria uma API HTTP com um autorizador JWT usando o Amazon Cognito como provedor de identidade. A saída do modelo CloudFormation é um URL para uma interface de usuário hospedada no Amazon Cognito, na qual os clientes podem se inscrever e fazer login para receber um JWT. Depois que o cliente faz login, é redirecionado para sua API HTTP com um token de acesso no URL. Para invocar a API com o token de acesso, altere o `#` no URL para um `?` para usar o token como um parâmetro de string de consulta. ##### Exemplo de modelo CloudFormation ``` AWSTemplateFormatVersion: '2010-09-09' Description: | Example HTTP API with a JWT authorizer. This template includes an Amazon Cognito user pool as the issuer for the JWT authorizer and an Amazon Cognito app client as the audience for the authorizer. The outputs include a URL for an Amazon Cognito hosted UI where clients can sign up and sign in to receive a JWT. After a client signs in, the client is redirected to your HTTP API with an access token in the URL. To invoke the API with the access token, change the '#' in the URL to a '?' to use the token as a query string parameter. Resources: MyAPI: Type: AWS::ApiGatewayV2::Api Properties: Description: Example HTTP API Name: api-with-auth ProtocolType: HTTP Target: !GetAtt MyLambdaFunction.Arn DefaultRouteOverrides: Type: AWS::ApiGatewayV2::ApiGatewayManagedOverrides Properties: ApiId: !Ref MyAPI Route: AuthorizationType: JWT AuthorizerId: !Ref JWTAuthorizer JWTAuthorizer: Type: AWS::ApiGatewayV2::Authorizer Properties: ApiId: !Ref MyAPI AuthorizerType: JWT IdentitySource: - '$request.querystring.access_token' JwtConfiguration: Audience: - !Ref AppClient Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool} Name: test-jwt-authorizer MyLambdaFunction: Type: AWS::Lambda::Function Properties: Runtime: nodejs18.x Role: !GetAtt FunctionExecutionRole.Arn Handler: index.handler Code: ZipFile: | exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify('Hello from the ' + event.routeKey + ' route!'), }; return response; }; APIInvokeLambdaPermission: Type: AWS::Lambda::Permission Properties: FunctionName: !Ref MyLambdaFunction Action: lambda:InvokeFunction Principal: apigateway.amazonaws.com SourceArn: !Sub arn:${AWS::Partition}:execute-api:${AWS::Region}:${AWS::AccountId}:${MyAPI}/$default/$default FunctionExecutionRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Version: '2012-10-17 ' Statement: - Effect: Allow Principal: Service: - lambda.amazonaws.com Action: - 'sts:AssumeRole' ManagedPolicyArns: - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole UserPool: Type: AWS::Cognito::UserPool Properties: UserPoolName: http-api-user-pool AutoVerifiedAttributes: - email Schema: - Name: name AttributeDataType: String Mutable: true Required: true - Name: email AttributeDataType: String Mutable: false Required: true AppClient: Type: AWS::Cognito::UserPoolClient Properties: AllowedOAuthFlows: - implicit AllowedOAuthScopes: - aws.cognito.signin.user.admin - email - openid - profile AllowedOAuthFlowsUserPoolClient: true ClientName: api-app-client CallbackURLs: - !Sub https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com ExplicitAuthFlows: - ALLOW_USER_PASSWORD_AUTH - ALLOW_REFRESH_TOKEN_AUTH UserPoolId: !Ref UserPool SupportedIdentityProviders: - COGNITO HostedUI: Type: AWS::Cognito::UserPoolDomain Properties: Domain: !Join - '-' - - !Ref MyAPI - !Ref AppClient UserPoolId: !Ref UserPool Outputs: SignupURL: Value: !Sub https://${HostedUI}.auth.${AWS::Region}.amazoncognito.com/login?client_id=${AppClient}&response_type=token&scope=email+profile&redirect_uri=https://${MyAPI}.execute-api.${AWS::Region}.amazonaws.com ``` ## Atualizar uma rota para usar um autorizador JWT Você pode usar o console, a AWS CLI ou um AWS SDK para atualizar uma rota para usar um autorizador JWT. ### Atualizar uma rota para usar um autorizador JWT com o console As etapas a seguir mostram como atualizar uma rota para usar o autorizador JWT com o console. **Para criar um autorizador JWT usando o console** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione uma API HTTP. 1. No painel de navegação principal, selecione **Autorização**. 1. Escolha um método, selecione o autorizador no menu suspenso e escolha **Anexar autorizador**. #### Atualizar uma rota para usar um autorizador JWT com a AWS CLI O comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) indicado abaixo atualiza uma rota para usar um autorizador de JWT: ``` aws apigatewayv2 update-route \ --api-id api-id \ --route-id route-id \ --authorization-type JWT \ --authorizer-id authorizer-id \ --authorization-scopes user.email ``` # Controlar o acesso a APIs HTTP com autorização do IAM no API Gateway É possível habilitar a autorização do IAM para rotas de API HTTP. Quando a autorização do IAM está habilitada, os clientes precisam usar o [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) para assinar suas solicitações com credenciais da AWS. O API Gateway invocará sua rota de API somente se o cliente tiver a permissão `execute-api` para a rota. A autorização do IAM para APIs HTTP é semelhante à das [APIs REST](api-gateway-control-access-using-iam-policies-to-invoke-api.md). **nota** Atualmente, as políticas de recursos não são compatíveis com as APIs HTTP. Para obter políticas demonstrativas do IAM que concedem aos clientes permissão para invocar APIs, consulte [Controlar o acesso para chamar uma API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). ## Habilitar a autorização do IAM para uma rota O comando [update-rout](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) indicado abaixo habilita a autorização do IAM para uma rota de API HTTP: ``` aws apigatewayv2 update-route \ --api-id abc123 \ --route-id abcdef \ --authorization-type AWS_IAM ``` # Criar integrações para APIs HTTP no API Gateway *Integrações* conectam uma rota aos recursos de backend. As APIs HTTP são compatíveis com integrações de proxy do Lambda, serviços da AWS e proxy HTTP. Por exemplo, é possível configurar uma solicitação `POST` para a rota `/signup` da sua API para se integrar a uma função do Lambda que lida com o cadastro de clientes. **Topics** + [Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway](http-api-develop-integrations-lambda.md) + [Criar integrações de proxy HTTP para APIs HTTP](http-api-develop-integrations-http.md) + [Criar integrações de serviços da AWS para APIs HTTP no API Gateway](http-api-develop-integrations-aws-services.md) + [Criar integrações privadas para APIs HTTP no API Gateway](http-api-develop-integrations-private.md) # Criar integrações de proxy AWS Lambda para APIs HTTP no API Gateway Uma integração de proxy do Lambda permite integrar uma rota de API com uma função do Lambda. Quando um cliente chama sua API, o API Gateway envia a solicitação para a função do Lambda e retorna a resposta da função para o cliente. Para obter exemplos de criação de uma API HTTP, consulte [Criar uma API HTTP](http-api-develop.md#http-api-examples). ## Versão do formato da carga útil A versão do formato de carga útil especifica o formato do evento que o API Gateway envia para uma integração do Lambda e como o API Gateway interpreta a resposta do Lambda. Por padrão, se você não especificar uma versão de formato de carga útil, o Console de gerenciamento da AWS usará a versão mais recente. Se você criar uma integração do Lambda usando a AWS CLI, o CloudFormation ou um SDK, será necessário especificar um `payloadFormatVersion`. Os valores suportados são `1.0` e `2.0`. Para saber mais sobre como definir o`payloadFormatVersion`, consulte [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html). Para saber mais sobre como determinar a `payloadFormatVersion` de uma integração existente, consulte [get-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-integration.html). ### Diferenças do formato da carga útil A lista a seguir mostra as diferenças entre as versões do formato da carga útil `1.0` e `2.0`: + O formato `2.0` não tem campos `multiValueHeaders` ou `multiValueQueryStringParameters`. Os cabeçalhos duplicados são combinados com vírgulas e incluídos no campo `headers`. As strings de consulta duplicadas são combinadas com vírgulas e incluídas no campo `queryStringParameters`. + O formato `2.0` tem `rawPath`. Se você usar um mapeamento de API para associar o estágio a um nome de domínio personalizado, `rawPath` não fornecerá o valor do mapeamento de API. Use o formato `1.0` e `path` para acessar o mapeamento da API de seu nome de domínio personalizado. + O formato `2.0` inclui um novo campo `cookies`. Todos os cabeçalhos de cookie na solicitação são combinados com vírgulas e adicionados ao campo `cookies`. Na resposta ao cliente, cada cookie torna-se um cabeçalho `set-cookie`. ### Estrutura do formato da carga útil Os exemplos a seguir mostram a estrutura de cada versão do formato de carga útil. Todos os nomes de cabeçalho ficam em letras minúsculas. ------ #### [ 2.0 ] ``` { "version": "2.0", "routeKey": "$default", "rawPath": "/my/path", "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", "cookies": [ "cookie1", "cookie2" ], "headers": { "header1": "value1", "header2": "value1,value2" }, "queryStringParameters": { "parameter1": "value1,value2", "parameter2": "value" }, "requestContext": { "accountId": "123456789012", "apiId": "api-id", "authentication": { "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "authorizer": { "jwt": { "claims": { "claim1": "value1", "claim2": "value2" }, "scopes": [ "scope1", "scope2" ] } }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "http": { "method": "POST", "path": "/my/path", "protocol": "HTTP/1.1", "sourceIp": "192.0.2.1", "userAgent": "agent" }, "requestId": "id", "routeKey": "$default", "stage": "$default", "time": "12/Mar/2020:19:03:58 +0000", "timeEpoch": 1583348638390 }, "body": "Hello from Lambda", "pathParameters": { "parameter1": "value1" }, "isBase64Encoded": false, "stageVariables": { "stageVariable1": "value1", "stageVariable2": "value2" } } ``` ------ #### [ 1.0 ] ``` { "version": "1.0", "resource": "/my/path", "path": "/my/path", "httpMethod": "GET", "headers": { "header1": "value1", "header2": "value2" }, "multiValueHeaders": { "header1": [ "value1" ], "header2": [ "value1", "value2" ] }, "queryStringParameters": { "parameter1": "value1", "parameter2": "value" }, "multiValueQueryStringParameters": { "parameter1": [ "value1", "value2" ], "parameter2": [ "value" ] }, "requestContext": { "accountId": "123456789012", "apiId": "id", "authorizer": { "claims": null, "scopes": null }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "extendedRequestId": "request-id", "httpMethod": "GET", "identity": { "accessKey": null, "accountId": null, "caller": null, "cognitoAuthenticationProvider": null, "cognitoAuthenticationType": null, "cognitoIdentityId": null, "cognitoIdentityPoolId": null, "principalOrgId": null, "sourceIp": "192.0.2.1", "user": null, "userAgent": "user-agent", "userArn": null, "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "path": "/my/path", "protocol": "HTTP/1.1", "requestId": "id=", "requestTime": "04/Mar/2020:19:15:17 +0000", "requestTimeEpoch": 1583349317135, "resourceId": null, "resourcePath": "/my/path", "stage": "$default" }, "pathParameters": null, "stageVariables": null, "body": "Hello from Lambda!", "isBase64Encoded": false } ``` ------ ## Formato de resposta da função do Lambda A versão do formato da carga determina a estrutura da resposta que a função do Lambda deve retornar. ### Resposta de função do Lambda para o formato 1.0 Com a versão do formato `1.0`, as integrações do Lambda devem retornar uma resposta no formato JSON a seguir: **Example** ``` { "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headername": "headervalue", ... }, "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... }, "body": "..." } ``` ### Resposta de função do Lambda para o formato 2.0 Com a versão de formato `2.0`, o API Gateway pode inferir o formato de resposta para você. O API Gateway fará as suposições a seguir se sua função do Lambda retornar JSON válido e não retornar um `statusCode`: + `isBase64Encoded` é `false`. + `statusCode` é `200`. + `content-type` é `application/json`. + `body` é a resposta da função. Os exemplos a seguir mostram a saída de uma função do Lambda e a interpretação do API Gateway. | Saída da função do Lambda | Interpretação do API Gateway | | --- | --- | | 
"Hello from Lambda!"
| 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "Hello from Lambda!",
  "headers": {
    "content-type": "application/json"
  }
}
| | 
{ "message": "Hello from Lambda!" }
| 
{
  "isBase64Encoded": false,
  "statusCode": 200,
  "body": "{ \"message\": \"Hello from Lambda!\" }",
  "headers": {
    "content-type": "application/json"
  }
}
| Para personalizar a resposta, a função do Lambda deve retornar uma resposta com o formato a seguir. ``` { "cookies" : ["cookie1", "cookie2"], "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headername": "headervalue", ... }, "body": "Hello from Lambda!" } ``` # Criar integrações de proxy HTTP para APIs HTTP Uma integração de proxy HTTP permite que você conecte uma rota de API a um endpoint HTTP roteável publicamente. Com esse tipo de integração, o API Gateway transmite toda a solicitação e resposta entre o front-end e o backend. Para criar uma integração de proxy HTTP, forneça a URL de um endpoint HTTP roteável publicamente. ## Integração de proxy HTTP com variáveis de caminho É possível usar variáveis de caminho em rotas de API HTTP. Por exemplo, a rota `/pets/{petID}` captura solicitações para a `/pets/6`. Você pode fazer referência a variáveis de caminho no URI de integração para enviar o conteúdo das variáveis para uma integração. Um exemplo é `/pets/extendedpath/{petID}`. Você pode usar variáveis de caminho voraz para capturar todos os recursos filho de uma rota. Para criar uma variável de caminho voraz, adicione `+` ao nome da variável, por exemplo, `{proxy+}`. Para configurar uma rota com uma integração de proxy HTTP que captura todas as solicitações, crie uma rota de API com uma variável de caminho voraz (por exemplo, `/parent/{proxy+}`). Integre a rota a um endpoint HTTP (por exemplo, `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`) no método `ANY`. O parâmetro de caminho voraz deve estar no final do caminho do recurso. # Criar integrações de serviços da AWS para APIs HTTP no API Gateway Você pode integrar sua API HTTP com serviços da AWS usando *integrações de primeira classe*. Uma integração de primeira classe conecta uma rota de API HTTP a uma API de serviço da AWS. Quando um cliente invoca uma rota apoiada por uma integração de primeira classe, o API Gateway invoca uma API de serviço da AWS para você. Por exemplo, é possível usar integrações de primeira classe para enviar uma mensagem para uma fila do Amazon Simple Queue Service ou iniciar uma máquina de estado do AWS Step Functions. Para obter ações de serviço compatíveis, consulte [Referência do subtipo de integração](http-api-develop-integrations-aws-services-reference.md). ## Mapear parâmetros de solicitação Integrações de primeira classe têm parâmetros obrigatórios e opcionais. É necessário configurar todos os parâmetros necessários para criar uma integração. Você pode usar valores estáticos ou mapear parâmetros que são avaliados dinamicamente no tempo de execução. Para obter uma lista completa de integrações e parâmetros compatíveis, consulte [Referência do subtipo de integração](http-api-develop-integrations-aws-services-reference.md). A tabela a seguir descreve os parâmetros de solicitação de mapeamento compatíveis. | Tipo | Exemplo | Observações | | --- | --- | --- | | Valor de cabeçalho | \$1request.header.nome | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2". | | Valor da string de consulta | \$1request.querystring.nome | Os nomes de strings de consulta diferenciam maiúsculas e minúsculas O API Gateway combina vários valores com vírgulas, por exemplo, "querystring1": "Value1,Value2". | | Parâmetro de caminho | \$1request.path.name | O valor de um parâmetro de caminho na solicitação. Por exemplo, se a rota for /pets/\$1petId\$1, você poderá mapear o parâmetro petId da solicitação com \$1request.path.petId. | | Solicitar passagem do corpo | \$1request.body | O API Gateway transmite todo o corpo da solicitação. | | Corpo da solicitação | \$1request.body.name | Uma [expressão de caminho JSON](https://goessner.net/articles/JsonPath/index.html#e2). Descidas recursivas (\$1request.body..name) e expressões de filtro (?(expression)) não são compatíveis. Quando você especifica um caminho JSON, o API Gateway trunca o corpo da solicitação em 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique `$request.body`. | | Variável de contexto | \$1context.variableName | O valor de uma [variável de contexto](http-api-logging-variables.md) compatível. | | Variável de estágio | \$1stageVariables.variableName | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). | | Valor estático | string | Um valor constante. | ## Criar uma integração de primeira classe Antes de criar uma integração de primeira classe, é necessário criar uma função do IAM que conceda ao API Gateway permissões para invocar a ação de serviço da AWS à qual você está se integrando. Para saber mais, consulte [Criação de uma função para um serviço da AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html). Para criar uma integração de primeira classe, escolha uma ação de serviço da AWS compatível, como `SQS-SendMessage`, configure os parâmetros de solicitação e forneça uma função que conceda ao API Gateway permissões para invocar a API de serviço integrado da AWS. Dependendo do subtipo de integração, diferentes parâmetros de solicitação são necessários. Para saber mais, consulte [Referência do subtipo de integração](http-api-develop-integrations-aws-services-reference.md). O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo cria uma integração que envia uma mensagem do Amazon SQS: ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-subtype SQS-SendMessage \ --integration-type AWS_PROXY \ --payload-format-version 1.0 \ --credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \ --request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}' ``` ## Criar uma integração de primeira classe usando o CloudFormation O exemplo a seguir mostra um trecho do CloudFormation que cria uma rota `/{source}/{detailType}` com uma integração de primeira classe com o Amazon EventBridge. O parâmetro `Source` é mapeado para o parâmetro de caminho `{source}`, o `DetailType` é mapeado para o parâmetro de caminho `{DetailType}` e o parâmetro `Detail` é mapeado para o corpo da solicitação. O trecho não mostra o barramento de eventos ou o perfil do IAM que concede permissões ao API Gateway para invocar a ação `PutEvents`. ``` Route: Type: AWS::ApiGatewayV2::Route Properties: ApiId: !Ref HttpApi AuthorizationType: None RouteKey: 'POST /{source}/{detailType}' Target: !Join - / - - integrations - !Ref Integration Integration: Type: AWS::ApiGatewayV2::Integration Properties: ApiId: !Ref HttpApi IntegrationType: AWS_PROXY IntegrationSubtype: EventBridge-PutEvents CredentialsArn: !GetAtt EventBridgeRole.Arn RequestParameters: Source: $request.path.source DetailType: $request.path.detailType Detail: $request.body EventBusName: !GetAtt EventBus.Arn PayloadFormatVersion: "1.0" ``` # Referência do subtipo de integração Os [subtipos de integração](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationsubtype) a seguir são compatíveis com APIs HTTP. **Topics** + [EventBridge-PutEvents 1.0](#EventBridge-PutEvents) + [SQS-SendMessage 1.0](#SQS-SendMessage) + [SQS-ReceiveMessage 1.0](#SQS-ReceiveMessage) + [SQS-DeleteMessage 1.0](#SQS-DeleteMessage) + [SQS-PurgeQueue 1.0](#SQS-PurgeQueue) + [AppConfig-GetConfiguration 1.0](#AppConfig-GetConfiguration) + [Kinesis-PutRecord 1.0](#Kinesis-PutRecord) + [StepFunctions-StartExecution 1.0](#StepFunctions-StartExecution) + [StepFunctions-StartSyncExecution 1.0](#StepFunctions-StartSyncExecution) + [StepFunctions-StopExecution 1.0](#StepFunctions-StopExecution) ## EventBridge-PutEvents 1.0 Envia eventos personalizados para o Amazon EventBridge para que eles possam ser correspondidos a regras. | Parâmetro | Obrigatório | | --- | --- | | Detalhes | Verdadeiro | | DetailType | Verdadeiro | | Origem | Verdadeiro | | Tempo | Falso | | EventBusName | Falso | | Recursos | Falso | | Região | Falso | | TraceHeader | Falso | Para saber mais, consulte [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) na *Referência de API do Amazon EventBridge*. ## SQS-SendMessage 1.0 Entrega uma mensagem para a fila especificada. | Parâmetro | Obrigatório | | --- | --- | | QueueUrl | Verdadeiro | | MessageBody | Verdadeiro | | DelaySeconds | Falso | | MessageAttributes | Falso | | MessageDeduplicationId | Falso | | MessageGroupId | Falso | | MessageSystemAttributes | Falso | | Região | Falso | Para saber mais, consulte [SendMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) na *Referência de API do Amazon Simple Queue Service*. ## SQS-ReceiveMessage 1.0 Recupera uma ou mais mensagens (até 10) de uma fila especificada. | Parâmetro | Obrigatório | | --- | --- | | QueueUrl | Verdadeiro | | AttributeNames | Falso | | MaxNumberOfMessages | Falso | | MessageAttributeNames | Falso | | ReceiveRequestAttemptId | Falso | | VisibilityTimeout | Falso | | WaitTimeSeconds | Falso | | Região | Falso | Para saber mais, consulte [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) na *Referência de API do Amazon Simple Queue Service*. ## SQS-DeleteMessage 1.0 Exclui a mensagem especificada da fila especificada. | Parâmetro | Obrigatório | | --- | --- | | ReceiptHandle | Verdadeiro | | QueueUrl | Verdadeiro | | Região | Falso | Para saber mais, consulte [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) na *Referência de API do Amazon Simple Queue Service*. ## SQS-PurgeQueue 1.0 Exclui todas as mensagens da fila especificada. | Parâmetro | Obrigatório | | --- | --- | | QueueUrl | Verdadeiro | | Região | Falso | Para saber mais, consulte [PurgeQueue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_PurgeQueue.html) na *Referência de API do Amazon Simple Queue Service*. ## AppConfig-GetConfiguration 1.0 Receba informações sobre uma configuração. | Parâmetro | Obrigatório | | --- | --- | | Aplicativo | Verdadeiro | | Ambiente | Verdadeiro | | Configuração | Verdadeiro | | ClientId | Verdadeiro | | ClientConfigurationVersion | Falso | | Região | Falso | Para saber mais, consulte [GetConfiguration](https://docs.aws.amazon.com/appconfig/2019-10-09/APIReference/API_GetConfiguration.html) na *Referência da API AppConfig da AWS*. ## Kinesis-PutRecord 1.0 Grava um único registro de dados em um stream de dados do Amazon Kinesis. | Parâmetro | Obrigatório | | --- | --- | | StreamName | Verdadeiro | | Dados | Verdadeiro | | PartitionKey | Verdadeiro | | SequenceNumberForOrdering | Falso | | ExplicitHashKey | Falso | | Região | Falso | Para saber mais, consulte [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) na *Referência de API do Amazon Kinesis Data Streams*. ## StepFunctions-StartExecution 1.0 Inicia uma execução de máquina de estado. | Parâmetro | Obrigatório | | --- | --- | | StateMachineArn | Verdadeiro | | Nome | Falso | | Entrada | Falso | | Região | Falso | Para saber mais, consulte [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) na *Referência da API do AWS Step Functions*. ## StepFunctions-StartSyncExecution 1.0 Inicia uma execução de máquina de estado síncrono. | Parâmetro | Obrigatório | | --- | --- | | StateMachineArn | Verdadeiro | | Nome | Falso | | Entrada | Falso | | Região | Falso | | TraceHeader | Falso | Para saber mais, consulte [StartSyncExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) na *Referência da API do AWS Step Functions*. ## StepFunctions-StopExecution 1.0 Interrompe uma execução. | Parâmetro | Obrigatório | | --- | --- | | ExecutionArn | Verdadeiro | | Causa | Falso | | Erro | Falso | | Região | Falso | Para saber mais, consulte [StopExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html) na *Referência da API do AWS Step Functions*. # Criar integrações privadas para APIs HTTP no API Gateway As integrações privadas permitem que você crie integrações de API com recursos privados em uma VPC, como Application Load Balancers ou aplicações baseadas em contêiner do Amazon ECS. Você pode expor seus recursos em uma VPC para acesso por clientes fora da VPC usando integrações privadas. Você pode controlar o acesso à sua API usando qualquer um dos [ métodos de autorização](http-api-access-control.md) compatíveis com o API Gateway. **nota** Para criar uma integração privada, primeiro crie um link de VPC. Os links da VPC V2 agora comportam APIs HTTP e REST. Para saber mais sobre links da VPC V2, consulte [Configurar links da VPC V2 no API Gateway](apigateway-vpc-links-v2.md). Depois de criar um link da VPC V2, é possível configurar integrações privadas que se conectam a um Application Load Balancer, Network Load Balancer ou a recursos registrados em um serviço do AWS Cloud Map. ## Considerações As considerações a seguir podem afetar o uso de integrações privadas: + Todos os recursos devem ser de propriedade da mesma Conta da AWS. Isso inclui o balanceador de carga ou o serviço AWS Cloud Map, o link da VPC e a API HTTP. + Por padrão, o tráfego de integração privada usa o protocolo HTTP. Para usar HTTPS, especifique uma [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html). Para fazer isso usando o Console de gerenciamento da AWS, ao criar sua integração privada, escolha **Configurações avançadas** e, depois, insira um nome de servidor seguro. + Para integrações privadas, o API Gateway inclui a parte do [estágio](http-api-stages.md) do endpoint da API na solicitação para seus recursos de backend. Por exemplo, uma solicitação para o estágio `test` de uma API inclui `test/route-path` na solicitação para sua integração privada. Para remover o nome do estágio da solicitação para os seus recursos de backend, use o [mapeamento de parâmetros](http-api-parameter-mapping.md) para substituir o caminho da solicitação para `$request.path`. ## Criar uma integração privada usando um Application Load Balancer ou Network Load Balancer Antes de criar uma integração privada, você deve criar um link da VPC V2. Para saber mais sobre links da VPC V2, consulte [Configurar links da VPC V2 no API Gateway](apigateway-vpc-links-v2.md). Para criar uma integração privada com um Application Load Balancer ou Network Load Balancer, crie uma integração de proxy HTTP, especifique o link de VPC a ser usado e forneça o ARN de listener do balanceador de carga. O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo cria uma integração privada que se conecta a um balanceador de carga usando um link de VPC. ``` aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \ --integration-method GET --connection-type VPC_LINK \ --connection-id VPC-link-ID \ --integration-uri arn:aws:elasticloadbalancing:us-east-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/0467ef3c8400ae65 --payload-format-version 1.0 ``` ## Criar uma integração privada usando a descoberta de serviço do AWS Cloud Map Antes de criar uma integração privada, você deve criar um link da VPC V2. Para saber mais sobre links de VPC, consulte [Configurar links da VPC V2 no API Gateway](apigateway-vpc-links-v2.md). Para integrações com o AWS Cloud Map, o API Gateway usa `DiscoverInstances` para identificar recursos. Você pode usar parâmetros de consulta para direcionar recursos específicos. Os atributos dos recursos registrados devem incluir endereços IP e portas. O API Gateway distribui solicitações entre recursos íntegros que são retornados de `DiscoverInstances`. Para saber mais, consulte [DiscoverInstances](https://docs.aws.amazon.com/cloud-map/latest/api/API_DiscoverInstances.html) na Referência da API do AWS Cloud Map. **nota** Se usar o Amazon ECS para preencher entradas no AWS Cloud Map, você deverá configurar a tarefa do Amazon ECS para usar registros SRV com a descoberta de serviços do Amazon ECS ou ativar o Amazon ECS Service Connect. Para obter mais informações, consulte [Interconexão de serviços](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/interconnecting-services.html) no Guia do desenvolvedor do Amazon Elastic Container Service. Para criar uma integração privada com o AWS Cloud Map, crie uma integração de proxy HTTP, especifique o link de VPC a ser usado e forneça o ARN do serviço AWS Cloud Map. O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo cria uma integração privada que usa a descoberta de serviços do AWS Cloud Map para identificar recursos: ``` aws apigatewayv2 create-integration --api-id api-id --integration-type HTTP_PROXY \ --integration-method GET --connection-type VPC_LINK \ --connection-id VPC-link-ID \ --integration-uri arn:aws:servicediscovery:us-east-2:123456789012:service/srv-id?stage=prod&deployment=green_deployment --payload-format-version 1.0 ``` # Configurar CORS para APIs HTTP no API Gateway O [compartilhamento de recursos entre origens (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) é um recurso de segurança de navegador que restringe as solicitações HTTP que são iniciadas em scripts em execução no navegador. Se você não conseguir acessar sua API e receber uma mensagem de erro contendo `Cross-Origin Request Blocked`, talvez seja necessário habilitar o CORS. Consulte mais informações em [O que é CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/). Normalmente o CORS é necessário para criar aplicativos Web que acessem APIs hospedadas em um domínio ou origem diferente. O CORS pode ser habilitado para permitir solicitações para sua API a partir de um aplicativo Web hospedado em um domínio diferente. Por exemplo, se sua API estiver hospedada em `https://{api_id}.execute-api.{region}.amazonaws.com/`, e você quiser chamar sua API a partir de um aplicativo web hospedado no `example.com`, sua API deverá ser compatível com CORS. Se você configurar o CORS para uma API, o API Gateway enviará automaticamente uma resposta às solicitações de comprovação OPTIONS, mesmo que não haja uma rota OPTIONS configurada para sua API. Para uma solicitação CORS, o API Gateway adiciona os cabeçalhos de CORS configurados à resposta de uma integração. **nota** Se você configurar CORS para uma API, o API Gateway ignorará os cabeçalhos de CORS retornados de sua integração de backend. Em uma configuração de CORS, é possível especificar os parâmetros a seguir. Para adicionar esses parâmetros usando o console da API HTTP do API Gateway, selecione **Adicionar** depois de inserir o valor. | Cabeçalhos de CORS | Propriedade da configuração de CORS | Exemplos de valores | | --- | --- | --- | | Access-Control-Allow-Origin | allowOrigins | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/http-api-cors.html) | | Access-Control-Allow-Credentials | allowCredentials | true | | Access-Control-Expose-Headers | exposeHeaders | date, x-api-id, \$1 | | Access-Control-Max-Age | maxAge | 300 | | Access-Control-Allow-Methods | allowMethods | GET, POST, DELETE, \$1 | | Access-Control-Allow-Headers | allowHeaders | authorization, \$1 | Para retornar cabeçalhos CORS, sua solicitação deve conter um cabeçalho `origin`. Para o método `OPTIONS`, sua solicitação deve conter um cabeçalho `origin` e um cabeçalho `Access-Control-Request-Method`. A configuração de CORS pode parecer com a seguinte imagem: ![\[Configuração de CORS para APIs HTTP\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/http-cors-console.png) ## Configurar o CORS para uma API HTTP com uma rota `$default` e um autorizador É possível habilitar o CORS e configurar a autorização para qualquer rota de uma API HTTP. Quando você habilita o CORS e a autorização para a [rota `$default`](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html#http-api-develop-routes.default), há algumas considerações especiais. A rota `$default` captura solicitações para todos os métodos e rotas não definidos explicitamente, inclusive solicitações `OPTIONS`. Para oferecer suporte a solicitações `OPTIONS` não autorizadas, adicione uma rota `OPTIONS /{proxy+}` à API que não exija autorização e anexe uma integração à rota. A rota `OPTIONS /{proxy+}` tem prioridade mais alta que a `$default`. Como resultado, ela permite que os clientes enviem solicitações `OPTIONS` para a API sem autorização. Para obter mais informações sobre prioridades de roteamento, consulte [Rotear solicitações de API](http-api-develop-routes.md#http-api-develop-routes.evaluation). ## Configurar o CORS para uma API HTTP usando a CLI da AWS O comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) a seguir habilita as solicitações de CORS em `https://www.example.com`. **Example** ``` aws apigatewayv2 update-api --api-id api-id --cors-configuration AllowOrigins="https://www.example.com" ``` Para obter mais informações, consulte [CORS](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid.html#apis-apiid-model-cors) na Referência de API do Amazon API Gateway versão 2. # Transformar solicitações e respostas de API para APIs HTTP no API Gateway Você pode modificar solicitações de API dos clientes antes que eles atinjam suas integrações de backend. Você também pode alterar a resposta das integrações antes que o API Gateway retorne a resposta aos clientes. Use o *mapeamento de parâmetros* para modificar solicitações e respostas de API para APIs HTTP. Para usar o mapeamento de parâmetros, especifique os parâmetros de solicitação de API ou resposta a serem modificados e especifique como modificar esses parâmetros. ## Transformação de solicitações de API Você usa parâmetros de solicitação para alterar solicitações antes que elas atinjam suas integrações de backend. Você pode modificar cabeçalhos, strings de consulta ou o caminho da solicitação. Os parâmetros de solicitação são um mapa de chave-valor. A chave identifica a localização do parâmetro da solicitação a ser alterado e como alterá-lo. O valor especifica os novos dados para o parâmetro. A tabela a seguir mostra as chaves suportadas. | Tipo | Sintaxe | | --- | --- | | Cabeçalho | append\$1overwrite\$1remove:header.headername | | String de consulta | append\$1overwrite\$1remove:querystring.querystring-name | | Caminho | overwrite:path | A tabela a seguir mostra os valores suportados que você pode mapear para parâmetros. | Tipo | Sintaxe | Observações | | --- | --- | --- | | Valor de cabeçalho | \$1request.header.name ou \$1\$1request.header.name\$1 | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2". Alguns cabeçalhos são reservados. Para saber mais, consulte [Cabeçalhos reservados](#http-api-mapping-reserved-headers). | | Valor da string de consulta | \$1request.querystring.name ou \$1\$1request.querystring.name\$1 | Os nomes de strings de consulta diferenciam maiúsculas e minúsculas O API Gateway combina vários valores com vírgulas, por exemplo, "querystring1" "Value1,Value2". | | Corpo da solicitação | \$1request.body.name ou \$1\$1request.body.name\$1 | Uma expressão de caminho JSON. Descida recursiva (\$1request.body..name) e expressões de filtro (?(expression)) não são suportadas. Quando você especifica um caminho JSON, o API Gateway trunca o corpo da solicitação em 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique `$request.body`. | | O caminho da solicitação. | \$1request.path ou \$1\$1request.path\$1 | O caminho da solicitação, sem o nome do estágio. | | Parâmetro de caminho | \$1request.path.name ou \$1\$1request.path.name\$1 | O valor de um parâmetro de caminho na solicitação. Por exemplo, se a rota for /pets/\$1petId\$1, você poderá mapear o parâmetro petId da solicitação com \$1request.path.petId. | | Variável de contexto | \$1context.variableName ou \$1\$1context.variableName\$1 | O valor de uma [variável de contexto](http-api-logging-variables.md). Somente os caracteres especiais `.` e `_` são aceitos. | | Variável de estágio | \$1stageVariables.variableName ou \$1\$1stageVariables.variableName\$1 | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). | | Valor estático | string | Um valor constante. | **nota** Para usar mais de uma variável em uma expressão de seleção, inclua a variável entre colchetes. Por exemplo, `${request.path.name} ${request.path.id}`. ## Transformando respostas da API Você usa parâmetros de resposta para transformar a resposta HTTP de uma integração de backend antes de retornar a resposta aos clientes. Você pode modificar cabeçalhos ou o código de status de uma resposta antes que o API Gateway retorne a resposta aos clientes. Você configura os parâmetros de resposta para cada código de status que sua integração retorna. Os parâmetros de resposta são um mapa de chave-valor. A chave identifica a localização do parâmetro da solicitação a ser alterado e como alterá-lo. O valor especifica os novos dados para o parâmetro. A tabela a seguir mostra as chaves suportadas. | Tipo | Sintaxe | | --- | --- | | Cabeçalho | append\$1overwrite\$1remove:header.headername | | Código de status | overwrite:statuscode | A tabela a seguir mostra os valores suportados que você pode mapear para parâmetros. | Tipo | Sintaxe | Observações | | --- | --- | --- | | Valor de cabeçalho | \$1response.header.nome ou \$1\$1response.header.nome\$1 | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2". Alguns cabeçalhos são reservados. Para saber mais, consulte [Cabeçalhos reservados](#http-api-mapping-reserved-headers). | | Corpo da resposta | \$1response.body.name ou \$1\$1response.body.name\$1 | Uma expressão de caminho JSON. Descidas recursivas (\$1response.body..name) e expressões de filtro (?(expression)) não são compatíveis. Quando você especifica um caminho JSON, o API Gateway trunca o corpo da resposta a 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique `$response.body`. | | Variável de contexto | \$1context.variableName ou \$1\$1context.variableName\$1 | O valor de uma [variável de contexto](http-api-logging-variables.md) compatível. | | Variável de estágio | \$1stageVariables.variableName ou \$1\$1stageVariables.variableName\$1 | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). | | Valor estático | string | Um valor constante. | **nota** Para usar mais de uma variável em uma expressão de seleção, inclua a variável entre colchetes. Por exemplo, `${request.path.name} ${request.path.id}`. ## Cabeçalhos reservados Os seguintes cabeçalhos são reservados. Não é possível configurar mapeamentos de solicitação ou resposta para esses cabeçalhos. + access-control-\$1 + apigw-\$1 + Autorização + Conexão + Content-Encoding + Content-Length + Content-Location + Encaminhado + Keep-alive + Origem + Proxy-Authenticate + Proxy-Authorization + TE + Trailers + Transfer-Encoding + Upgrade + x-amz-\$1 + x-amzn-\$1 + X-Forwarded-For + X-Forwarded-Host + X-Forwarded-Proto + Via ## Exemplos Os exemplos da AWS CLI a seguir configuram mapeamentos de dados. Para ver modelos de exemplo do CloudFormation, consulte o [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates). ### Adicionar um cabeçalho a uma solicitação de API O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir cria um cabeçalho chamado `header1` para uma solicitação de API antes que ela atinja sua integração de backend. O API Gateway preenche o cabeçalho com o ID da solicitação. ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --request-parameters '{ "append:header.header1": "$context.requestId" }' ``` ### Renomear um cabeçalho de solicitação O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo renomeia um cabeçalho de solicitação de `header1` para `header2`: ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --request-parameters '{ "append:header.header2": "$request.header.header1", "remove:header.header1": "''"}' ``` ### Alterar a resposta de uma integração O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir configura parâmetros de resposta para uma integração. Quando as integrações retornam um código de status 500, o API Gateway altera o código de status para 403 e adiciona `header1`1 à resposta. Quando a integração retorna um código de status 404, o API Gateway adiciona um `error` cabeçalho à resposta. ``` aws apigatewayv2 create-integration \ --api-id abcdef123 \ --integration-type HTTP_PROXY \ --payload-format-version 1.0 \ --integration-uri 'https://api.example.com' \ --integration-method ANY \ --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"} }' ``` ### Remover mapeamentos de parâmetros configurados O comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir remove os parâmetros de solicitação configurados anteriormente para `append:header.header1`. Ele também remove parâmetros de resposta previamente configurados para um código de status 200. ``` aws apigatewayv2 update-integration \ --api-id abcdef123 \ --integration-id hijk456 \ --request-parameters '{"append:header.header1" : ""}' \ --response-parameters '{"200" : {}}' ``` # Usar definições do OpenAPI para APIs HTTP no API Gateway É possível definir a API HTTP usando um arquivo de definição de OpenAPI 3.0. Depois, é possível importar a definição no API Gateway para criar uma API. Para saber mais sobre as extensões do API Gateway para OpenAPI, consulte [Extensões OpenAPI para o API Gateway](api-gateway-swagger-extensions.md). ## Importar uma API HTTP É possível criar uma API HTTP importando um arquivo de definição do OpenAPI 3.0. Para realizar a migração de uma API REST para uma API HTTP, é possível exportar sua API REST como um arquivo de definição do OpenAPI 3.0. Depois, importe a definição de API como uma API HTTP. Para saber mais sobre como exportar uma API REST, consulte [Exportar uma API REST do API Gateway](api-gateway-export-api.md). **nota** As APIs HTTP são compatíveis com as mesmas variáveis da AWS que as APIs REST. Para saber mais, consulte [Variáveis da AWS para importação de OpenAPI](import-api-aws-variables.md). ### Importar informações de validação À medida que você importa uma API, o API Gateway fornece três categorias de informações de validação. **Informações** Uma propriedade é válida de acordo com a especificação do OpenAPI, mas essa propriedade não é compatível com APIs HTTP. Por exemplo, o snippet do OpenAPI 3.0 a seguir produz informações sobre importação porque APIs HTTP não são compatíveis com a validação de solicitação. O API Gateway ignora os campos `requestBody` e `schema`. ``` "paths": { "/": { "get": { "x-amazon-apigateway-integration": { "type": "AWS_PROXY", "httpMethod": "POST", "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld", "payloadFormatVersion": "1.0" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body" } } } } } } ... }, "components": { "schemas": { "Body": { "type": "object", "properties": { "key": { "type": "string" } } } ... } ... } ``` **Aviso** Uma propriedade ou estrutura é inválida de acordo com a especificação OpenAPI, mas não bloqueia a criação de API.çç É possível especificar se o API Gateway deve ignorar esses avisos e continuar criando a API ou parar de criar a API em avisos. O documento do OpenAPI 3.0 a seguir produz avisos na importação porque APIs HTTP são compatíveis apenas com integrações de proxy do Lambda e HTTP. ``` "x-amazon-apigateway-integration": { "type": "AWS", "httpMethod": "POST", "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld", "payloadFormatVersion": "1.0" } ``` **Erro** A especificação do OpenAPI é inválida ou malformada. O API Gateway não pode criar recursos a partir do documento malformado. Você precisa corrigir os erros e, em seguida, tentar novamente. A definição de API a seguir produz erros na importação porque as APIs HTTP são compatíveis apenas com a especificação do OpenAPI 3.0. ``` { "swagger": "2.0.0", "info": { "title": "My API", "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo", "version": "1.0" } ... } ``` Como outro exemplo, enquanto o OpenAPI permite que os usuários definam uma API com vários requisitos de segurança anexados a uma determinada operação, o API Gateway não oferece suporte a isso. Cada operação pode ter apenas uma autorização do IAM, um autorizador do Lambda ou um autorizador JWT. A tentativa de modelar vários requisitos de segurança resulta em um erro. ### Importar uma API usando a AWS CLI O comando [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) indicado abaixo importa o arquivo de definição `api-definition.json` do OpenAPI 3.0 como uma API HTTP: **Example** ``` aws apigatewayv2 import-api --body file://api-definition.json ``` **Example** É possível importar a definição demonstrativa do OpenAPI 3.0 a seguir para criar uma API HTTP. ``` { "openapi": "3.0.1", "info": { "title": "Example Pet Store", "description": "A Pet Store API.", "version": "1.0" }, "paths": { "/pets": { "get": { "operationId": "GET HTTP", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pets" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "GET", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets", "payloadFormatVersion": 1.0 } }, "post": { "operationId": "Create Pet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPet" } } }, "required": true }, "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPetResponse" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "POST", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets", "payloadFormatVersion": 1.0 } } }, "/pets/{petId}": { "get": { "operationId": "Get Pet", "parameters": [ { "name": "petId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "GET", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}", "payloadFormatVersion": 1.0 } } } }, "x-amazon-apigateway-cors": { "allowOrigins": [ "*" ], "allowMethods": [ "GET", "OPTIONS", "POST" ], "allowHeaders": [ "x-amzm-header", "x-apigateway-header", "x-api-key", "authorization", "x-amz-date", "content-type" ] }, "components": { "schemas": { "Pets": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } }, "Empty": { "type": "object" }, "NewPetResponse": { "type": "object", "properties": { "pet": { "$ref": "#/components/schemas/Pet" }, "message": { "type": "string" } } }, "Pet": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "number" } } }, "NewPet": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PetType" }, "price": { "type": "number" } } }, "PetType": { "type": "string", "enum": [ "dog", "cat", "fish", "bird", "gecko" ] } } } } ``` # Exportar APIs HTTP do API Gateway Depois de criar uma API HTTP, é possível exportar uma definição do OpenAPI 3.0 da API a partir do API Gateway. Você pode escolher um estágio para exportar ou exportar a configuração mais recente da API. Também é possível importar uma definição de API exportada para o API Gateway para a criação de outra API idêntica. Para saber mais sobre a importação de definições de API, consulte [Importar uma API HTTP](http-api-open-api.md#http-api-import). ## Exportar uma definição do OpenAPI 3.0 de um estágio usando a CLI da AWS O comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) a seguir exporta uma definição do OpenAPI de um estágio de API chamado `prod` para um arquivo YAML denominado `stage-definition.yaml`. O arquivo de definição exportado inclui [extensões do API Gateway](api-gateway-swagger-extensions.md) por padrão. ``` aws apigatewayv2 export-api \ --api-id api-id \ --output-type YAML \ --specification OAS30 \ --stage-name prod \ stage-definition.yaml ``` ## Exporte uma definição do OpenAPI 3.0 das alterações mais recentes da API usando a CLI da AWS O comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) a seguir exporta uma definição do OpenAPI de uma API HTTP para um arquivo JSON denominado `latest-api-definition.json`. Como o comando não especifica um estágio, o API Gateway exporta a configuração mais recente da API, quer ela tenha sido implantada em um estágio ou não. O arquivo de definição exportado não inclui [extensões do API Gateway](api-gateway-swagger-extensions.md). ``` aws apigatewayv2 export-api \ --api-id api-id \ --output-type JSON \ --specification OAS30 \ --no-include-extensions \ latest-api-definition.json ``` Para obter mais informações, consulte [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods) na *Referência de API do Amazon API Gateway versão 2*. ## Exportar uma definição do OpenAPI 3.0 usando o console do API Gateway O procedimento a seguir mostra como exportar uma definição do OpenAPI de uma API HTTP. **Como exportar uma definição do OpenAPI 3.0 usando o console do API Gateway** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione uma API HTTP. 1. No painel de navegação principal, em **Desenvolver**, escolha **Exportar**. 1. Selecione uma das seguintes opções para exportar a API: ![\[Opções de exportação para APIs HTTP.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/export-http-api.png) 1. Em **Origem**, selecione uma origem para a definição do OpenAPI 3.0. Você pode escolher um estágio para exportar ou exportar a configuração mais recente da API. 1. Ative a opção **Incluir extensões do API Gateway** para incluir [extensões do API Gateway](api-gateway-swagger-extensions.md). 1. Em **Formato de saída**, selecione um formato de saída. 1. Escolha **Baixar**.