# Desenvolver APIs REST no API Gateway No Amazon API Gateway, você cria uma API REST como uma coleção de entidades programáveis conhecida como [recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) do API Gateway. Por exemplo, você usa um recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) para representar uma API que pode conter uma coleção de entidades [Recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html). Cada entidade `Resource` pode ter um ou mais recursos [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). Um `Method` é uma solicitação recebida enviada pelo cliente e pode conter os seguintes parâmetros de solicitação: um parâmetro de caminho, um cabeçalho ou um parâmetro de string de consulta. Além disso, dependendo do método HTTP, a solicitação pode conter um corpo. O método define como o cliente acessa o `Resource` exposto. Para integrar o `Method` a um endpoint de back-end, também conhecido como endpoint de integração, crie um recurso [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Isso encaminha a solicitação recebida para um URI de endpoint de integração especificado. Se necessário, é possível transformar os parâmetros ou o corpo da solicitação para atender aos requisitos de backend, ou criar uma integração de proxy, na qual o API Gateway envia a solicitação inteira em um formato padronizado ao URI do endpoint de integração e, depois, envia diretamente a resposta ao cliente. Para as respostas, é possível criar um recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) para representar uma resposta recebida pelo cliente e criar um recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) para representar a resposta retornada pelo backend. Use uma resposta de integração para transformar os dados da resposta do backend antes de retornar os dados ao cliente ou transmitir a resposta do backend da forma em que se encontra para o cliente. ## Exemplo de recurso para uma API REST O diagrama a seguir mostra como o API Gateway implementa esse modelo de solicitação/resposta para uma integração de proxy HTTP e uma integração HTTP sem proxy para o recurso `GET /pets`. O cliente envia o cabeçalho `x-version:beta` ao API Gateway e o API Gateway envia o código de status `204` ao cliente. Na integração sem proxy, o API Gateway realiza transformações de dados para atender aos requisitos de backend, modificando a solicitação e a resposta da integração. Em uma integração sem proxy, é possível acessar o corpo na solicitação do método, mas ele é transformado na solicitação de integração. Quando o endpoint de integração retorna uma resposta com um corpo, você a acessa e a transforma na resposta de integração. Não é possível modificar o corpo na resposta do método. Na integração de proxy, o endpoint de integração modifica a solicitação e a resposta. O API Gateway não modifica a solicitação nem a resposta de integração e envia a solicitação recebida ao backend no estado em que se encontra. Independentemente do tipo de integração, o cliente enviou uma solicitação ao API Gateway, que a respondeu de forma síncrona. ------ #### [ Non-proxy integration ] ![\[Diagrama da integração sem proxy do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/develop-non-proxy.png) ------ #### [ Proxy integration ] ![\[Diagrama de integração com proxy do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/develop-proxy.png) ------ Os exemplos de logs de execução a seguir mostram o que o API Gateway registraria no exemplo anterior. Para garantir maior clareza, alguns valores e logs iniciais foram removidos: ------ #### [ Non-proxy integration ] ``` Wed Feb 12 23:56:44 UTC 2025 : Starting execution for request: abcd-1234-5678 Wed Feb 12 23:56:44 UTC 2025 : HTTP Method: GET, Resource Path: /pets Wed Feb 12 23:56:44 UTC 2025 : Method request path: {} Wed Feb 12 23:56:44 UTC 2025 : Method request query string: {} Wed Feb 12 23:56:44 UTC 2025 : Method request headers: {x-version=beta} Wed Feb 12 23:56:44 UTC 2025 : Method request body before transformations: Wed Feb 12 23:56:44 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:56:44 UTC 2025 : Endpoint request headers: {app-version=beta} Wed Feb 12 23:56:44 UTC 2025 : Endpoint request body after transformations: Wed Feb 12 23:56:44 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:56:45 UTC 2025 : Received response. Status: 200, Integration latency: 123 ms Wed Feb 12 23:56:45 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:56:45 GMT} Wed Feb 12 23:56:45 UTC 2025 : Endpoint response body before transformations: Wed Feb 12 23:56:45 UTC 2025 : Method response body after transformations: (null) Wed Feb 12 23:56:45 UTC 2025 : Method response headers: {X-Amzn-Trace-Id=Root=1-abcd-12345} Wed Feb 12 23:56:45 UTC 2025 : Successfully completed execution Wed Feb 12 23:56:45 UTC 2025 : Method completed with status: 204 ``` ------ #### [ Proxy integration ] ``` Wed Feb 12 23:59:42 UTC 2025 : Starting execution for request: abcd-1234-5678 Wed Feb 12 23:59:42 UTC 2025 : HTTP Method: GET, Resource Path: /pets Wed Feb 12 23:59:42 UTC 2025 : Method request path: {} Wed Feb 12 23:59:42 UTC 2025 : Method request query string: {} Wed Feb 12 23:59:42 UTC 2025 : Method request headers: {x-version=beta} Wed Feb 12 23:59:42 UTC 2025 : Method request body before transformations: Wed Feb 12 23:59:42 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:59:42 UTC 2025 : Endpoint request headers: { x-version=beta} Wed Feb 12 23:59:42 UTC 2025 : Endpoint request body after transformations: Wed Feb 12 23:59:42 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:59:43 UTC 2025 : Received response. Status: 204, Integration latency: 123 ms Wed Feb 12 23:59:43 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} Wed Feb 12 23:59:43 UTC 2025 : Endpoint response body before transformations: Wed Feb 12 23:59:43 UTC 2025 : Method response body after transformations: Wed Feb 12 23:59:43 UTC 2025 : Method response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} Wed Feb 12 23:59:43 UTC 2025 : Successfully completed execution Wed Feb 12 23:59:43 UTC 2025 : Method completed with status: 204 ``` ------ Para importar uma API semelhante e testá-la no Console de gerenciamento da AWS, consulte o [exemplo de API](api-gateway-create-api-from-example.md). ## Recursos adicionais da API REST para desenvolvimento O API Gateway é compatível com recursos adicionais para o desenvolvimento da API REST. Por exemplo, para ajudar os clientes a compreenderem sua API, você pode fornecer a documentação da API. Para fazer isso, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) para uma entidade de API compatível. Para controlar como os clientes chamam uma API, use [permissões do IAM](permissions.md), um [autorizador de Lambda](apigateway-use-lambda-authorizer.md) ou um [grupo de usuários Amazon Cognito](apigateway-integrate-with-cognito.md). Para medir o uso da sua API, configure [planos de uso](api-gateway-api-usage-plans.md) para limitar as solicitações de API. Você pode habilitá-los ao criar ou atualizar a API. O diagrama a seguir mostra os recursos disponíveis para o desenvolvimento da API REST e onde, no modelo de solicitação/resposta, esses recursos são configurados. ![\[Diagrama dos recursos do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/develop-features.png) Para conferir uma introdução sobre como criar uma API, consulte [Tutorial: Crie uma API REST com uma integração de proxy do Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md). Para obter mais informações sobre os recursos do API Gateway que você pode usar ao desenvolver uma API REST, consulte os tópicos a seguir. Esses tópicos contêm informações conceituais e procedimentos que você pode executar usando o console do API Gateway, a API REST do API Gateway, a AWS CLI ou um dos AWS SDKs. **Topics** + [Exemplo de recurso para uma API REST](#rest-api-develop-example) + [Recursos adicionais da API REST para desenvolvimento](#rest-api-develop-details) + [Tipos de endpoint da API para APIs REST no API Gateway](api-gateway-api-endpoint-types.md) + [Políticas de segurança para APIs REST no API Gateway](apigateway-security-policies.md) + [Tipos de endereço IP para APIs REST no API Gateway](api-gateway-ip-address-type.md) + [Métodos para APIs REST no API Gateway](how-to-method-settings.md) + [Controlar e gerenciar o acesso a APIs REST no API Gateway](apigateway-control-access-to-api.md) + [Integrações para APIs REST no API Gateway](how-to-integration-settings.md) + [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md) + [Transformações de dados para APIs REST no API Gateway](rest-api-data-transformations.md) + [Respostas do gateway para APIs REST no API Gateway](api-gateway-gatewayResponse-definition.md) + [CORS para APIs REST no API Gateway](how-to-cors.md) + [Tipos de mídia binários para APIs REST no API Gateway](api-gateway-payload-encodings.md) + [Invocar APIs REST no API Gateway](how-to-call-api.md) + [Desenvolver APIs REST usando OpenAPI no API Gateway](api-gateway-import-api.md) # Tipos de endpoint da API para APIs REST no API Gateway Um tipo de *[endpoint da API](api-gateway-basic-concept.md#apigateway-definition-api-endpoints)* refere-se ao nome do host da API. O tipo de endpoint da API pode ser *edge-optimized*, *regional* ou *privado*, dependendo de onde a maior parte do seu tráfego de API se origina. ## Endpoint de API otimizado para bordas Um *[endpoint de API otimizado para borda](api-gateway-basic-concept.md#apigateway-definition-edge-optimized-api-endpoint)* geralmente direciona as solicitações para o ponto de presença (POP) do CloudFront mais próximo, o que pode ajudar nos casos em que os clientes estão distribuídos geograficamente. Esse é o tipo de endpoint padrão para APIs REST do API Gateway. As APIs otimizadas para fronteiras mantêm em letra maiúscula os nomes dos [cabeçalhos HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (por exemplo, `Cookie`). O CloudFront classifica os cookies HTTP em ordem natural por nome de cookie antes de encaminhar a solicitação para sua origem. Para obter mais informações sobre a maneira como o CloudFront processa os cookies, consulte [Armazenamento em cache de conteúdo com base em cookies](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html). Qualquer nome de domínio personalizado que for usado para uma API otimizada para a borda se aplicará a todas as regiões. ## Endpoints de API regionais Um *[endpoint de API regional](api-gateway-basic-concept.md#apigateway-definition-regional-api-endpoint)* é destinado a clientes na mesma região. Quando um cliente em execução em uma instância do EC2 chama uma API na mesma região ou quando uma API é destinada a atender a um pequeno número de clientes com alta demanda, uma API regional reduz a sobrecarga da conexão. Para uma API regional, o nome de domínio personalizado que você usa é específico da região em que a API é implantada. Se você implantar uma API regional implantada em várias regiões, o nome de domínio personalizado poderá ser o mesmo em todas as regiões. Você pode usar domínios personalizados em conjunto com o Amazon Route 53 para executar tarefas como [roteamento baseado em latência](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-latency). Para obter mais informações, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md) e [Configurar um nome de domínio personalizado otimizado para borda no API Gateway](how-to-edge-optimized-custom-domain-name.md). Os endpoints de API regionais transmitem todos os nomes de cabeçalho no estado em que se encontram. **nota** Nos casos em que os clientes da API são geograficamente dispersos, ainda poderá fazer sentido usar um endpoint de API regional junto à sua própria distribuição do Amazon CloudFront para garantir que o API Gateway não associe a API às distribuições do CloudFront controladas pelo serviço. Para obter mais informações sobre esse caso de uso, consulte [Como posso configurar o API Gateway com minha própria distribuição do CloudFront?](https://repost.aws/knowledge-center/api-gateway-cloudfront-distribution). ## Endpoints privados de API Um *[endpoint privado da API](api-gateway-basic-concept.md#apigateway-definition-private-api-endpoint)* é um endpoint de API que somente pode ser acessado de sua Amazon Virtual Private Cloud (VPC) usando um VPC endpoint de interface, uma endpoint network interface (ENI – Interface de rede de endpoint) que você cria em sua VPC. Para obter mais informações, consulte [APIs REST privadas no API Gateway](apigateway-private-apis.md). Os endpoints privados de API transmitem todos os nomes de cabeçalho no estado em que se encontram. # Alterar um tipo de endpoint de API pública ou privada no API Gateway Alterar o tipo de endpoint da API requer que você atualize a configuração da API. É possível alterar um tipo de API existente usando o console do API Gateway, a AWS CLI ou um SDK da AWS para API Gateway. O tipo de endpoint não poderá ser alterado novamente até que a alteração atual seja concluída, mas a API estará disponível. Há suporte para as seguintes alterações nos tipos de endpoints: + De “otimizada para borda” para “regional” ou “privada” + De “regional” para “otimizada para borda” ou “privada” + De “privada” para “regional” Não é possível alterar uma API privada para uma API otimizada para fronteiras. Se você está alterando uma API pública do tipo “otimizada para borda” para “regional” ou vice-versa, observe que uma API otimizada para borda pode ter comportamentos diferentes em comparação com uma API regional. Por exemplo, uma API otimizada para fronteiras remove o cabeçalho `Content-MD5`. Qualquer valor de hash MD5 transmitido para o backend pode ser expresso em um parâmetro de string de solicitação ou uma propriedade de corpo. No entanto, a API regional transmite esse cabeçalho, embora ela possa remapear o nome do cabeçalho para outro nome. A compreensão das diferenças ajuda você a decidir como atualizar de uma API otimizada para borda para uma regional ou de uma API regional para uma otimizada para borda. **Topics** + [Usar o console do API Gateway para alterar um tipo de endpoint de API](#migrate-api-using-console) + [Usar a AWS CLI para alterar um tipo de endpoint de API](#migrate-api-using-aws-cli) ## Usar o console do API Gateway para alterar um tipo de endpoint de API Para alterar o tipo de endpoint de API da sua API, realize um dos seguintes conjuntos de etapas: **Como converter um endpoint público de regional em otimizado para borda e vice-versa** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Escolha **Configurações da API**. 1. Na seção **Detalhes da API**, escolha **Editar**. 1. **Em **Tipo de endpoint da API**, selecione Otimizado para borda** ou **Regional**. 1. Escolha **Salvar alterações**. 1. Reimplante sua API para que as alterações sejam aplicadas. **Converter um endpoint privado em um endpoint regional** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Edite a política de recursos da sua API para remover qualquer menção de VPCs ou endpoints da VPC, a fim de que as chamadas de API de fora ou de dentro da sua VPC sejam bem-sucedidas. 1. Escolha **Configurações da API**. 1. Na seção **Detalhes da API**, escolha **Editar**. 1. Em **Tipo de endpoint da API**, escolha **Regional**. 1. Escolha **Salvar alterações**. 1. Remova a política de recursos da sua API. 1. Reimplante sua API para que as alterações sejam aplicadas. Como você está migrando o tipo de endpoint de privado para Regional, o API Gateway altera o tipo de endereço IP para IPv4. Para obter mais informações, consulte [Tipos de endereço IP para APIs REST no API Gateway](api-gateway-ip-address-type.md). **Converter um endpoint regional em um endpoint privado** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Crie uma política de recursos que conceda acesso a VPC ou ao endpoint da VPC. Para obter mais informações, consulte [Etapa 3: Configurar uma política de recursos para uma API privada](apigateway-private-api-create.md#apigateway-private-api-set-up-resource-policy). 1. Escolha **Configurações da API**. 1. Na seção **Detalhes da API**, escolha **Editar**. 1. Em **Tipo de endpoint de API**, escolha **Privado**. 1. (Opcional) Para **IDs de endpoint da VPC**, selecione as IDs de endpoint da VPC que você deseja associar à API privada. 1. Escolha **Salvar alterações**. 1. Reimplante sua API para que as alterações sejam aplicadas. Como você está migrando o tipo de endpoint de Regional para privado, o API Gateway altera o tipo de endereço IP para pilha dupla. Para obter mais informações, consulte [Tipos de endereço IP para APIs REST no API Gateway](api-gateway-ip-address-type.md). ## Usar a AWS CLI para alterar um tipo de endpoint de API O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo atualiza uma API otimizada para borda para uma API regional: ``` aws apigateway update-rest-api \ --rest-api-id a1b2c3 \ --patch-operations op=replace,path=/endpointConfiguration/types/EDGE,value=REGIONAL ``` A resposta bem-sucedida tem um código de status de `200 OK` e uma carga semelhante ao seguinte: ``` { "createdDate": "2017-10-16T04:09:31Z", "description": "Your first API with Amazon API Gateway. This is a sample API that integrates via HTTP with our demo Pet Store endpoints", "endpointConfiguration": { "types": "REGIONAL" }, "id": "a1b2c3", "name": "PetStore imported as edge-optimized" } ``` O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo atualiza uma API regional para uma API otimizada para borda: ``` aws apigateway update-rest-api \ --rest-api-id a1b2c3 \ --patch-operations op=replace,path=/endpointConfiguration/types/REGIONAL,value=EDGE ``` Como [put-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-rest-api.html) é usado para atualizar as definições de API, não é aplicável à atualização de um tipo de endpoint de API. # Políticas de segurança para APIs REST no API Gateway Uma *política de segurança* é uma combinação predefinida da versão mínima do TLS e dos pacotes de criptografia oferecida pelo Amazon API Gateway. Quando seus clientes estabelecem um handshake do TLS para a API ou o nome do domínio personalizado, a política de segurança aplica a versão do TLS e o pacote de criptografia aceitos pelo API Gateway. As políticas de segurança protegem suas APIs e nomes de domínio personalizados contra problemas de segurança de rede, como violação e espionagem entre um cliente e o servidor. O API Gateway aceita políticas de segurança legadas e políticas de segurança aprimoradas. `TLS_1_0` e `TLS_1_2` são políticas de segurança legadas. Use essas políticas de segurança para compatibilidade com versões anteriores. Qualquer política que comece com `SecurityPolicy_` é uma política de segurança aprimorada. Use essas políticas para workloads reguladas, governança avançada ou para usar criptografia pós-quântica. Ao usar uma política de segurança aprimorada, você também deve definir o modo de acesso ao endpoint para governança adicional. Para obter mais informações, consulte [Modo de acesso ao endpoint](#apigateway-security-policies-endpoint-access-mode). ## Como o API Gateway aplica políticas de segurança O exemplo a seguir mostra como o API Gateway aplica políticas de segurança utilizando a política `SecurityPolicy_TLS13_1_3_2025_09` como exemplo. A política de segurança `SecurityPolicy_TLS13_1_3_2025_09` aceita tráfego TLS 1.3 e rejeita tráfego TLS 1.2 e TLS 1.0. Para o tráfego TLS 1.3, a política de segurança aceita os seguintes pacotes de criptografia: + `TLS_AES_128_GCM_SHA256` + `TLS_AES_256_GCM_SHA384` + `TLS_CHACHA20_POLY1305_SHA256` O API Gateway não aceita nenhum outro pacote de criptografia. Por exemplo, a política de segurança rejeitaria qualquer tráfego TLS 1.3 que utilize o pacote de criptografia `AES128-SHA`. Para acessar mais informações sobre as versões de TLS e criptografias aceitas, consulte [Políticas de segurança aceitas](apigateway-security-policies-list.md). Para monitorar quais protocolos TLS e criptografias os clientes usaram para acessar seu API Gateway, você pode usar as variáveis de contexto `$context.tlsVersion` e `$context.cipherSuite` em seus logs de acesso. Para obter mais informações, consulte [Monitorar APIs REST no API Gateway](rest-api-monitor.md). ## Modo de acesso ao endpoint O modo de acesso ao endpoint é um parâmetro adicional que você deve especificar para qualquer API REST ou nome de domínio personalizado que use uma política de segurança aprimorada começando com `SecurityPolicy_`. Você faz isso ao criar seu recurso ou ao alterar a política de segurança de uma política legada para uma política aprimorada. Quando o modo de acesso ao endpoint é definido como `STRICT`, todas as solicitações para sua API REST ou nome de domínio personalizado devem passar pelas seguintes verificações: + A solicitação deve ser originada do mesmo tipo de endpoint do API Gateway que seu recurso. Pode ser de um endpoint regional, otimizado para borda ou privado. + Se você usar um endpoint regional ou privado, o API Gateway usará a correspondência de host SNI. Se você utilizar um endpoint otimizado para borda, o API Gateway estará em conformidade com a proteção contra “domain fronting” do CloudFront. Para acessar mais informações, consulte [Domain fronting](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions). Se alguma dessas condições não for atendida, o API Gateway rejeitará a solicitação. É recomendável utilizar o modo de acesso ao endpoint `STRICT` quando possível. Para migrar uma API ou nome de domínio existente para usar o modo de acesso ao endpoint restrito, primeiro atualize sua política de segurança para uma política de segurança aprimorada e mantenha o modo de acesso ao endpoint definido como `BASIC`. Depois de validar seus logs de tráfego e acesso, defina o modo de acesso ao endpoint como `STRICT`. Quando você migra o modo de acesso ao endpoint de `STRICT` para`BASIC`, ele fica indisponível por cerca de 15 minutos à medida que as alterações se propagam. Você não deve definir o modo de acesso ao endpoint como `STRICT` para determinadas arquiteturas de aplicações e, em vez disso, definir o modo de acesso ao endpoint como `BASIC`. A tabela a seguir mostra algumas arquiteturas de aplicações e uma recomendação para que sua API REST ou nome de domínio personalizado possa usar o modo de acesso ao endpoint `STRICT`. | Arquitetura | Migração sugerida | | --- | --- | | Usar um endpoint da VPC para acessar um nome de domínio personalizado público. | Essa arquitetura utiliza tráfego do tipo entre endpoints. Recomendamos migrar para [Nomes de domínio personalizados para APIs privadas no API Gateway](apigateway-private-custom-domains.md). | | Usar qualquer método para invocar uma API privada que não utilize um nome de domínio personalizado ou nomes DNS privados. | Essa arquitetura cria uma incompatibilidade entre o cabeçalho d host e o SNI utilizado no handshake TLS e não atende às restrições de “domain fronting” do CloudFront. Recomendamos que você migre sua VPC para utilizar o DNS privado. | | Utilizar a fragmentação de domínio para distribuir conteúdo em vários domínios ou subdomínios. | Essa arquitetura cria uma incompatibilidade entre o cabeçalho d host e o SNI utilizado no handshake TLS e não atende às restrições de “domain fronting” do CloudFront. É recomendável que você utilize `HTTP/2` e migre para longe desse antipadrão. | Veja a seguir algumas considerações sobre o uso do modo de acesso ao endpoint: + Se o modo de acesso ao endpoint de uma API ou nome de domínio for `STRICT`, você não poderá alterar o tipo de endpoint. Para alterar o tipo de endpoint, primeiro altere o modo de acesso ao endpoint para `BASIC`. + Depois de alterar o modo de acesso ao endpoint de `BASIC` para `STRICT`, há um atraso de 15 minutos para o API Gateway aplicar o modo de acesso restrito ao endpoint. + Ao alterar uma política de segurança de uma política que começa com `SecurityPolicy_` para uma política legada, você deve cancelar a definição do modo de acesso ao endpoint como `""`. ## Considerações Veja a seguir algumas considerações sobre políticas de segurança para APIs REST no API Gateway: + Você pode importar a política de segurança em um arquivo de definição da OpenAPI. Para obter mais informações, consulte [x-amazon-apigateway-endpoint-access-modex-amazon-apigateway-security-policy](openapi-extensions-security-policy.md). + Sua API pode ser associada a um nome de domínio personalizado com uma política de segurança diferente da política da sua API. Quando você invoca esse nome de domínio personalizado, o API Gateway utiliza a política de segurança da API para negociar o handshake TLS. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar sua API. + Se você alterar sua política de segurança, a atualização levará cerca de 15 minutos para ser concluída. É possível monitorar o `apiStatus` de sua API. No decorrer da atualização da sua API, o `apiStatus` será `UPDATING` e, quando o processo for concluído, será `AVAILABLE`. Quando o status da sua API é `UPDATING`, você ainda pode invocá-la. + O API Gateway aceita políticas de segurança em todas as APIs. No entanto, você só pode escolher uma política de segurança para as APIs REST. O API Gateway comporta apenas a política de segurança `TLS_1_2` para APIs HTTP ou de WebSocket. + Você não pode atualizar a política de segurança de uma API de `TLS_1_0` para `TLS_1_2`. + Algumas políticas de segurança comportam os pacotes de criptografia ECDSA e RSA. Se você usar esse tipo de política com um nome de domínio personalizado, os pacotes de criptografia corresponderão ao tipo de chave de certificado fornecido pelo cliente, RSA ou ECDSA. Se você usar esse tipo de política com uma API REST, os conjuntos de criptografia corresponderão aos pacotes aceitos com os tipos de certificados RSA. # Políticas de segurança aceitas As tabelas a seguir descrevem as [políticas de segurança](apigateway-security-policies.md) que podem ser especificadas para cada tipo de endpoint de API REST e tipo de nome de domínio personalizado. Essas políticas permitem que você controle as conexões de entrada. O API Gateway aceita somente o TLS 1.2 na saída. Você pode atualizar a política de segurança da sua API ou nome de domínio personalizado a qualquer momento. As políticas que contêm o `FIPS` no título são compatíveis com o Federal Information Processing Standard (FIPS), que é um padrão do governo dos EUA e do Canadá que especifica os requisitos de segurança para módulos criptográficos que protegem informações sensíveis. Para saber mais, consulte [Federal Information Processing Standard (FIPS) 140](https://aws.amazon.com/compliance/fips/) na página *AWS Cloud Security Compliance*. Todas as políticas do FIPS utilizam o módulo criptográfico AWS-LC validado pelo FIPS. Para saber mais, consulte a página [AWS-LC Cryptographic Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4631) no site *NIST Cryptographic Module Validation Program*. As políticas que contêm `PQ` no título utilizam [criptografia pós-quântica (PQC)](https://aws.amazon.com/security/post-quantum-cryptography/) para implementar algoritmos híbridos de troca de chaves para TLS a fim de garantir a confidencialidade do tráfego contra futuras ameaças de computação quântica. As políticas que contêm `PFS` no título utilizam o [Perfect Forward Secrecy (PFS)](https://en.wikipedia.org/wiki/Forward_secrecy) para garantir que as chaves da sessão não sejam comprometidas. As políticas que contêm `FIPS` e `PQ` em seus títulos comportam esses dois recursos. ## Políticas de segurança padrão Quando você cria uma API REST ou domínio personalizado, o recurso recebe uma política de segurança padrão. A tabela a seguir mostra a política de segurança padrão para esses recursos. | **Recurso** | **Nome da política de segurança padrão** | | --- | --- | | APIs regionais | TLS\$11\$10 | | APIs otimizadas para bordas | TLS\$11\$10 | | APIs privadas | TLS\$11\$12 | | Domínios regionais | TLS\$11\$12 | | Domínio otimizado para borda | TLS\$11\$12 | | Domínio privado | TLS\$11\$12 | ## Políticas de segurança aceitas para APIs regionais e privadas e nomes de domínio personalizados A tabela a seguir descreve as políticas de segurança que podem ser especificadas para nomes de domínio personalizados e APIs privadas e regionais. | **Política de segurança** | **Versões aceitas do TLS** | **Criptografias compatíveis** | | --- | --- | --- | | SecurityPolicy\$1TLS13\$11\$13\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS13\$11\$13\$1FIPS\$12025\$109 | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS13\$11\$12\$1PFS\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS13\$11\$12\$1PQ\$12025\$109 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$12 | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | ## Políticas de segurança aceitas para APIs otimizadas para borda e nomes de domínio personalizados A tabela a seguir descreve as políticas de segurança que podem ser especificadas para APIs e nomes de domínio personalizados otimizados para borda. | **Nome da política de segurança** | **Versões aceitas do TLS** | **Criptografias compatíveis** | | --- | --- | --- | | SecurityPolicy\$1TLS13\$12025\$1EDGE | TLS1.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS12\$1PFS\$12025\$1EDGE | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1TLS12\$12018\$1EDGE | TLS1.3 TLS1.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$10 | TLS1.3 TLS1.2 TLS1.1 TLS1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-security-policies-list.html) | ## Nomes das criptografias OpenSSL e RFC OpenSSL e IETF RFC 5246 usam nomes diferentes para as mesmas cifras. A tabela a seguir mapeia o nome do OpenSSL para o nome do RFC para cada criptograma. Para ter mais informações, consulte [ciphers](https://docs.openssl.org/1.1.1/man1/ciphers/) na documentação do OpenSSL. | **Nome da criptografia OpenSSL** | **Nome da criptografia RFC** | | --- | --- | | TLS\$1AES\$1128\$1GCM\$1SHA256 | TLS\$1AES\$1128\$1GCM\$1SHA256 | | TLS\$1AES\$1256\$1GCM\$1SHA384 | TLS\$1AES\$1256\$1GCM\$1SHA384 | | TLS\$1CHACHA20\$1POLY1305\$1SHA256 | TLS\$1CHACHA20\$1POLY1305\$1SHA256 | | ECDHE-RSA-AES128-GCM-SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 | | ECDHE-RSA-AES128-SHA256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 | | ECDHE-RSA-AES128-SHA | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | | ECDHE-RSA-AES256-GCM-SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | | ECDHE-RSA-AES256-SHA384 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | | ECDHE-RSA-AES256-SHA | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | | AES128-GCM-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 | | AES256-GCM-SHA384 | TLS\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 | | AES128-SHA256 | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 | | AES256-SHA | TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | | AES128-SHA | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | | DES-CBC3-SHA | TLS\$1RSA\$1WITH\$13DES\$1EDE\$1CBC\$1SHA | # Como alterar uma política de segurança É possível alterar a política de segurança para sua API. Se você está enviando tráfego para as suas APIs utilizando o seu nome de domínio personalizado, a API e o nome de domínio personalizado não precisarão ter a mesma política de segurança. Quando você invoca esse nome de domínio personalizado, o API Gateway utiliza a política de segurança da API para negociar o handshake TLS. No entanto, para manter a consistência, é recomendável usar a mesma política de segurança para o seu nome de domínio personalizado e a API. Se você alterar sua política de segurança, a atualização levará cerca de 15 minutos para ser concluída. É possível monitorar o `apiStatus` de sua API. No decorrer da atualização da sua API, o `apiStatus` será `UPDATING` e, quando o processo for concluído, será `AVAILABLE`. Durante a atualização da sua API, você ainda pode invocá-la. ------ #### [ Console de gerenciamento da AWS ] **Como alterar a política de segurança de uma API** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Selecione **Configurações da API** e, depois, escolha **Editar**. 1. Em **Política de segurança**, selecione uma nova política que comece com `SecurityPolicy_`. 1. Em **Modo de acesso ao endpoint**, escolha **Restrito**. 1. Escolha **Salvar alterações**. Implante a API novamente para que as alterações entrem em vigor. Como você alterou o modo de acesso ao endpoint para restrito, levará cerca de 15 minutos para que as alterações se propaguem totalmente. ------ #### [ AWS CLI ] O seguinte comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) atualiza uma API para utilizar a política de segurança `SecurityPolicy_TLS13_1_3_2025_09`: ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations '[ { "op": "replace", "path": "/securityPolicy", "value": "SecurityPolicy_TLS13_1_3_2025_09" }, { "op": "replace", "path": "/endpointAccessMode", "value": "STRICT" } ]' ``` A saída será exibida da seguinte forma: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a new security policy", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09", "endpointAccessMode": "STRICT" "rootResourceId": "efg456" } ``` O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) a seguir atualiza uma API que estava utilizando uma política de segurança aprimorada para utilizar `TLS_1_0`: ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations '[ { "op": "replace", "path": "/securityPolicy", "value": "TLS_1_0" }, { "op": "replace", "path": "/endpointAccessMode", "value": "" } ]' ``` A saída será exibida da seguinte forma: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a new security policy", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "securityPolicy": "TLS_1_0", "rootResourceId": "efg456" } ``` ------ # Tipos de endereço IP para APIs REST 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). Para restringir sua API somente ao tráfego IPv6, você pode criar uma política de recursos e restringir os endereços IP de origem somente a intervalos IPv6. É possível alterar o tipo de endereço IP atualizando a configuração da API. Essa alteração entrará em vigor imediatamente e você não precisará reimplantar sua API. Para obter mais informações, consulte [Exemplo: negar tráfego da API com base no intervalo ou endereço IP de origem](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example). ## 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 todas as APIs regionais e otimizadas para borda é IPv4. + As APIs privadas só podem ter um tipo de endereço IP de pilha dupla. + 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. + Se você migrar o tipo de endpoint de uma API de regional ou otimizado para borda para privado, o API Gateway alterará o tipo de endereço IP para pilha dupla. Para obter mais informações, consulte [Alterar um tipo de endpoint de API pública ou privada no API Gateway](apigateway-api-migration.md). + Se você migrar o tipo de endpoint de uma API de privado para regional, deverá definir o tipo de endereço IP como pilha dupla. Após a conclusão da migração do endpoint, você pode alterar o tipo de endereço IP para IPv4. Para obter mais informações, consulte [Alterar um tipo de endpoint de API pública ou privada no API Gateway](apigateway-api-migration.md). + 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. + Não é possível usar um arquivo de definição externo para configurar o tipo de endereço IP da sua API. # Alterar o tipo de endereço IP de uma API REST É 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. Antes de alterar o tipo de endereço IP, confirme se todas as políticas que controlam o acesso às suas APIs foram atualizadas para considerar as chamadas IPv6. ------ #### [ Console de gerenciamento da AWS ] **Como alterar o tipo de endereço IP de uma API REST** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Selecione **Configurações da API** e, depois, escolha **Editar**. 1. Em Tipo de endereço IP, escolha **IPv4** ou **Pilha dupla**. 1. Escolha **Salvar alterações**. A alteração na configuração da sua API entrará em vigor imediatamente. ------ #### [ AWS CLI ] O seguinte comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) atualiza uma API para ter um tipo de endereço IP de pilha dupla: ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'" ``` A saída será exibida da seguinte forma: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a dualstack IP address type", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "rootResourceId": "efg456" } ``` ------ # Métodos para APIs REST no API Gateway No API Gateway, um método de API incorpora uma [solicitação de método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) e uma [resposta de método](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). Você pode configurar um método de API para definir o que um cliente deve fazer para enviar uma solicitação para acessar o serviço no backend e definir as respostas que o cliente recebe em troca. Para entrada, você pode escolher os parâmetros de solicitação de método ou uma carga útil aplicável para o cliente fornecer os dados obrigatórios ou opcionais em tempo de execução. Para a saída, você determina o código de status de resposta de método, os cabeçalhos e o corpo aplicável como destinos para mapear os dados de resposta de backend, antes de serem retornados para o cliente. Para ajudar o desenvolvedor do cliente a entender os comportamentos e os formatos de entrada e saída de sua API, você pode [documentar sua API](api-gateway-documenting-api.md) e [fornecer mensagens de erro adequadas](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) para [solicitações inválidas](api-gateway-method-request-validation.md). Solicitação de método de API é uma solicitação HTTP. Para configurar a solicitação de método, configure um método HTTP (ou verbo), o caminho para um [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API, cabeçalhos e parâmetros de string de consulta aplicáveis. Você também configura uma carga útil quando o método HTTP é `POST`, `PUT` ou `PATCH`. Por exemplo, para recuperar um animal de estimação usando a [API de exemplo PetStore](api-gateway-create-api-from-example.md), defina a solicitação de método de API de `GET /pets/{petId}`, em que `{petId}` é um parâmetro de caminho que pode obter um número em tempo de execução. ``` GET /pets/1 Host: apigateway.us-east-1.amazonaws.com ... ``` Se o cliente especificar um caminho incorreto, por exemplo, `/pet/1` ou `/pets/one` em vez de `/pets/1`, será lançada uma exceção. Uma resposta de método de API é uma resposta HTTP com um código de status determinado. Para uma integração não proxy, você deve configurar respostas de método para especificar os destinos obrigatórios ou opcionais dos mapeamentos. Eles transformam os cabeçalhos de resposta de integração ou o corpo para os cabeçalhos de resposta de método associado ou o corpo. O mapeamento pode ser tão simples quanto uma [transformação de identidade](https://en.wikipedia.org/wiki/Identity_transform) que transmite os cabeçalhos ou o corpo pela integração no estado em que se encontra. Por exemplo, a resposta de método `200` a seguir mostra um exemplo de passagem de uma resposta de integração bem-sucedida no estado em que se encontra. ``` 200 OK Content-Type: application/json ... { "id": "1", "type": "dog", "price": "$249.99" } ``` Em princípio, você pode definir uma resposta de método correspondente a uma resposta específica do backend. Normalmente, isso envolve qualquer resposta 2XX, 4XX e 5XX. No entanto, isso pode não ser prático, pois, muitas vezes, você pode não saber com antecedência todas as respostas que um backend pode retornar. Na prática, você pode designar uma resposta de método como padrão para lidar com respostas desconhecidas ou não mapeadas do backend. É uma boa prática designar a resposta 500 como padrão. Em qualquer caso, você deve configurar pelo menos uma resposta de método para integrações não proxy. Caso contrário, o API Gateway retorna uma resposta de erro 500 para o cliente, mesmo quando a solicitação for bem-sucedida no backend. Para oferecer suporte a um SDK fortemente tipado, como um Java SDK, para sua API, você deve definir o modelo de dados para entrada para a solicitação de método e definir o modelo de dados para a saída da resposta de método. ## Pré-requisitos Antes de configurar um método de API, verifique o seguinte: + Você deve ter o método disponível no API Gateway. Siga as instruções em [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md). + Se você deseja que o método se comunique com uma função do Lambda, você já deve ter criado as funções de invocação e execução do Lambda no IAM. Você também deve ter criado a função do Lambda com a qual seu método se comunicará no AWS Lambda. Para criar as funções, use as instruções em [Criar uma função do Lambda para integração não proxy do Lambda](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda) do [Escolher um tutorial de integração do AWS Lambda](getting-started-with-lambda-integration.md). + Se quiser que o método se comunique com uma integração HTTP ou de proxy HTTP, será necessário já ter criado a URL de endpoint HTTP com a qual o seu método se comunicará, além de ter acesso a ela. + Verifique se os certificados para os endpoints HTTP e de proxy HTTP têm suporte pelo API Gateway. Para obter mais detalhes, consulte [Autoridades de certificado compatíveis com o API Gateway para integrações HTTP e de proxy HTTP no API Gateway.](api-gateway-supported-certificate-authorities-for-http-endpoints.md). **Topics** + [Pré-requisitos](#method-setting-prerequisites) + [Configurar uma solicitação de método no API Gateway](api-gateway-method-settings-method-request.md) + [Configurar uma resposta de método no API Gateway](api-gateway-method-settings-method-response.md) + [Configurar um método usando o console do API Gateway](how-to-set-up-method-using-console.md) # Configurar uma solicitação de método no API Gateway A configuração de uma solicitação de método envolve as seguintes tarefas, depois de criar um recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html): 1. A criação de uma nova API ou a escolha de uma entidade [Recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API existente. 1. A criação de um recurso [Método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) da API que seja um verbo HTTP específico no `Resource` de API novo ou escolhido. Essa tarefa pode ser dividida ainda mais nas seguintes tarefas secundárias: + Adição de um método HTTP à solicitação de método + Configuração de parâmetros de solicitação + Definição de um modelo para o corpo de solicitação + Adoção de um esquema de autorização + Ativação da validação de solicitação Você pode executar essas tarefas usando os seguintes métodos: + [Console do API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console) + Comandos da AWS CLI ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) e [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)) + Funções do SDK da AWS (por exemplo, em Node.js, [createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) e [putMethod](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property)) + API REST do API Gateway ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) e [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)). **Topics** + [Configurar recursos da API](#setup-method-resources) + [Configurar um método HTTP](#setup-method-add-http-method) + [Configurar parâmetros da solicitação de método](#setup-method-request-parameters) + [Configurar um modelo de solicitação de método](#setup-method-request-model) + [Configurar a autorização de solicitação de método](#setup-method-request-authorization) + [Configurar a validação da solicitação de método](#setup-method-request-validation) ## Configurar recursos da API Em uma API do API Gateway, você expõe recursos endereçáveis como uma árvore de entidades de [Recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) da API, com o recurso raiz (`/`) na parte superior da hierarquia. O recurso raiz é relativo à URL base da API, que é composta do endpoint de API e um nome de etapa. No console do API Gateway esse URI base é referido como o **URI de invocação** e é exibido no editor de etapas da API depois que a API é implantada. O endpoint da API pode ser um nome de host padrão ou um nome de domínio personalizado. O nome de host padrão é do seguinte formato: ``` {api-id}.execute-api.{region}.amazonaws.com ``` Neste formato, o *\$1api-id\$1* representa o identificador de API que é gerado pelo API Gateway. A variável `{region}` representa a região da AWS (por exemplo, `us-east-1`) escolhida ao criar a API. Um nome de domínio personalizado é qualquer nome amigável em um domínio de internet válido. Por exemplo, se você tiver registrado um domínio da Internet de `example.com`, qualquer `*.example.com` é um nome de domínio personalizado válido. Para obter mais informações, consulte [criar um nome de domínio personalizado](how-to-custom-domains.md). Para a [API de exemplo PetStore](api-gateway-create-api-from-example.md), o recurso raiz (`/`) expõe a loja de animais de estimação. O recurso `/pets` representa a coleção de animais de estimação disponíveis na loja. O `/pets/{petId}` expõe um animação de estimação individual de um determinado identificador (`petId`). O parâmetro de caminho de `{petId}` faz parte dos parâmetros da solicitação. Para configurar um recurso de API, você escolhe um recurso existente como seu pai e, em seguida, cria os recursos filho abaixo desse recurso pai. Você começa com o recurso raiz como um pai, adiciona um recurso a esse pai, adiciona outro recurso a esse recurso filho como novo pai, e assim por diante, ao identificador pai. Em seguida, você adiciona o recurso indicado ao pai. O comando [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) indicado abaixo recupera todos os recursos de uma API: ``` aws apigateway get-resources --rest-api-id apiId ``` Para o exemplo de API PetStore, essa lista é semelhante à seguinte: ``` { "items": [ { "path": "/pets", "resourceMethods": { "GET": {} }, "id": "6sxz2j", "pathPart": "pets", "parentId": "svzr2028x8" }, { "path": "/pets/{petId}", "resourceMethods": { "GET": {} }, "id": "rjkmth", "pathPart": "{petId}", "parentId": "6sxz2j" }, { "path": "/", "id": "svzr2028x8" } ] } ``` Cada item lista os identificadores do recurso (`id`) e, exceto para o recurso raiz, seu pai imediato (`parentId`), bem como o nome do recurso (`pathPart`). O recurso raiz é especial, pois não tem nenhum pai. Depois de escolher um recurso como primário, use o comando a seguir para adicionar um recurso secundário. ``` aws apigateway create-resource --rest-api-id apiId \ --parent-id parentId \ --path-part resourceName ``` Por exemplo, para colocar rações para animais de estimação à venda no site PetStore, use o seguinte comando: ``` aws apigateway create-resource --rest-api-id a1b2c3 \ --parent-id svzr2028x8 \ --path-part food ``` A saída será exibida da seguinte forma: ``` { "path": "/food", "pathPart": "food", "id": "xdsvhp", "parentId": "svzr2028x8" } ``` ### Usar um recurso de proxy para simplificar a configuração de API À medida que os negócios crescem, o proprietário da PetStore pode decidir adicionar alimentos, brinquedos e outros itens relacionados a animais de estimação para venda. Para oferecer suporte a isso, você pode adicionar `/food`, `/toys` e outros recursos ao recurso raiz. Em cada categoria de venda, você também pode adicionar mais recursos, como `/food/{type}/{item}`, `/toys/{type}/{item}`, etc. Isso pode ser entediante. Se você decidir adicionar uma camada intermediária `{subtype}` aos caminhos de recursos para alterar a hierarquia de caminhos em `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc., as alterações romperão a configuração da API existente. Para evitar isso, você pode usar um [recurso de proxy](api-gateway-set-up-simple-proxy.md) do API Gateway para expor um conjunto de recursos da API simultaneamente. O API Gateway define um recurso de proxy como um espaço reservado para um recurso a ser especificado quando a solicitação é enviada. Um recurso de proxy é expresso por um parâmetro de caminho especial `{proxy+}`, geralmente conhecido como um parâmetro de caminho voraz. O sinal `+` indica os recursos filho que estão anexados a ele. O espaço reservado `/parent/{proxy+}` representa qualquer recurso que corresponda ao padrão de caminho de `/parent/*`. Você pode usar qualquer string para o nome do parâmetro de caminho voraz. O comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) indicado abaixo cria um recurso de proxy sob a raiz (`/{proxy+}`): ``` aws apigateway create-resource --rest-api-id apiId \ --parent-id rootResourceId \ --path-part {proxy+} ``` A saída será exibida da seguinte forma: ``` { "path": "/{proxy+}", "pathPart": "{proxy+}", "id": "234jdr", "parentId": "svzr2028x8" } ``` Para o exemplo de API `PetStore`, você pode usar `/{proxy+}` para representar o `/pets` e o `/pets/{petId}`. Esse recurso de proxy também pode fazer referência a qualquer outro recurso (existente ou a ser adicionado), como `/food/{type}/{item}`, `/toys/{type}/{item}`, etc., ou `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc. O desenvolvedor de backend determina a hierarquia de recursos, e o desenvolvedor do cliente é responsável por entendê-la. O API Gateway simplesmente transfere o que o cliente enviou ao backend. Uma API pode ter mais de um recurso de proxy. Por exemplo, os recursos de proxy a seguir são permitidos em uma API, pressupondo-se que `/parent/{proxy+}` não seja o mesmo proxy principal que `/parent/{child}/{proxy+}`. ``` /{proxy+} /parent/{proxy+} /parent/{child}/{proxy+} ``` Quando um recurso de proxy tem irmãos não proxy, os recursos irmãos são excluídos da representação do recurso de proxy. Para os exemplos anteriores, `/{proxy+}` refere-se a todos os recursos sob o recurso raiz, exceto os recursos `/parent[/*]`. Ou seja, uma solicitação de método em um recurso específico tem precedência sobre uma solicitação de método em um recurso genérico no mesmo nível da hierarquia de recursos. A tabela abaixo mostra como o API Gateway encaminha solicitações aos recursos a seguir para o estágio `prod` de uma API. ``` ANY /{proxy+} GET /pets/{proxy+} GET /pets/dog ``` | Solicitação | Rota selecionada | Explicação | | --- | --- | --- | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | A solicitação corresponde totalmente a esse recurso. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | A variável de caminho voraz `/pets/{proxy+}` captura essa solicitação. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | A variável de caminho voraz `/{proxy+}` captura essa solicitação. | Um recurso de proxy não pode ter nenhum recurso filho. Qualquer recurso de API após `{proxy+}` é redundante e ambíguo. Os seguintes recursos de proxy não são permitidos dentro de uma API. ``` /{proxy+}/child /parent/{proxy+}/{child} /parent/{child}/{proxy+}/{grandchild+} ``` ## Configurar um método HTTP Uma solicitação de método de API é encapsulada pelo recurso [Método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) do API Gateway. Para configurar a solicitação de método, você deve primeiro instanciar o recurso `Method`, definindo pelo menos um método HTTP e um tipo de autorização no método. Intimamente associado ao recurso de proxy, o API Gateway oferece suporte a um método HTTP de `ANY`. Esse método `ANY` representa qualquer método HTTP que deve ser fornecido em tempo de execução. Ele permite usar uma única configuração de método de API para todos os métodos HTTP com suporte de `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. Você também pode configurar o método `ANY` em um recurso de proxy. Combinando o método `ANY` com um recurso de proxy, você obtém uma única configuração de método de API para todos os métodos HTTP com suporte em qualquer recurso de uma API. Além disso, o backend pode evoluir sem romper a configuração da API existente. Antes de definir um método de API, considere quem pode chamar o método. Defina o tipo de autorização de acordo com seu plano. Para acesso aberto, defina-o como `NONE`. Para usar permissões do IAM, defina o tipo de autorização como `AWS_IAM`. Para usar uma função de autorizador do Lambda, defina essa propriedade como `CUSTOM`. Para usar um grupo de usuários do Amazon Cognito, defina o tipo de autorização como `COGNITO_USER_POOLS`. O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) a seguir cria uma solicitação de método para o verbo `ANY` usando permissões do IAM para controlar o respectivo acesso. ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method ANY \ --authorization-type AWS_IAM ``` Para criar uma solicitação de método de API com um tipo de autorização diferente, consulte [Configurar a autorização de solicitação de método](#setup-method-request-authorization). ## Configurar parâmetros da solicitação de método Os parâmetros da solicitação de método são uma forma de um cliente fornecer dados de entrada ou o contexto de execução necessário para concluir a solicitação de método. Um parâmetro de método pode ser um parâmetro de caminho, um cabeçalho ou um parâmetro de string de consulta. Como parte da configuração de solicitação de método, você deve declarar os parâmetros de solicitação necessários para disponibilizá-los para o cliente. Para a integração não proxy, você pode converter esses parâmetros de solicitação em um formulário que seja compatível com o requisito de backend. Por exemplo, para a solicitação de método `GET /pets/{petId}`, a variável de caminho `{petId}` é um parâmetro de solicitação necessário. Você pode declarar esse parâmetro de caminho ao chamar o comando `put-method` da AWS CLI. O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo cria um método com um parâmetro de caminho necessário: ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id rjkmth \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.path.petId=true ``` Se um parâmetro não for necessário, você poderá configurá-lo como `false` em `request-parameters`. Por exemplo, se o método `GET /pets` usar um parâmetro de string de consulta opcional de `type` e um parâmetro de cabeçalho opcional de `age`, você pode declará-los usando o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo: ``` aws apigateway put-method --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.querystring.type=false,method.request.header.age=false ``` Em vez desse formulário resumido, você pode usar uma string JSON para definir o valor `request-parameters`: ``` '{"method.request.querystring.type":false,"method.request.header.age":false}' ``` Com essa configuração, o cliente pode consultar animais de estimação por tipo: ``` GET /pets?type=dog ``` E pode realizar uma consulta de filhotes caninos da seguinte forma: ``` GET /pets?type=dog age:puppy ``` Para obter informações sobre como mapear parâmetros da solicitação de método para parâmetros de solicitação de integração, consulte [Integrações para APIs REST no API Gateway](how-to-integration-settings.md). ## Configurar um modelo de solicitação de método Para um método de API que possa levar dados de entrada em uma carga útil, você pode usar um modelo. Um modelo é expresso em um [esquema JSON rascunho 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) e descreve a estrutura de dados do corpo da solicitação. Com um modelo, um cliente pode determinar como construir uma carga útil de solicitação de método como entrada. Mais importante, o API Gateway usa o modelo para [validar uma solicitação](api-gateway-method-request-validation.md), [gerar um SDK](how-to-generate-sdk.md) e inicializar um modelo de mapeamento para configurar a integração no console do API Gateway. Para ter informações sobre como criar um [modelo](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html), consulte [Noções básicas dos modelos de dados](models-mappings-models.md). Dependendo dos tipos de conteúdo, uma carga útil de método pode ter diferentes formatos. Um modelo é indexado no tipo de mídia da carga útil aplicada. O API Gateway usa o cabeçalho `Content-Type` da solicitação para determinar o tipo de conteúdo. Para configurar modelos de solicitação de método, adicione pares de chave-valor no formato `"media-type":"model-name"` ao mapa `requestModels` ao chamar o comando AWS CLI da `put-method`. Para usar o mesmo modelo, independentemente do tipo de conteúdo, especifique `$default` como a chave. Por exemplo, para definir um modelo na carga útil JSON da solicitação de método `POST /pets` da API de exemplo PetStore, você pode usar o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo: ``` aws apigateway put-method \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method POST \ --authorization-type "NONE" \ --request-models '{"application/json":"petModel"}' ``` Aqui, `petModel` é o valor de propriedade `name` de um recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) que descreve um animal de estimação. A definição de esquema JSON real é expressa como um valor de string JSON da propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema) do recurso `Model`. Em um Java ou outro SDK fortemente tipado, da API, os dados de entrada são emitidos como a classe `petModel` derivada da definição de esquema. Com o modelo de solicitação, os dados de entrada no SDK gerado são convertidos na classe `Empty`, que é derivada do modelo `Empty` padrão. Nesse caso, o cliente não pode instanciar a classe de dados correta para fornecer a entrada necessária. ## Configurar a autorização de solicitação de método Para controlar quem pode chamar o método de API, você pode configurar o [tipo de autorização](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType) no método. Você pode usar esse tipo para adotar um dos autorizadores com suporte, incluindo funções e políticas do IAM (`AWS_IAM`), um grupo de usuários do Amazon Cognito (`COGNITO_USER_POOLS`) ou um autorizador do Lambda (`CUSTOM`). Para usar permissões do IAM para autorizar o acesso ao método de API, defina a propriedade de entrada `authorization-type` como **AWS\$1IAM**. Ao definir essa opção, o API Gateway verifica a assinatura do autor da chamada na solicitação, com base nas credenciais do autor da chamada. Se o usuário verificado tiver permissão para chamar o método, ela será aceita. Caso contrário, a solicitação será rejeitada, e o autor da chamada receberá uma resposta de erro não autorizada. A chamada para o método não é bem-sucedida, a menos que o autor da chamada tenha permissão para invocar o método da API. A seguinte política do IAM concede permissão ao autor da chamada para chamar qualquer método de API criado na mesma Conta da AWS: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": "arn:aws:execute-api:*:*:*" } ] } ``` ------ Para obter mais informações, consulte [Controlar o acesso a uma API REST com permissões do IAM](permissions.md). Atualmente, você só pode conceder essa política aos usuários, grupos e funções na Conta da AWS do proprietário da API. Os usuários de outra Conta da AWS poderão chamar os métodos de API somente se eles tiverem permissão para assumir uma função na Conta da AWS do proprietário da API com as permissões necessárias para chamar a ação `execute-api:Invoke`. Para obter informações sobre as permissões entre contas, consulte [Uso de funções do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). Você pode usar a AWS CLI, um AWS SDK ou um cliente de API REST, como o [Postman](https://www.postman.com/), que implementa a [assinatura do Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Para usar um autorizador do Lambda para autorizar o acesso ao método de API, defina a propriedade de entrada `authorization-type` como `CUSTOM` e defina a propriedade de entrada [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) como o valor da propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) de um autorizador do Lambda que já existe. O autorizador do Lambda referenciado pode ser do tipo `TOKEN` ou `REQUEST`. Para obter mais informações sobre como criar um autorizador do Lambda, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md). Para usar um grupo de usuários do Amazon Cognito para autorizar o acesso ao método de API, defina a propriedade de entrada `authorization-type` como `COGNITO_USER_POOLS` e defina a propriedade de entrada [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) como o valor da propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) do autorizador `COGNITO_USER_POOLS` que já foi criado. Para obter informações sobre como criar um autorizador do grupo de usuários do Amazon Cognito, consulte [Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). ## Configurar a validação da solicitação de método Você pode habilitar a validação de solicitação ao configurar uma solicitação de método de API. Primeiro, é necessário criar um [validador de solicitação](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html). O comando [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html) a seguir cria um validador somente do corpo da solicitação. ``` aws apigateway create-request-validator \ --rest-api-id 7zw9uyk9kl \ --name bodyOnlyValidator \ --validate-request-body \ --no-validate-request-parameters ``` A saída será exibida da seguinte forma: ``` { "validateRequestParameters": false, "validateRequestBody": true, "id": "jgpyy6", "name": "bodyOnlyValidator" } ``` Você pode usar esse validador de solicitação para utilizar a validação de solicitação como parte da configuração de solicitação de método: O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo cria uma solicitação de método que exige que o corpo da solicitação de entrada corresponda ao `PetModel` e tem dois parâmetros de solicitação que não são obrigatórios: ``` aws apigateway put-method \ --rest-api-id 7zw9uyk9kl \ --resource-id xdsvhp \ --http-method PUT \ --authorization-type "NONE" \ --request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \ --request-models '{"application/json":"petModel"}' \ --request-validator-id jgpyy6 ``` Para incluir um parâmetro de solicitação na respectiva validação, você deve definir `validateRequestParameters` como `true` para o validador da solicitação e definir o parâmetro específico da solicitação como `true` no comando `put-method`. # Configurar uma resposta de método no API Gateway Uma resposta de método de API encapsula a saída de uma solicitação de método de API que será recebida pelo cliente. Os dados de saída incluem um código de status HTTP, alguns cabeçalhos e possivelmente um corpo. Com integrações não proxy, os parâmetros de resposta especificados e o corpo podem ser mapeados dos dados de resposta de integração associados ou podem receber certos valores estáticos de acordo com os mapeamentos. Esses mapeamentos são especificados na resposta de integração. O mapeamento pode ser uma transformação idêntica que passe pela resposta de integração no estado em que se encontra. Com uma integração de proxy, o API Gateway passa a resposta de backend para a resposta de método automaticamente. Não há necessidade de configurar a resposta de método de API. No entanto, com a integração do proxy do Lambda, a função do Lambda deve retornar um resultado [desse formato de saída](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) para o API Gateway mapear com êxito a resposta de integração a uma resposta de método. Programaticamente, a configuração da resposta de método equivale à criação de um recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) do API Gateway e à definição das propriedades de [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) e [responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels). Ao definir os códigos de status de um método de API, você deve escolher um como o padrão para lidar com qualquer resposta de integração de um código de status imprevisto. É razoável definir `500` como padrão, pois isso equivale à geração de respostas não mapeadas de outra forma como um erro no servidor. Por motivos educacionais, o console do API Gateway define a resposta `200` como padrão. No entanto, você pode redefini-la como a resposta `500`. Para configurar uma resposta de método, você deve ter criado a solicitação de método. ## Configurar o código de status de resposta de método O código de status de uma resposta de método define um tipo de resposta. Por exemplo, as respostas 200, 400 e 500 indicam respostas bem-sucedidas de erros no servidor e no cliente, respectivamente. Para configurar um código de status de resposta de método, defina a propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode) como um código de status HTTP. O comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) a seguir cria uma resposta de método `200`. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 ``` ## Configurar parâmetros da resposta de método Os parâmetros da resposta de método definem quais cabeçalhos o cliente recebe em resposta à solicitação de método associada. Os parâmetros de resposta também especificam um destino para o qual o API Gateway mapeia um parâmetro de resposta de integração de acordo com os mapeamentos prescritos na resposta de integração do método de API. Para configurar os parâmetros de resposta de método, adicione ao mapa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) de pares de chave-valor `MethodResponse` do formato `"{parameter-name}":"{boolean}"`. O comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) a seguir define o cabeçalho `my-header`. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false ``` ## Configurar modelos de resposta de método Um modelo de resposta de método define um formato do corpo de resposta de método. A configuração de um modelo de resposta de método é necessária quando você gera um SDK fortemente tipado para a API. Ela garante que a saída seja gerada em uma classe apropriada em Java ou Objective-C. Em outros casos, a definição de um modelo é opcional. Antes de configurar o modelo de resposta, você deve primeiro criar o modelo no API Gateway. Para fazer isso, você pode chamar o comando `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)`. O comando [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) a seguir cria o modelo `PetStorePet` para descrever o corpo da resposta à solicitação do método `GET /pets/{petId}`. ``` aws apigateway create-model \ --rest-api-id vaz7da96z6 \ --content-type application/json \ --name PetStorePet \ --schema '{ \ "$schema": "http://json-schema.org/draft-04/schema#", \ "title": "PetStorePet", \ "type": "object", \ "properties": { \ "id": { "type": "number" }, \ "type": { "type": "string" }, \ "price": { "type": "number" } \ } \ }' ``` O resultado é criado como um recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) do API Gateway. Para configurar os modelos de resposta de método a fim de definir o formato de carga útil, adicione o par de chave-valor "application/json":"PetStorePet" ao mapa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels) do recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). O comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) indicado abaixo cria uma resposta de método que usa um modelo de resposta para definir o formato da carga útil: ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false \ --response-models '{"application/json":"PetStorePet"}' ``` # Configurar um método usando o console do API Gateway Ao criar um método usando o console da API REST, você configura a solicitação de integração e a solicitação de método. Por padrão, o API Gateway cria a resposta do método `200` para seu método. As instruções a seguir mostram como editar as configurações de solicitação de método e como criar respostas de método adicionais para seu método. **Topics** + [Editar uma solicitação de método do API Gateway no console do API Gateway](#how-to-method-settings-callers-console) + [Configurar uma resposta do método API Gateway usando o console do API Gateway](#how-to-method-response-settings-console) ## Editar uma solicitação de método do API Gateway no console do API Gateway Estas instruções supõem que você já criou sua solicitação de método. Para saber mais sobre como criar um método, consulte [Configurar uma solicitação de integração de API usando o console do API Gateway](how-to-method-settings-console.md). 1. No painel **Recursos**, escolha o método e selecione a guia **Solicitação de método**. 1. Na seção **Configurações de solicitação de método**, selecione **Editar**. 1. Em **Autorização**, selecione um autorizador disponível. 1. Para habilitar o acesso aberto ao método para qualquer usuário, selecione **Nenhum**. Essa etapa poderá ser ignorada se a configuração padrão não tiver sido alterada. 1. Para usar permissões do IAM para controlar o acesso do cliente ao método, selecione `AWS_IAM`. Com essa opção, somente os usuários das funções do IAM com a política do IAM correta anexada terão permissão para chamar esse método. Para criar a função do IAM, especifique uma política de acesso com um formato semelhante ao seguinte: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/" ] } ] } ``` ------ Nesta política de acesso, `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/` é o ARN do seu método. Você pode encontrar o ARN do seu método selecionando o método na página **Recursos**. Para obter mais informações sobre como definir as permissões do IAM, consulte [Controlar o acesso a uma API REST com permissões do IAM](permissions.md). Para criar um perfil do IAM, é possível adaptar as instruções no seguinte tutorial: [Criar uma função do Lambda para integração não proxy do Lambda](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda). 1. Para usar um autorizador do Lambda, selecione um autorizador de solicitação ou token. Crie um autorizador do Lambda para que essa opção seja exibida no menu suspenso. Para obter informações sobre como criar um autorizador do Lambda, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md). 1. Para usar um grupo de usuários do Amazon Cognito, escolha um grupo de usuários disponíveis em **Cognito user pool authorizers (Autorizadores do grupo de usuários do Cognito)**. Crie um grupo de usuários no Amazon Cognito e um autorizador do grupo de usuários do Amazon Cognito no API Gateway para que essa opção seja exibida no menu suspenso. Para obter informações sobre como criar um autorizador do grupo de usuários do Amazon Cognito, consulte [Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). 1. Para especificar a validação da solicitação, selecione um valor no menu suspenso **Validador de solicitação**. Para desativar a validação da solicitação, selecione **Nenhuma**. Para obter mais informações sobre cada opção, consulte [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md). 1. Selecione **Chave de API obrigatória** para exigir uma chave de API. Quando ativadas, as chaves de APIs são usadas em [planos de uso](api-gateway-api-usage-plans.md) para controlar o tráfego do cliente. 1. (Opcional) Para atribuir um nome da operação em um SDK do Java dessa API, gerada pelo API Gateway, em **Nome da operação**, digite um nome. Por exemplo, para a solicitação de método de `GET /pets/{petId}`, o nome da operação de Java SDK correspondente é, por padrão,`GetPetsPetId`. Esse nome é construído a partir do verbo HTTP do método (`GET`) e os nomes de variáveis de caminho de recurso (`Pets` e `PetId`). Se você definir o nome da operação como `getPetById`, o nome da operação de SDK se tornará `GetPetById`. 1. Para adicionar um parâmetro de string de consulta ao método, faça o seguinte: 1. Selecione **Parâmetros de string de consulta de URL** e escolha **Adicionar string de consulta**. 1. Em **Nome**, digite o nome do parâmetro de string de consulta. 1. Selecione **Obrigatório** se o parâmetro de string de consulta recém-criado precisar ser usado para a validação de solicitação. Para obter mais informações sobre a validação de solicitação, consulte [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md). 1. Selecione **Armazenamento em cache** se o parâmetro de string de consulta recém-criado precisar ser usado como parte de uma chave de armazenamento em cache. Para obter mais informações sobre armazenamento em cache, consulte [Usar parâmetros de método ou integração como chaves de cache para indexar respostas em cache](api-gateway-caching.md#enable-api-gateway-cache-keys). Para remover o parâmetro de string de consulta, selecione **Remover**. 1. Para adicionar um parâmetro de cabeçalho ao método, faça o seguinte: 1. Selecione **Cabeçalhos de solicitação HTTP** e, depois, **Adicionar cabeçalho**. 1. Em **Nome**, insira o nome do cabeçalho. 1. Selecione **Obrigatório** se o cabeçalho recém-criado precisar ser usado para a validação de solicitação. Para obter mais informações sobre a validação de solicitação, consulte [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md). 1. Selecione **Armazenamento em cache** se o cabeçalho recém-criado precisar ser usado como parte de uma chave de armazenamento em cache. Para obter mais informações sobre armazenamento em cache, consulte [Usar parâmetros de método ou integração como chaves de cache para indexar respostas em cache](api-gateway-caching.md#enable-api-gateway-cache-keys). Para remover o cabeçalho, selecione **Remover**. 1. Para declarar o formato de carga útil de uma solicitação de método com o verbo HTTP `POST`, `PUT` ou `PATCH`, expanda **Corpo da solicitação** e faça o seguinte: 1. Escolha **Add model** (Adicionar modelo). 1. Em **Tipo de conteúdo**, insira um tipo MIME (por exemplo, `application/json`). 1. Em **Modelo**, selecione um modelo no menu suspenso. Os modelos atualmente disponíveis para a API incluem os modelos padrão `Empty` e `Error`, bem como quaisquer modelos que você tenha criado e adicionado à coleção de [Modelos](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) da API. Para obter mais informações sobre a criação de um modelo, consulte [Modelos de dados para APIs REST](models-mappings-models.md). **nota** O modelo é útil para informar ao cliente o formato de dados esperado de uma carga útil. Ele é útil para gerar um modelo de mapeamento de esqueleto. É importante gerar um SDK altamente tipado da API em linguagens como Java, C \$1, Objective-C e Swift. Ele só será necessário se a validação de solicitação estiver ativada para a carga útil. 1. Escolha **Salvar**. ## Configurar uma resposta do método API Gateway usando o console do API Gateway Um método de API pode ter uma ou mais respostas. Cada resposta é indexada por seu código de status HTTP. Por padrão, o console do API Gateway adiciona a resposta `200` às respostas de método. Você pode modificá-la, por exemplo, para que o método retorne `201` em vez disso. Você pode adicionar outras respostas, por exemplo, `409` para negação de acesso e `500` para variáveis de estágio não inicializadas utilizadas. Para usar o console do API Gateway para modificar, excluir ou adicionar uma resposta a um método de API, siga estas instruções. 1. No painel **Recursos**, escolha o método e selecione a guia **Resposta do método**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. 1. Na seção **Configurações de resposta do método**, selecione **Criar resposta**. 1. Em **Código de status HTTP**, insira um código de status HTTP, como `200`, `400` ou `500`. Quando uma resposta retornada pelo backend não tiver uma resposta de método correspondente definida, o API Gateway não retornará a resposta para o cliente. Em vez disso, ele retornará uma resposta de erro `500 Internal server error`. 1. Escolha **Add header** (Adicionar cabeçalho). 1. Em **Nome de cabeçalho**, insira um nome. Para retornar um cabeçalho do back-end para o cliente, adicione o cabeçalho à resposta do método. 1. Selecione **Adicionar modelo** para definir um formato do corpo de resposta de método. Digite o tipo de mídia da carga útil de resposta para **Tipo de conteúdo** e selecione um modelo no menu suspenso **Modelos**. 1. Escolha **Salvar**. Para modificar uma resposta existente, acesse a resposta do método e selecione **Editar**. Para alterar o **Código de status HTTP**, selecione **Excluir** e crie uma resposta de método. Para cada resposta retornada do backend, você deve ter uma resposta compatível configurada como a resposta de método. No entanto, a configuração de cabeçalhos de resposta de método e o modelo de carga útil são opcionais, a menos que você mapeie o resultado do backend para a resposta de método antes de retornar para o cliente. Além disso, um modelo de carga útil de resposta de método é importante se você pretende gerar um SDK fortemente tipado para sua API. # Controlar e gerenciar o acesso a APIs REST no API Gateway O API Gateway oferece suporte a vários mecanismos de controle e gerenciamento de acesso à sua API. Os mecanismos a seguir podem ser usados para autenticação e autorização: + As **políticas de recursos** permitem que você crie políticas baseadas em recursos para permitir ou negar acesso a APIs e métodos de endereços IP de origem ou endpoints da VPC especificados. Para obter mais informações, consulte [Controlar o acesso a uma API REST com políticas de recursos do API Gateway](apigateway-resource-policies.md). + As **funções e políticas padrão do AWS IAM** oferecem controles de acesso flexíveis e robustos que podem ser aplicados a uma API inteira ou a métodos individuais. As funções e políticas do IAM podem ser usadas para controlar quem pode criar, gerenciar e chamar suas APIs. Para obter mais informações, consulte [Controlar o acesso a uma API REST com permissões do IAM](permissions.md). + As **tags do IAM** podem ser usadas com as políticas do IAM para controlar o acesso. Para obter mais informações, consulte [Usar tags para controlar o acesso aos recursos da API REST do API Gateway](apigateway-tagging-iam-policy.md). + As **políticas de endpoint para VPC endpoints de interface** permitem anexar políticas de recurso do IAM a endpoints da VPC de interface a fim de melhorar a segurança das [APIs privadas](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html). Para obter mais informações, consulte [Usar políticas de VPC endpoint para APIs privadas no API Gateway](apigateway-vpc-endpoint-policies.md). + **Autorizadores do Lambda** são funções do Lambda que controlam o acesso aos métodos da API REST usando a autenticação de token de portador, bem como informações descritas pelos cabeçalhos, caminhos, strings de consulta, variáveis de estágio ou parâmetros de solicitação de variáveis de contexto. Autorizadores do Lambda são usados para controlar quem pode chamar métodos da API REST. Para obter mais informações, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md). + Os **grupos de usuários do Amazon Cognito** permitem criar soluções de autenticação e autorização personalizáveis para suas APIs REST. Os grupos de usuários do Amazon Cognito são usados para controlar quem pode invocar métodos da API REST. Para obter mais informações, consulte [Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). É possível usar os mecanismos a seguir para executar outras tarefas relacionadas a controle de acesso: + O **compartilhamento de recursos entre origens (CORS)** permite que você controle como a API REST responde a solicitações de recursos entre domínios. Para obter mais informações, consulte [CORS para APIs REST no API Gateway](how-to-cors.md). + Os **certificados SSL no lado do cliente** podem ser usados para verificar se as solicitações HTTP para seu sistema backend provêm do API Gateway. Para obter mais informações, consulte [Gerar e configurar um certificado SSL para autenticação de backend no API Gateway](getting-started-client-side-ssl-authentication.md). + **AWS WAF** O pode ser usado para proteger sua API do API Gateway contra explorações comuns da Web. Para obter mais informações, consulte [Usar o AWS WAF para proteger as APIs REST no API Gateway](apigateway-control-access-aws-waf.md). É possível usar os mecanismos a seguir para rastrear e limitar o acesso que você concedeu a clientes autorizados: + Os **planos de uso** permitem que você forneça **chaves da API** aos clientes e monitore e restrinja o uso dos estágios e métodos da API para cada chave da API. Para obter mais informações, consulte [Usar planos e chaves de API para APIs REST no APIs Gateway](api-gateway-api-usage-plans.md). # Controlar o acesso a uma API REST com políticas de recursos do API Gateway As *políticas de recursos* do Amazon API Gateway são documentos de política JSON que você anexa a uma API para controlar se uma entidade principal especificada (geralmente um usuário ou um perfil do IAM) pode invocar a API. Você pode usar as políticas de recursos do API Gateway para permitir que sua API seja invocada de forma segura por: + Usuários de uma determinada conta da AWS. + Intervalos de endereços IP ou blocos CIDR de origem especificados. + Nuvens privadas virtuais (VPCs) ou endpoints da VPC (em qualquer conta) específicos Você pode anexar uma política de recursos para qualquer tipo de endpoint de API no API Gateway usando o Console de gerenciamento da AWS, a AWS CLI ou os AWS SDKs. Para [APIs privadas](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html), é possível usar políticas de recurso em conjunto com políticas de VPC endpoint para controlar quais principais têm acesso a quais recursos e ações. Para obter mais informações, consulte [Usar políticas de VPC endpoint para APIs privadas no API Gateway](apigateway-vpc-endpoint-policies.md). As políticas de recursos do API Gateway são diferentes das políticas baseadas em identidade do IAM. As políticas baseadas em identidade do IAM são anexadas usuários, grupos ou funções do IAM e definem quais ações essas entidades são capazes de executar em quais recursos. As políticas de recursos do API Gateway são anexadas aos recursos. Você pode usar as políticas de recursos do API Gateway junto com as políticas do IAM. Para obter mais informações, consulte [Políticas baseadas em identidade e políticas baseadas em recurso](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html). **Topics** + [Visão geral da linguagem de políticas de acesso para o Amazon API Gateway](apigateway-control-access-policy-language-overview.md) + [Como as políticas de recursos do API Gateway afetam o fluxo de trabalho de autorização](apigateway-authorization-flow.md) + [Exemplos de política de recursos do API Gateway](apigateway-resource-policies-examples.md) + [Criar e anexar uma política de recursos do API Gateway a uma API](apigateway-resource-policies-create-attach.md) + [AWSAs chaves condições da que podem ser usadas nas políticas de recursos do API Gateway](apigateway-resource-policies-aws-condition-keys.md) # Visão geral da linguagem de políticas de acesso para o Amazon API Gateway Esta página descreve os elementos básicos usados nas políticas de recursos do Amazon API Gateway. As políticas de recursos são especificadas usando a mesma sintaxe que as políticas do IAM. Para obter as informações completas sobre a linguagem da política, consulte [Visão geral de políticas do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) e [Referência de políticas do AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) no *Guia do usuário do IAM*. Para obter informações sobre como um serviço da AWS determina se uma solicitação deve ser permitida ou negada, consulte [Determinar se uma solicitação é permitida ou negada](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow). ## Elementos comuns em uma política de acesso No sentido mais básico, uma política de recursos contém os seguintes elementos: + **Recursos** – APIs são os recursos do Amazon API Gateway para os quais você pode permitir ou negar permissões. Em uma política, você usa o nome de recurso da Amazon (ARN) para identificar o recurso. Também é possível usar a sintaxe abreviada, que o API Gateway expande automaticamente para o ARN completo ao salvar uma política de recursos. Para saber mais, consulte [Exemplos de política de recursos do API Gateway](apigateway-resource-policies-examples.md). Para o formato do elemento `Resource` completo, consulte [Formato de recurso das permissões para executar a API no API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-resource-format-for-executing-api). + **Ações** — para cada recurso, o Amazon API Gateway oferece suporte a um conjunto de operações. Você identifica as operações de recursos que permitirão (ou negarão) usando palavras-chave de ação. Por exemplo, a `execute-api:Invoke` permissão permite que o usuário permissão para chamar uma API mediante a solicitação de um cliente. Para o formato do elemento `Action`, consulte [Formato de ação das permissões para executar a API no API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-action-format-for-executing-api). + **Efeito** — qual é o efeito quando o usuário solicita a ação específica, que pode ser `Allow` ou `Deny`. Você também pode negar explicitamente o acesso a um recurso, o que pode fazer para ter a certeza de que um usuário não consiga acessá-lo, mesmo que uma política diferente conceda acesso. **nota** "Negação explícita" é a mesma coisa que "Negação por padrão". Uma “negação implícita” é diferente de uma “negação explícita”. Para obter mais informações, consulte [A diferença entre negação por padrão e negação explícita](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#AccessPolicyLanguage_Interplay). + **Entidade principal**: a conta ou o usuário que tem permissão de acesso a ações e recursos na instrução. Em uma política de recursos, a entidade principal é o usuário ou a conta que recebe essa permissão. O exemplo de política de recursos a seguir mostra os elementos comuns de política anteriores. A política concede acesso a todas as APIs no *account-id* especificado na *region* especificada para qualquer usuário cujo endereço IP de origem esteja no bloco de endereço *123.4.5.6/24*. A política nega todo o acesso à API se o IP de origem do usuário não estiver dentro do intervalo. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:*" }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:*", "Condition": { "NotIpAddress": { "aws:SourceIp": "123.4.5.6/24" } } } ] } ``` ------ # Como as políticas de recursos do API Gateway afetam o fluxo de trabalho de autorização Quando o API Gateway avalia a política de recurso anexada à sua API, o resultado é afetado pelo tipo de autenticação definido para a API, conforme ilustrado nos fluxogramas das próximas seções. **Topics** + [Somente política de recursos do API Gateway](#apigateway-authorization-flow-resource-policy-only) + [Política de recursos e autorizador do Lambda](#apigateway-authorization-flow-lambda) + [Política de recursos e autenticação do IAM](#apigateway-authorization-flow-iam) + [Autenticação e política de recursos do Amazon Cognito](#apigateway-authorization-flow-cognito) + [Tabelas de resultados de avaliação de política](#apigateway-resource-policies-iam-policies-interaction) ## Somente política de recursos do API Gateway Neste fluxo de trabalho, uma política de recursos do API Gateway é anexada à API, mas nenhum tipo de autenticação é definido para a API. A avaliação da política envolve a busca de uma permissão explícita baseada nos critérios de entrada do autor da chamada. Uma negação implícita ou qualquer negação explícita resulta na negação do autor da chamada. ![\[Fluxo de autorização somente de uma política de recursos.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/apigateway-auth-resource-policy-only.png) Veja a seguir um exemplo dessa política de recursos. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/", "Condition": { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ ## Política de recursos e autorizador do Lambda Neste fluxo de trabalho, um autorizador do Lambda é configurado para a API, além de uma política de recursos. A política de recursos é avaliada em duas fases. Antes de chamar o autorizador do Lambda, o API Gateway primeiro avalia a política e verifica se há negações explícitas. Se encontradas, o autor da chamada terá o acesso negado imediatamente. Caso contrário, o autorizador do Lambda é chamado e retorna um [documento de política](api-gateway-lambda-authorizer-output.md), que é avaliado em conjunto com a política de recursos. Se seu autorizador usa armazenamento em cache, o API Gateway pode exibir o documento de política em cache. O resultado é determinado com base na [Tabela A](#apigateway-resource-policies-iam-policies-interaction). O exemplo de política de recursos a seguir permite chamadas somente a partir do VPC endpoint cujo ID de VPC endpoint é `vpce-1a2b3c4d`. Durante a avaliação de “pré-autorização”, somente as chamadas vindas do VPC endpoint indicado no exemplo são permitidas para prosseguir e avaliar o autorizador do Lambda. Todas as chamadas restantes são bloqueadas. Esse fluxo de trabalho de autorização será o mesmo se você usar um nome de domínio personalizado para uma API privada. ![\[Fluxo de autorização de uma política de recursos e um autorizador do Lambda.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/apigateway-auth-lambda-resource-policy.png) ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-1a2b3c4d" } } } ] } ``` ------ ## Política de recursos e autenticação do IAM Nesse fluxo de trabalho, uma autenticação do IAM é configurada para a API além de uma política de recursos. Depois de autenticar o usuário com o serviço do IAM, a API avalia as duas políticas anexadas ao usuário, além da política de recursos. O resultado varia com base na origem do autor da chamada, se ele está na mesma Conta da AWS ou em outra Conta da AWS do proprietário da API. Se o autor da chamada e o proprietário da API forem de contas diferentes, as políticas do IAM e a política de recursos deverão permitir explicitamente que o autor da chamada prossiga. Consulte mais informações em [Tabela B](#apigateway-resource-policies-iam-policies-interaction). No entanto, se o autor da chamada e o proprietário da API estiverem na mesma Conta da AWS, as políticas de usuário do IAM ou a política de recursos deverá permitir explicitamente que o autor da chamada prossiga. Consulte mais informações em [Tabela A](#apigateway-resource-policies-iam-policies-interaction). ![\[Fluxo de autorização de uma política de recursos e autenticação do IAM.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/apigateway-auth-iam-resource-policy.png) Veja a seguir um exemplo de uma política de recursos entre contas. Pressupondo-se que a política do IAM contenha um efeito de permissão, essa política de recursos permite chamadas somente da VPC cujo ID é `vpc-2f09a348`. Consulte mais informações em [Tabela B](#apigateway-resource-policies-iam-policies-interaction). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/" ], "Condition" : { "StringEquals": { "aws:SourceVpc": "vpc-2f09a348" } } } ] } ``` ------ ## Autenticação e política de recursos do Amazon Cognito Neste fluxo de trabalho, um [grupo de usuários do Amazon Cognito](apigateway-integrate-with-cognito.md) é configurado para a API, além de uma política de recursos. O API Gateway primeiro tenta autenticar o autor da chamada por meio do Amazon Cognito. Isso é normalmente executado por meio de um [token JWT](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) que é fornecido pelo autor da chamada. Se a autenticação for bem-sucedida, a política de recursos é avaliada de forma independente e é necessária uma permissão explícita. Uma negação ou “nem permissão nem negação” resulta em uma negação. Veja a seguir um exemplo de uma política de recursos que pode ser usada com os grupos de usuários do Amazon Cognito. ![\[Fluxo de autorização de uma política de recursos e um autorizador do Amazon Cognito.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/apigateway-auth-cognito-resource-policy.png) Veja a seguir um exemplo de uma política de recursos que permite chamadas somente de IPs de origem especificados, pressupondo que o token de autenticação do Amazon Cognito contém uma permissão. Consulte mais informações em [Tabela B](#apigateway-resource-policies-iam-policies-interaction). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/", "Condition": { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ ## Tabelas de resultados de avaliação de política A Tabela A lista o comportamento resultante quando o acesso a uma API do API Gateway é controlado por uma política do IAM ou um autorizador do Lambda e por uma política de recursos do API Gateway, ambos na mesma Conta da AWS. | **Política do IAM (ou autorizador do Lambda)** | **Política de recursos do API Gateway** | **Comportamento resultante** | | --- | --- | --- | | Permitir | Permitir | Permitir | | Permitir | Nem permitir ou negar | Permitir | | Permitir | Deny | Negação explícita | | Nem permitir ou negar | Permitir | Permitir | | Nem permitir ou negar | Nem permitir ou negar | Negação implícita | | Nem permitir ou negar | Deny | Negação explícita | | Deny | Permitir | Negação explícita | | Deny | Nem permitir ou negar | Negação explícita | | Deny | Deny | Negação explícita | A Tabela B lista o comportamento resultante quando o acesso a uma API do API Gateway é controlado por uma política do IAM ou um autorizador de grupos de usuários do Amazon Cognito e por uma política de recursos do API Gateway, os quais estão em Contas da AWS diferentes. Se uma delas for silenciosa (nem permissão nem negação), o acesso entre contas é negado. Isso ocorre porque o acesso entre contas requer que tanto a política de recursos quanto a política do IAM, ou o autorizador de grupos de usuários do Amazon Cognito, conceda acesso explicitamente. | **Política do IAM (ou autorizador de grupos de usuários do Amazon Cognito)** | **Política de recursos do API Gateway** | **Comportamento resultante** | | --- | --- | --- | | Permitir | Permitir | Permitir | | Permitir | Nem permitir ou negar | Negação implícita | | Permitir | Deny | Negação explícita | | Nem permitir ou negar | Permitir | Negação implícita | | Nem permitir ou negar | Nem permitir ou negar | Negação implícita | | Nem permitir ou negar | Deny | Negação explícita | | Deny | Permitir | Negação explícita | | Deny | Nem permitir ou negar | Negação explícita | | Deny | Deny | Negação explícita | # Exemplos de política de recursos do API Gateway Esta página apresenta alguns exemplos de casos de uso típicos de políticas de recursos do API Gateway. Os exemplos de política a seguir usam uma sintaxe simplificada para especificar o recurso da API. Essa sintaxe simplificada é uma forma abreviada de como você pode se referir a um recurso de API, em vez de especificar o nome de recurso da Amazon (ARN) completo. O API Gateway converte a sintaxe abreviada para o ARN completo quando você salva a política. Por exemplo, você pode especificar o recurso `execute-api:/stage-name/GET/pets` em uma política de recursos. O API Gateway converte o recurso para `arn:aws:execute-api:us-east-2:123456789012:aabbccddee/stage-name/GET/pets` quando você salva a política de recursos. O API Gateway cria o ARN completo usando a região atual, o ID da conta da AWS e o ID da API REST à qual a política de recursos está associada. É possível usar `execute-api:/*` para representar todos os estágios, métodos e caminhos na API atual. Para obter informações sobre a linguagem de políticas de acesso, consulte [Visão geral da linguagem de políticas de acesso para o Amazon API Gateway](apigateway-control-access-policy-language-overview.md). **Topics** + [Exemplo: permitir que funções em outra conta da AWS usem uma API](#apigateway-resource-policies-cross-account-example) + [Exemplo: negar tráfego da API com base no intervalo ou endereço IP de origem](#apigateway-resource-policies-source-ip-address-example) + [Exemplo: negar tráfego de API com base no endereço IP ou intervalo de origem ao usar uma API privada](#apigateway-resource-policies-source-ip-address-vpc-example) + [Exemplo: permitir tráfego da API privada com base na VPC ou no VPC endpoint de origem](#apigateway-resource-policies-source-vpc-example) ## Exemplo: permitir que funções em outra conta da AWS usem uma API O exemplo de política de recursos a seguir concede acesso à API em uma conta da AWS a dois perfis em outra conta da AWS por meio dos protocolos [Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) (SigV4) ou [Signature Version 4a](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works) (SigV4a). Especificamente, a função de desenvolvedor e de administrador da conta da AWS identificada pelo `account-id-2` recebem a ação `execute-api:Invoke` para executar a ação `GET` no recurso `pets` (API) em sua conta da AWS. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:role/developer", "arn:aws:iam::111122223333:role/Admin" ] }, "Action": "execute-api:Invoke", "Resource": [ "execute-api:/stage/GET/pets" ] } ] } ``` ------ ## Exemplo: negar tráfego da API com base no intervalo ou endereço IP de origem O exemplo de política de recursos a seguir nega (bloqueia) o tráfego de entrada para uma API de dois blocos de endereços IP de origem especificados. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ Se você usa políticas de usuário do IAM ou políticas de recursos do API Gateway para controlar o acesso ao API Gateway ou a qualquer API do API Gateway, confirme se suas políticas foram atualizadas para incluir intervalos de endereços IPv6. Políticas que não são atualizadas para lidar com endereços IPv6 podem afetar o acesso do cliente ao API Gateway quando eles começarem a usar o endpoint de pilha dupla. Para obter mais informações, consulte [Como usar endereços do IPv6 em políticas do IAM](api-ref.md#api-reference-service-endpoints-dualstack-iam). ## Exemplo: negar tráfego de API com base no endereço IP ou intervalo de origem ao usar uma API privada O seguinte exemplo de política de recursos nega (bloqueia) o tráfego de entrada para uma API privada de dois blocos de endereços IP de origem especificados. Ao usar APIs privadas, o VPC endpoint de `execute-api` regrava o endereço IP de origem. A condição `aws:VpcSourceIp` filtra a solicitação em relação ao endereço IP do solicitante original. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "IpAddress": { "aws:VpcSourceIp": ["192.0.2.0/24", "198.51.100.0/24"] } } } ] } ``` ------ ## Exemplo: permitir tráfego da API privada com base na VPC ou no VPC endpoint de origem O exemplo das políticas de recursos a seguir permite o tráfego de entrada para uma API privada apenas proveniente de uma nuvem privada virtual (VPC) ou um VPC endpoint específicos. Este exemplo de política de recurso especifica uma VPC de origem: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpc": "vpc-1a2b3c4d" } } } ] } ``` ------ Este exemplo de política de recurso especifica um VPC endpoint de origem: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-1a2b3c4d" } } } ] } ``` ------ # Criar e anexar uma política de recursos do API Gateway a uma API Para permitir que um usuário acesse sua API chamando o serviço de execução de API, você precisa criar uma política de recursos do API Gateway e anexar essa política à API. Ao anexar uma política à API, ela aplica as permissões da política aos métodos na API. Se você atualizar a política de recursos, será necessário implantar a API. **Topics** + [Pré-requisitos](#apigateway-resource-policies-prerequisites) + [Anexar uma política de recursos a uma API do API Gateway](#apigateway-resource-policies-create-attach-procedure) + [Solução de problemas na política de recursos](#apigateway-resource-policies-troubleshoot) ## Pré-requisitos Para atualizar uma política de recursos do API Gateway, você precisará ter as permissões `apigateway:UpdateRestApiPolicy` e `apigateway:PATCH`. Para uma API regional ou otimizada para bordas, é possível anexar a política de recursos à API ao criá-la ou depois de implantá-la. Para uma API privada, não é possível implantar a API sem uma política de recursos. Para obter mais informações, consulte [APIs REST privadas no API Gateway](apigateway-private-apis.md). ## Anexar uma política de recursos a uma API do API Gateway O procedimento a seguir mostra como anexar uma política de recursos a uma API do API Gateway. ------ #### [ Console de gerenciamento da AWS ] **Como anexar uma política de recursos a uma API 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. Escolha uma API REST. 1. No painel de navegação principal, escolha **Política de recursos**. 1. Escolha **Criar política**. 1. (Opcional) Escolha **Selecionar um modelo** para gerar um exemplo de política. Nas políticas de exemplo, os espaços reservados são colocados entre chaves duplas (`"{{placeholder}}"`). Substitua cada um dos espaços reservados, incluindo as chaves, pelas informações necessárias. 1. Se você não usar um dos exemplos do modelo, insira a política de recurso. 1. Escolha **Salvar alterações**. Se a API tiver sido implantada anteriormente no console do API Gateway, será necessário reimplantá-la para que a política de recursos entre em vigor. ------ #### [ AWS CLI ] Para criar uma API por meio da AWS CLI e anexar uma política de recursos a ela, use o comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo: ``` aws apigateway create-rest-api \ --name "api-name" \ --policy "{\"jsonEscapedPolicyDocument\"}" ``` Para anexar uma política de recursos a uma API existente por meio da AWS CLI, use o comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo: ``` aws apigateway update-rest-api \ --rest-api-id api-id \ --patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"' ``` Você também pode anexar sua política de recursos como um arquivo `policy.json` separado e incluí-la no comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html). O comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo cria uma API com uma politica de recurso: ``` aws apigateway create-rest-api \ --name "api-name" \ --policy file://policy.json ``` `policy.json` é uma política de recursos do API Gateway, como [Exemplo: negar tráfego da API com base no intervalo ou endereço IP de origem](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example). ------ #### [ AWS CloudFormation ] Você pode usar CloudFormation para criar uma API com uma política de recursos. O seguinte exemplo cria uma API REST com o exemplo de política de recursos, [Exemplo: negar tráfego da API com base no intervalo ou endereço IP de origem](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example). ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: testapi Policy: Statement: - Action: 'execute-api:Invoke' Effect: Allow Principal: '*' Resource: 'execute-api:/*' - Action: 'execute-api:Invoke' Effect: Deny Principal: '*' Resource: 'execute-api:/*' Condition: IpAddress: 'aws:SourceIp': ["192.0.2.0/24", "198.51.100.0/24" ] Version: 2012-10-17 Resource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'helloworld' MethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref Resource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: MOCK RequestTemplates: application/json: '{"statusCode": 200}' IntegrationResponses: - StatusCode: 200 ResponseTemplates: application/json: '{}' MethodResponses: - StatusCode: 200 ResponseModels: application/json: 'Empty' ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - MethodGet Properties: RestApiId: !Ref Api StageName: test ``` ------ ## Solução de problemas na política de recursos As diretrizes de solução de problemas a seguir podem ajudar a resolver problemas em sua política de recursos. ### Minha API retorna \$1"Message":"Usuário: anônimo não tem autorização para executar: execute-api:Invoke no recurso: arn:aws:execute-api:us-east-1:\$1\$1\$1\$1\$1\$1\$1\$1/\$1\$1\$1\$1/\$1\$1\$1\$1/"\$1 Em sua política de recursos, se você definir a entidade principal como uma entidade principal da AWS, como a seguinte: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111111111111:role/developer", "arn:aws:iam::111111111111:role/Admin" ] }, "Action": "execute-api:Invoke", "Resource": [ "execute-api:/stage/GET/pets" ] } ] } ``` ------ Você deverá usar a autorização `AWS_IAM` para todos os métodos em sua API, caso contrário, a API retornará a mensagem de erro anterior. Para obter mais instruções sobre como ativar a autorização `AWS_IAM` para um método, consulte [Métodos para APIs REST no API Gateway](how-to-method-settings.md). ### Não consigo atualizar minha política de recursos Se você atualizar a política de recursos depois que a API for criada, será necessário implantar a API para propagar as alterações após a alteração da política. Atualizar ou salvar a política não altera o comportamento do tempo de execução da API. Para mais informações sobre como implantar sua API, consulte [Implantar APIs REST no API Gateway](how-to-deploy-api.md). ### Minha política de recursos retorna o seguinte erro: Documento de política inválido. Verifique a sintaxe da política e se as entidades principais são válidas. Para solucionar esse erro, primeiro recomendamos que você verifique a sintaxe da política. Para obter mais informações, consulte [Visão geral da linguagem de políticas de acesso para o Amazon API Gateway](apigateway-control-access-policy-language-overview.md). Também recomendamos que você verifique se todas as entidades principais especificadas são válidas e não foram excluídas. Além disso, se a API estiver em uma [região opcional](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html?icmpid=docs_homepage_addtlrcs#optinregion), verifique se todas as contas na política de recursos têm a região habilitada. # AWSAs chaves condições da que podem ser usadas nas políticas de recursos do API Gateway A tabela a seguir contém as chaves de condição da AWS que podem ser usadas nas políticas de recursos de APIs no API Gateway para cada tipo de autorização. Para obter mais informações sobre chaves de condição da AWS, consulte [Chaves de contexto de condição global da AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html). | **Chaves de condição** | **Critérios** | **Precisa de `AuthN`?** | **Tipo de autorização** | | --- | --- | --- | --- | | aws:CurrentTime | Nenhum | Não | Tudo | | aws:EpochTime | Nenhum | Não | Tudo | | aws:TokenIssueTime | A chave está presente somente em solicitações assinadas com credenciais de segurança temporárias. | Sim | IAM | | aws:MultiFactorAuthPresent | A chave está presente somente em solicitações assinadas com credenciais de segurança temporárias. | Sim | IAM | | aws:MultiFactorAuthAge | A chave estará presente somente se o MFA estiver presente nas solicitações. | Sim | IAM | | aws:PrincipalAccount | Nenhum | Sim | IAM | | aws:PrincipalArn | Nenhum | Sim | IAM | | aws:PrincipalOrgID | Essa chave será incluída no contexto da solicitação somente se o principal for membro de uma organização. | Sim | IAM | | aws:PrincipalOrgPaths | Essa chave será incluída no contexto da solicitação somente se o principal for membro de uma organização. | Sim | IAM | | aws:PrincipalTag | Essa chave será incluída no contexto da solicitação se o principal estiver usando um usuário do IAM com tags anexadas. Ela será incluída para um principal usando uma função do IAM com tags anexadas ou tags de sessão. | Sim | IAM | | aws:PrincipalType | Nenhum | Sim | IAM | | aws:Referer | A chave estará presente somente se o valor for fornecido pelo autor da chamada no cabeçalho HTTP. | Não | Tudo | | aws:SecureTransport | Nenhum | Não | Tudo | | aws:SourceArn | Nenhum | Não | Tudo | | aws:SourceIp | Nenhum | Não | Tudo | | aws:SourceVpc | Essa chave só pode ser usada para APIs privadas. | Não | Tudo | | aws:SourceVpce | Essa chave só pode ser usada para APIs privadas. | Não | Tudo | | aws:VpcSourceIp | Essa chave só pode ser usada para APIs privadas. | Não | Tudo | | aws:UserAgent | A chave estará presente somente se o valor for fornecido pelo autor da chamada no cabeçalho HTTP. | Não | Tudo | | aws:userid | Nenhum | Sim | IAM | | aws:username | Nenhum | Sim | IAM | # Controlar o acesso a uma API REST com permissões do IAM O acesso à sua API do Amazon API Gateway com [permissões do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html) é controlado pelo controle do acesso aos dois processos de componente do API Gateway a seguir: + Para criar, implantar e gerenciar uma API no API Gateway, você deve conceder as permissões de desenvolvedor de APIs para realizar as ações necessárias com suporte pelo componente de gerenciamento de APIs do API Gateway. + Para chamar uma API implantada ou atualizar o armazenamento em cache de APIs, você deve conceder ao autor da chamada da API as devidas permissões para realizar as ações necessárias do IAM com suporte pelo componente de execução de APIs do API Gateway. O controle de acesso para os dois processos envolve diferentes modelos de permissões, explicados em seguida. ## Modelo de permissões do API Gateway para criar e gerenciar uma API Para permitir que um desenvolvedor de API crie e gerencie uma API no API Gateway, você deve [criar políticas de permissões do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) que permitem a um desenvolvedor de API especificado criar, atualizar, implantar, exibir ou excluir [entidades de API](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) necessárias. Você anexa a política de permissões a um usuário, perfil ou grupo. Para conceder acesso, adicione as permissões aos seus usuários, grupos ou perfis: + Usuários e grupos no Centro de Identidade do AWS IAM: Crie um conjunto de permissões. Siga as instruções em [Criação de um conjunto de permissões](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) no *Guia do usuário do Centro de Identidade do AWS IAM*. + Usuários gerenciados no IAM com provedor de identidades: Crie um perfil para a federação de identidades. Siga as instruções em [Criando um perfil para um provedor de identidades de terceiros (federação)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) no *Guia do Usuário do IAM*. + Usuários do IAM: + Crie um perfil que seu usuário possa assumir. Siga as instruções em [Criação de um perfil para um usuário do IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) no *Guia do usuário do IAM*. + (Não recomendado) Vincule uma política diretamente a um usuário ou adicione um usuário a um grupo de usuários. Siga as instruções em [Adição de permissões a um usuário (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) no *Guia do usuário do IAM*. Para obter mais informações sobre como usar esse modelo de permissões, consulte [Políticas baseadas em identidade do API Gateway](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies). ## Modelo de permissões do API Gateway para invocar uma API Para permitir que um autor da chamada de API invoque a API ou atualize seu armazenamento em cache, é necessário criar políticas do IAM que permitam que um autor da chamada de API específico invoque o método de API para o qual a autenticação de usuários está ativada. O desenvolvedor de APIs define a propriedade `authorizationType` do método como `AWS_IAM` para exigir que o autor da chamada envie as credenciais do usuário do IAM a serem autenticadas. O API Gateway é compatível com o Signature Version 4a (SigV4a) e Signature Version 4 (SigV4) para autenticar as credenciais do usuário. Para ter mais informações, consulte [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Depois, é possível anexar a política a um usuário, grupo ou perfil. Nesta instrução de política de permissões do IAM, o elemento `Resource` do IAM contém uma lista de métodos de API implantados identificados por verbos HTTP especificados e por [caminhos de recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) do API Gateway. O elemento `Action` do IAM contém as ações necessárias de execução de API do API Gateway. Essas ações incluem `execute-api:Invoke` ou `execute-api:InvalidateCache`, em que `execute-api` designa o componente de execução de API subjacente do API Gateway. Para obter mais informações sobre como usar esse modelo de permissões, consulte [Controlar o acesso para chamar uma API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). Quando uma API é integrada a um serviço da AWS (por exemplo, AWS Lambda) no backend, o API Gateway também deve ter permissões para acessar recursos integrados da AWS (por exemplo, invocar uma função do Lambda) em nome do autor da chamada da API. Para conceder essas permissões, crie uma função do IAM do tipo **serviço da AWS para API Gateway**. Quando você cria essa função no console de gerenciamento do IAM, essa função resultante contém a seguinte política de confiança do IAM que declara o API Gateway como uma entidade confiável com permissão para assumir a função: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ Se você criar a função do IAM chamando o comando [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) da CLI ou um método de SDK correspondente, forneça a política de confiança acima como o parâmetro de entrada de `assume-role-policy-document`. Não tente criar essa política diretamente no console de gerenciamento do IAM ou chamando o comando da AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) ou um método correspondente do SDK. Para que o API Gateway chame o serviço da AWS integrado, você também deve anexar a essa função políticas de permissões do IAM apropriadas para chamar os serviços integrados da AWS. Por exemplo, para chamar uma função do Lambda, inclua a seguinte política de permissão do IAM na função do IAM: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] } ``` ------ Observe que o Lambda oferece suporte a políticas de acesso com base em recursos, que combina políticas de confiança com políticas de permissões. Ao integrar uma API com uma função do Lambda usando o console do API Gateway, você não é solicitado a definir essa função do IAM explicitamente, pois o console define as permissões com base em recurso na função do Lambda para você, com seu consentimento. **nota** Para implementar o controle de acesso em um serviço da AWS, você pode usar o modelo de permissões com base em autor da chamada, no qual uma política de permissões é diretamente anexada ao usuário ou grupo do autor da chamada, ou ao modelo de permissões com base em perfil, no qual uma política de permissões é anexada a um perfil do IAM que o API Gateway pode assumir. As políticas de permissões podem ser diferentes nos dois modelos. Por exemplo, a política baseada em agente de chamada bloqueia o acesso, enquanto a política baseada em função permite o acesso. Você pode utilizar isso para exigir que um usuário acesse um serviço da AWS somente por meio da API do API Gateway. # Controlar o acesso para chamar uma API Nesta seção, você saberá mais sobre o modelo de permissões para controlar o acesso à sua API usando as permissões do IAM. Quando a autorização do IAM está habilitada, os clientes precisam usar o Signature Version 4a (SigV4a) e o Signature Version 4 (SigV4) para assinar suas solicitações com credenciais da AWS. Para ter mais informações, consulte [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Nesta seção, mostramos um modelo de declaração de política do IAM e a referência de declarações de política. A referência de declarações de política inclui os formatos dos campos `Action` e `Resource` relacionados ao serviço de execução da API. Use essas referências para criar sua declaração de política do IAM. Ao criar a declaração de política do IAM, talvez seja necessário pensar em como as políticas de recursos do API Gateway afetam o fluxo de trabalho de autorização. Para obter mais informações, consulte [Como as políticas de recursos do API Gateway afetam o fluxo de trabalho de autorização](apigateway-authorization-flow.md). Para APIs privadas, é necessário usar uma combinação de uma política de recursos do API Gateway e de uma política do VPC endpoint. Para obter mais informações, consulte os tópicos a seguir: + [Controlar o acesso a uma API REST com políticas de recursos do API Gateway](apigateway-resource-policies.md) + [Usar políticas de VPC endpoint para APIs privadas no API Gateway](apigateway-vpc-endpoint-policies.md) ## Controlar quem pode chamar um método de API do API Gateway com políticas do IAM Para controlar quem pode ou não pode chamar uma API implantada com permissões do IAM, crie um documento de política do IAM com as permissões necessárias. Um modelo para esse documento de política é mostrado da seguinte maneira. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Permission", "Action": [ "execute-api:Execution-operation" ], "Resource": [ "arn:aws:execute-api:region:123456789012:api-id/stage/METHOD_HTTP_VERB/Resource-path" ] } ] } ``` ------ Aqui, é necessário substituir `Permission` por `Allow` ou `Deny` dependendo se você deseja conceder ou revogar as permissões incluídas. É necessário substituir `Execution-operation` pelas operações com suporte pelo serviço de execução de API. `METHOD_HTTP_VERB` representa um verbo HTTP com suporte pelos recursos especificados. `Resource-path` é o espaço reservado para o caminho da URL de uma instância de `[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)` da API implantada que oferece suporte ao `METHOD_HTTP_VERB` mencionado. Para obter mais informações, consulte [Referência de instrução de políticas do IAM para executar a API no API Gateway](#api-gateway-calling-api-permissions). **nota** Para que as políticas do IAM sejam eficazes, você deve ter habilitado a autenticação do IAM em métodos de API, definindo `AWS_IAM` para a propriedade `[authorizationType](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)` do método. Se isso não for feito, esses métodos de API se tornarão acessíveis ao público. Por exemplo, para conceder a um usuário a permissão para visualizar uma lista de animais de estimação exposta por uma API especificada, mas negar a esse usuário a permissão para adicionar um animal de estimação à lista, você pode incluir a seguinte instrução na política do IAM: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets" ] }, { "Effect": "Deny", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/POST/pets" ] } ] } ``` ------ Para conceder a um usuário a permissão para visualizar um animal de estimação exposto por uma API que é configurada como `GET /pets/{petId}`, você pode incluir a seguinte instrução na política do IAM: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/*/GET/pets/a1b2" ] } ] } ``` ------ ## Referência de instrução de políticas do IAM para executar a API no API Gateway As informações a seguir descrevem o formato de Ação e Recurso das instruções de política do IAM de permissões de acesso para a execução de uma API. ### Formato de ação das permissões para executar a API no API Gateway A expressão `Action` de execução de API possui o seguinte formato geral: ``` execute-api:action ``` em que *action* é uma ação de execução de API disponível: + **\$1**, que representa todas as ações a seguir. + **Invocar**, usado para chamar uma API mediante a solicitação de um cliente. + **InvalidateCache**, usado para invalidar o cache de API mediante a solicitação de um cliente. ### Formato de recurso das permissões para executar a API no API Gateway A expressão `Resource` de execução de API possui o seguinte formato geral: ``` arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier ``` em que: + *region* é a região da AWS (como **us-east-1** ou **\$1** para todas as regiões da AWS) que corresponde à API implantada para o método. + *account-id* é o ID de 12 dígitos da conta da AWS do proprietário da API REST. + *api-id* é o identificador que o API Gateway atribuiu à API para o método. + *stage-name* é o nome do estágio associado ao método. + *HTTP-VERB* é o verbo HTTP do método. Pode ser um dos seguintes: GET, POST, PUT, DELETE, PATCH. + *resource-path-specifier* é o caminho para o método desejado. **nota** Se você especificar um curinga (`*`), a expressão `Resource` aplicará o curinga ao resto da expressão. Algumas expressões de recursos de exemplo incluem: + **arn:aws:execute-api:\$1:\$1:\$1** para qualquer caminho de recurso em qualquer estágio, para qualquer API em qualquer região da AWS. + **arn:aws:execute-api:us-east-1:\$1:\$1** para qualquer caminho de recurso em qualquer estágio, para qualquer API na região da AWS `us-east-1`. + **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1** para qualquer caminho de recurso em qualquer estágio, para a API com o identificador de *api-id* na região da AWS us-east-1. + **arn:aws:execute-api:us-east-1:\$1:*api-id*/`test`/\$1** para qualquer caminho de recurso no estágio de `test`, para a API com o identificador *api-id* na região us-east-1 da AWS. Para saber mais, consulte [Referência de nome de recurso da Amazon (ARN) do API Gateway](arn-format-reference.md). # Exemplos de políticas do IAM para permissões de execução de API Para o modelo de permissões e outras informações de segundo plano, consulte [Controlar o acesso para chamar uma API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). A instrução de política a seguir concede ao usuário permissão para chamar qualquer método POST ao longo do caminho de `mydemoresource`, no estágio de `test`, para a API com o identificador `a123456789`, supondo que a API correspondente tenha sido implantada na região da AWS us-east-1: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*" ] } ] } ``` ------ O exemplo de instrução de política a seguir concede ao usuário permissão para chamar qualquer método no caminho de recurso de `petstorewalkthrough/pets`, em qualquer estágio, para a API com o identificador de `a123456789`, em qualquer região da AWS em que a API correspondente tenha sido implantada: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets" ] } ] } ``` ------ # Usar políticas de VPC endpoint para APIs privadas no API Gateway Para aumentar a segurança de sua API privada, você pode criar uma política de endpoint da VPC. Uma política de endpoint da VPC é uma política de recursos do IAM que você anexa a um endpoint da VPC. Para obter mais informações, consulte [Controlar o acesso a serviços com endpoints da VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html). Talvez você queira criar uma política de endpoint da VPC para realizar as tarefas a seguir. + Permitir que somente determinadas organizações ou recursos acessem seu endpoint da VPC e invoquem sua API. + Usar uma única política e evitar políticas baseadas em sessão ou perfil para controlar o tráfego para sua API. + Restringir o perímetro de segurança de sua aplicação ao migrar do ambiente on-premises para a AWS. ## Política do endpoint da VPC Veja a seguir as considerações para a política de endpoint da VPC. + A identidade do invocador é avaliada com base no valor do cabeçalho `Authorization`. A política de endpoint da VPC é avaliada primeiro e, em seguida, o Gateway da API avalia a solicitação com base no tipo de autorização configurada na solicitação do método. A tabela a seguir mostra como a política de endpoint da VPC é avaliada com base no conteúdo do valor do cabeçalho `Authorization`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-vpc-endpoint-policies.html) + Se seu controle de acesso depender do uso de um token de portador, como um autorizador Lambda ou Amazon Cognito, você pode controlar seu perímetro de segurança usando [propriedades do recurso](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties). + Se seus controles de autorização usarem a autorização do IAM, você poderá controlar seu perímetro de segurança usando [propriedades do recurso](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties) e [propriedades da entidade principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-principal). + As políticas de VPC endpoint podem ser usadas com políticas de recurso do API Gateway. A política de recursos do API Gateway é usada para especificar quais entidades principais podem acessar a API. A política de endpoint especifica quem pode acessar a VPC e quais APIs podem ser chamadas pelo endpoint da VPC. Sua API privada precisa de uma política de recursos, mas você não precisa criar uma política de endpoint da VPC personalizada. ## Exemplos de política de endpoint da VPC É possível criar políticas para endpoints da Amazon Virtual Private Cloud para o Amazon API Gateway nas quais você pode especificar o indicado a seguir. + A entidade principal que pode executar ações. + As ações que podem ser executadas. + Os recursos que podem ter ações executadas neles. Isso pode depender do conteúdo do cabeçalho de autorização. Para obter mais informações, consulte [Política do endpoint da VPC](#apigateway-vpc-endpoint-policies-considerations). Para exemplos adicionais de políticas, consulte [Exemplos de políticas de perímetro de dados](https://github.com/aws-samples/data-perimeter-policy-examples) no site do GitHub. Para anexar a política ao VPC endpoint, será necessário usar o console da VPC. Para obter mais informações, consulte [Controlar o acesso a serviços com endpoints da VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html). ## Exemplo 1: Política de VPC endpoint que concede acesso a duas APIs O exemplo de política a seguir concede acesso somente a duas APIs específicas por meio do VPC endpoint ao qual a política está anexada. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": "*", "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*", "arn:aws:execute-api:us-east-1:123412341234:aaaaa11111/*" ] } ] } ``` ------ ## Exemplo 2: Política de VPC endpoint que concede acesso a métodos GET O exemplo de política a seguir concede aos usuários acesso a métodos `GET` para uma API específica por meio do VPC endpoint ao qual a política está anexada. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": "*", "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/stageName/GET/*" ] } ] } ``` ------ ## Exemplo 3: Política de VPC endpoint que concede acesso a uma API específica para um usuário específico O exemplo de política a seguir concede acesso a uma API específica para um usuário específico por meio do VPC endpoint ao qual a política está anexada. Neste caso, como a política restringe o acesso a entidades principais específicas do IAM, você precisa definir o método `authorizationType` como `AWS_IAM` ou `NONE`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": { "AWS": [ "arn:aws:iam::123412341234:user/MyUser" ] }, "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*" ] } ] } ``` ------ ## Exemplo 4: política de endpoint da VPC que concede aos usuários acesso a um nome de domínio personalizado específico e a todas as APIs associadas ao domínio O exemplo de política a seguir concede aos usuários acesso a um nome de domínio personalizado específico para APIs privadas por meio do endpoint da VPC ao qual a política está anexada. Com essa política, desde que o usuário tenha criado uma associação de acesso ao nome de domínio entre o endpoint da VPC e o nome de domínio personalizado e tenha permissão para invocar o nome de domínio personalizado e quaisquer APIs privadas associadas ao nome de domínio personalizado, ele poderá invocar quaisquer APIs associadas a esse nome de domínio personalizado. Para obter mais informações, consulte [Nomes de domínio personalizados para APIs privadas no API Gateway](apigateway-private-custom-domains.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "*" ], "Condition": { "ArnEquals": { "execute-api:viaDomainArn": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6", } } } ] } ``` ------ ## Exemplo 5: política de endpoint da VPC que concede ou nega acesso a APIs e recursos de domínio específicos O exemplo de política a seguir concede aos usuários acesso a APIs e recursos de domínio específicos. Com essa política, desde que o usuário tenha criado uma associação de acesso ao nome de domínio entre o endpoint da VPC e o nome de domínio personalizado e tenha permissão para invocar o nome de domínio personalizado e quaisquer APIs privadas associadas ao nome de domínio personalizado, ele poderá invocar APIs privadas e recursos de domínio permitidos. Para obter mais informações, consulte [Nomes de domínio personalizados para APIs privadas no API Gateway](apigateway-private-custom-domains.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6", "arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/*" ] }, { "Effect": "Deny", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/admin/*", "arn:aws:execute-api:us-west-2:111122223333:bcd123455/*" ] } ] } ``` ------ ## Exemplo 6: política de endpoint da VPC concedendo ou negando acesso por entidades principais e recursos pertencentes a uma organização O exemplo de política a seguir concede acesso a entidades principais e recursos que pertencem a uma organização. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Condition": { "StringEquals": { "aws:ResourceOrgID": "o-abcd1234", "aws:PrincipalOrgID": "o-abcd1234" } }, "Action": "*", "Resource": "*", "Effect": "Allow", "Principal": { "AWS": "*" }, "Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources" } ] } ``` ------ # Usar tags para controlar o acesso a APIs REST no API Gateway A permissão para acessar APIs REST pode ser ajustada usando o controle de acesso baseado em atributos nas políticas do IAM. Para ter mais informações, consulte [Usar tags para controlar o acesso aos recursos da API REST do API Gateway](apigateway-tagging-iam-policy.md). # Usar os autorizadores do API Gateway Lambda Use um *autorizador do Lambda* (anteriormente conhecido como *autorizador personalizado*) para controlar o acesso à API. Quando um cliente solicita o método da API, o API Gateway chama o autorizador do Lambda. O autorizador do Lambda usa a identidade do chamador como entrada e retorna uma política do IAM como saída. Use um autorizador do Lambda para implementar um esquema de autorização personalizado. O esquema pode usar parâmetros de solicitação para determinar a identidade do chamador ou usar uma estratégia de autenticação de token de portador, como OAuth ou SAML. Crie um autorizador do Lambda no console da API REST do API Gateway, usando a AWS CLI ou um SDK da AWS. ## Fluxo de trabalho de autorização do autorizador do Lambda O diagrama a seguir mostra o fluxo de trabalho de autorização referente a um autorizador do Lambda. ![\[Fluxo de trabalho de autorização do Lambda do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/custom-auth-workflow.png) **Fluxo de trabalho de autorização do Lambda do API Gateway** 1. O cliente chama um método em uma API do API Gateway, passando um token de portador ou parâmetros de solicitação. 1. O API Gateway confere se a solicitação do método está configurada com um autorizador do Lambda. Se estiver, o API Gateway chama a função do Lambda. 1. A função do Lambda autentica o chamador. A função pode fazer a autenticação das seguintes maneiras: + Chamando um provedor OAuth para receber um token de acesso OAuth. + Chamando um provedor SAML para receber uma declaração SAML. + Gerando uma política do IAM com base nos valores do parâmetro de solicitação. + Recuperando as credenciais de um banco de dados. 1. A função do Lambda retorna uma política do IAM e um identificador de entidade principal. Se a função do Lambda não retornar essas informações, a chamada falhará. 1. O API Gateway avalia a política do IAM. + Se o acesso for negado, o API Gateway retornará um código de status HTTP, por exemplo, `403 ACCESS_DENIED`. + Se o acesso for permitido, o API Gateway invocará o método. Se você habilitar o armazenamento em cache da autorização, o API Gateway armazenará a política em cache para que a função do autorizador do Lamba não seja invocada novamente. Sua política deve ser aplicável a todos os recursos e métodos em sua API. É possível personalizar as respostas `403 ACCESS_DENIED` ou `401 UNAUTHORIZED` do gateway. Para saber mais, consulte [Respostas do gateway para APIs REST no API Gateway](api-gateway-gatewayResponse-definition.md). ## Como escolher um tipo de autorizador do Lambda Existem dois tipos de autorizadores do Lambda: **Solicitar um autorizador do Lambda baseado em parâmetros (autorizador `REQUEST`)** Um autorizador `REQUEST` recebe a identidade do chamador em uma combinação de cabeçalhos, parâmetros de strings de consulta, [`stageVariables`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) e variáveis [`$context`](api-gateway-mapping-template-reference.md#context-variable-reference). É possível usar um autorizador `REQUEST` para criar políticas refinadas com base nas informações de várias fontes de identidade, como as variáveis de contexto `$context.path` e `$context.httpMethod`. Se você ativar o armazenamento em cache de autorização para um autorizador `REQUEST`, o API Gateway verificará se todas as fontes de identidade especificadas estão presentes na solicitação. Se uma fonte de identidade especificada estiver ausente, for nula ou estiver vazia, o API Gateway retornará uma resposta HTTP `401 Unauthorized` sem chamar a função do autorizador do Lambda. Quando há várias fontes de identidade definidas, todas são usadas para derivar a chave de cache do autorizador, preservando a ordem. É possível definir uma chave de cache refinada usando várias fontes de identidade. Se você alterar qualquer parte da chave do cache e reimplantar a API, o autorizador descartará o documento da política em cache e gerará outro. Se você desativar o armazenamento em cache de autorização para um autorizador `REQUEST`, o API Gateway passará a solicitação diretamente à função do Lambda. **Autorizador do Lambda com base em token (autorizador `TOKEN`)** Um autorizador `TOKEN` recebe a identidade do chamador em um token de portador, como um JSON Web Token (JWT) ou um token OAuth. Se você ativar o armazenamento em cache de autorização para um autorizador `TOKEN`, o nome do cabeçalho especificado na origem do token será a chave do cache. Além disso, é possível usar a validação de token para inserir uma instrução RegEx. O API Gateway executa a validação inicial do token de entrada em relação a essa expressão e invoca a função do autorizador do Lambda mediante a validação com êxito. Isso ajuda a reduzir as chamadas para a API. A propriedade `IdentityValidationExpression` é compatível somente com autorizadores `TOKEN`. Para obter mais informações, consulte [Objeto x-amazon-apigateway-authorizer](api-gateway-swagger-extensions-authorizer.md). **nota** Recomendamos que você use um autorizador `REQUEST` para controlar o acesso à API. É possível controlar o acesso à API com base em várias fontes de identidade ao usar um autorizador `REQUEST`, em comparação com uma única fonte de identidade ao usar um autorizador `TOKEN`. Além disso, você pode separar as chaves de cache usando várias fontes de identidade para um autorizador `REQUEST`. ## Exemplo de função do Lambda do autorizador `REQUEST` O código de exemplo a seguir criará uma função do autorizador do Lambda que permite uma solicitação se o cabeçalho `HeaderAuth1`, o parâmetro de consulta `QueryString1` e a variável de estágio de `StageVar1` fornecidos pelo cliente corresponderem aos valores especificados de `headerValue1`, `queryValue1` e `stageValue1`, respectivamente. ------ #### [ Node.js ] ``` // A simple request-based authorizer example to demonstrate how to use request // parameters to allow or deny a request. In this example, a request is // authorized if the client-supplied HeaderAuth1 header, QueryString1 // query parameter, and stage variable of StageVar1 all match // specified values of 'headerValue1', 'queryValue1', and 'stageValue1', // respectively. export const handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); // Retrieve request parameters from the Lambda function input: var headers = event.headers; var queryStringParameters = event.queryStringParameters; var pathParameters = event.pathParameters; var stageVariables = event.stageVariables; // Parse the input for the parameter values var tmp = event.methodArn.split(':'); var apiGatewayArnTmp = tmp[5].split('/'); var awsAccountId = tmp[4]; var region = tmp[3]; var restApiId = apiGatewayArnTmp[0]; var stage = apiGatewayArnTmp[1]; var method = apiGatewayArnTmp[2]; var resource = '/'; // root resource if (apiGatewayArnTmp[3]) { resource += apiGatewayArnTmp[3]; } // Perform authorization to return the Allow policy for correct parameters and // the 'Unauthorized' error, otherwise. if (headers.HeaderAuth1 === "headerValue1" && queryStringParameters.QueryString1 === "queryValue1" && stageVariables.StageVar1 === "stageValue1") { callback(null, generateAllow('me', event.methodArn)); } else { callback(null, generateDeny('me', event.methodArn)); } } // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { // Required output: var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; // default version policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; // default action statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } var generateAllow = function(principalId, resource) { return generatePolicy(principalId, 'Allow', resource); } var generateDeny = function(principalId, resource) { return generatePolicy(principalId, 'Deny', resource); } ``` ------ #### [ Python ] ``` # A simple request-based authorizer example to demonstrate how to use request # parameters to allow or deny a request. In this example, a request is # authorized if the client-supplied headerauth1 header, QueryString1 # query parameter, and stage variable of StageVar1 all match # specified values of 'headerValue1', 'queryValue1', and 'stageValue1', # respectively. def lambda_handler(event, context): print(event) # Retrieve request parameters from the Lambda function input: headers = event['headers'] queryStringParameters = event['queryStringParameters'] pathParameters = event['pathParameters'] stageVariables = event['stageVariables'] # Parse the input for the parameter values tmp = event['methodArn'].split(':') apiGatewayArnTmp = tmp[5].split('/') awsAccountId = tmp[4] region = tmp[3] restApiId = apiGatewayArnTmp[0] stage = apiGatewayArnTmp[1] method = apiGatewayArnTmp[2] resource = '/' if (apiGatewayArnTmp[3]): resource += apiGatewayArnTmp[3] # Perform authorization to return the Allow policy for correct parameters # and the 'Unauthorized' error, otherwise. if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters['QueryString1'] == "queryValue1" and stageVariables['StageVar1'] == "stageValue1"): response = generateAllow('me', event['methodArn']) print('authorized') return response else: print('unauthorized') response = generateDeny('me', event['methodArn']) return response # Help function to generate IAM policy def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } return authResponse def generateAllow(principalId, resource): return generatePolicy(principalId, 'Allow', resource) def generateDeny(principalId, resource): return generatePolicy(principalId, 'Deny', resource) ``` ------ Neste exemplo, a função do autorizador do Lambda verifica os parâmetros de entrada e age da seguinte forma: + Se todos os valores de parâmetro necessários corresponderem aos valores esperados, a função do autorizador retornará uma resposta HTTP `200 OK` e uma política do IAM que é semelhante ao seguinte, e a solicitação de método será bem-sucedida: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ + Caso contrário, a função do autorizador retornará uma resposta HTTP `401 Unauthorized` e ocorrerá uma falha na solicitação do método. Além de retornar uma política do IAM, a função de autorizador do Lambda também deve retornar o identificador principal do autor da chamada. Opcionalmente, ela pode retornar um objeto `context` com informações adicionais que podem ser passadas ao back-end de integração. Para obter mais informações, consulte [Saída de um autorizador do Lambda para o API Gateway](api-gateway-lambda-authorizer-output.md). No código de produção, talvez seja necessário autenticar o usuário antes de conceder a autorização. É possível adicionar a lógica de autenticação à função do Lambda chamando um provedor de autenticação conforme indicado na documentação desse provedor. ## Exemplo de função do Lambda do autorizador `TOKEN` O código de exemplo a seguir cria uma função do Lambda do autorizador `TOKEN` que permite que um chamador invoque um método caso o valor do token fornecido pelo cliente seja `allow`. O chamador não tem permissão para invocar a solicitação caso o valor do token seja `deny`. Se o valor do token for `unauthorized` ou uma string vazia, a função do autorizador retornará uma resposta `401 UNAUTHORIZED`. ------ #### [ Node.js ] ``` // A simple token-based authorizer example to demonstrate how to use an authorization token // to allow or deny a request. In this example, the caller named 'user' is allowed to invoke // a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke // the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty // string, the authorizer function returns an HTTP 401 status code. For any other token value, // the authorizer returns an HTTP 500 status code. // Note that token values are case-sensitive. export const handler = function(event, context, callback) { var token = event.authorizationToken; switch (token) { case 'allow': callback(null, generatePolicy('user', 'Allow', event.methodArn)); break; case 'deny': callback(null, generatePolicy('user', 'Deny', event.methodArn)); break; case 'unauthorized': callback("Unauthorized"); // Return a 401 Unauthorized response break; default: callback("Error: Invalid token"); // Return a 500 Invalid token response } }; // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } ``` ------ #### [ Python ] ``` # A simple token-based authorizer example to demonstrate how to use an authorization token # to allow or deny a request. In this example, the caller named 'user' is allowed to invoke # a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke # the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty # string, the authorizer function returns an HTTP 401 status code. For any other token value, # the authorizer returns an HTTP 500 status code. # Note that token values are case-sensitive. import json def lambda_handler(event, context): token = event['authorizationToken'] if token == 'allow': print('authorized') response = generatePolicy('user', 'Allow', event['methodArn']) elif token == 'deny': print('unauthorized') response = generatePolicy('user', 'Deny', event['methodArn']) elif token == 'unauthorized': print('unauthorized') raise Exception('Unauthorized') # Return a 401 Unauthorized response return 'unauthorized' try: return json.loads(response) except BaseException: print('unauthorized') return 'unauthorized' # Return a 500 error def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } authResponse_JSON = json.dumps(authResponse) return authResponse_JSON ``` ------ Neste exemplo, quando a API recebe uma solicitação de método, o API Gateway repassa o token de origem para essa função do autorizador do Lambda no atributo `event.authorizationToken`. A função do autorizador do Lambda lê o token e age da seguinte forma: + Se o valor do token for `allow`, a função do autorizador retornará uma resposta HTTP `200 OK` e uma política do IAM que é semelhante ao seguinte, e a solicitação de método será bem-sucedida: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ + Se o valor do token for `deny`, a função do autorizador retornará uma resposta HTTP `200 OK` e uma política do IAM `Deny` que é semelhante ao seguinte, e ocorrerá uma falha na solicitação de método: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ **nota** Fora do ambiente de teste, o API Gateway retorna uma resposta HTTP `403 Forbidden` e ocorre uma falha na solicitação do método. + Se o valor do token for `unauthorized`, a função do autorizador retornará uma resposta HTTP `401 Unauthorized`, e ocorrerá uma falha na chamada de método. + Se o valor do token for diferente, o cliente receberá uma resposta `500 Invalid token`, e ocorrerá uma falha na chamada de método. Além de retornar uma política do IAM, a função de autorizador do Lambda também deve retornar o identificador principal do autor da chamada. Opcionalmente, ela pode retornar um objeto `context` com informações adicionais que podem ser passadas ao back-end de integração. Para obter mais informações, consulte [Saída de um autorizador do Lambda para o API Gateway](api-gateway-lambda-authorizer-output.md). No código de produção, talvez seja necessário autenticar o usuário antes de conceder a autorização. É possível adicionar a lógica de autenticação à função do Lambda chamando um provedor de autenticação conforme indicado na documentação desse provedor. ## Exemplos adicionais de funções do autorizador do Lambda A lista a seguir mostra exemplos adicionais de funções do autorizador do Lambda. É possível criar uma função do Lambda na mesma conta em que você criou a API ou em uma conta diferente. No exemplo anterior de funções do Lambda, é possível usar a função integrada [AWSLambdaBasicExecutionRole](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html), já que essas funções não chamam outros serviços da AWS. Se a função do Lambda chamar outros serviços da AWS, será necessário atribuir um perfil de execução do IAM à função do Lambda. Para criar a função, siga as instruções na [Função de execução AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html). **Exemplos adicionais de funções do autorizador do Lambda** + Para ver um exemplo de aplicação, consulte [Open Banking Brasil: amostras de autorizações](https://github.com/aws-samples/openbanking-brazilian-auth-samples) no GitHub. + Para obter mais exemplos de funções do Lambda, consulte [ aws-apigateway-lambda-authorizer-blueprints](https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints) no GitHub. + É possível criar um autorizador do Lambda que autentica usuários usando grupos de usuários do Amazon Cognito e autoriza chamadores com base em um armazenamento de políticas usando o Verified Permissions. Para obter mais informações, consulte [Controlar o acesso com base nos atributos de uma identidade com o Verified Permissions](apigateway-lambda-authorizer-verified-permissions.md). + O console do Lambda fornece um esquema Python, que você pode usar ao selecionar **Use a blueprint (Usar um esquema)** e selecionar o esquema **api-gateway-authorizer-python**. # Configurar um autorizador do Lambda para o API Gateway Depois de criar uma função do Lambda, configure-a como um autorizador para a API. Em seguida, configure o método para invocar o autorizador do Lambda e determinar se um chamador pode invocar o método. É possível criar uma função do Lambda na mesma conta em que você criou a API ou em uma conta diferente. Você pode testar o autorizador do Lambda usando as ferramentas integradas no console do API Gateway ou usando o [Postman](https://www.postman.com/). Consulte instruções sobre como usar o Postman para testar a função do autorizador do Lambda em [Chamar uma API com um autorizador do Lambda do API Gateway](call-api-with-api-gateway-lambda-authorization.md). ## Configurar um autorizador do Lambda (console) O procedimento a seguir mostra como criar um autorizador do Lambda no console da API REST do API Gateway. Para saber mais sobre os diferentes tipos de autorizador do Lambda, consulte [Como escolher um tipo de autorizador do Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-choose). ------ #### [ REQUEST authorizer ] **Como configurar um autorizador `REQUEST` do Lambda** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API e selecione **Autorizadores**. 1. Selecione **Criar autorizador**. 1. Em **Nome do autorizador**, insira um nome para o autorizador. 1. Em **Tipo de autorizador**, selecione **Lambda**. 1. Em **Função do Lambda**, selecione a Região da AWS onde você criou a função do Lambda do autorizador e, depois, insira o nome da função. 1. Mantenha o campo **Função Lambda de invocação** em branco para permitir que o console da API REST do API Gateway defina uma política baseada em recursos. A política concede permissões ao API Gateway para invocar a função do autorizador do Lambda. Você também pode optar por inserir o nome de um perfil do IAM para permitir que o API Gateway invoque a função do autorizador do Lambda. Consulte um exemplo de função em [Criar uma função do IAM que pode ser assumida](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies). 1. Em **Carga de evento do Lambda**, escolha **Solicitar**. 1. Em **Tipo de origem de identidade**, selecione um tipo de parâmetro. Os tipos de parâmetros com suporte são `Header`, `Query string`, `Stage variable` e `Context`. Para adicionar mais origens de identidade, escolha **Adicionar parâmetro**. 1. Para armazenar em cache a política de autorização gerada pelo autorizador, mantenha **Armazenamento em cache de autorização** ativado. Quando o armazenamento de políticas em cache está habilitado, é possível modificar o valor de **TTL**. A definição de **TTL** como zero desabilita o armazenamento em cache de políticas. Se você habilitar o armazenamento em cache, o autorizador deverá retornar uma política que seja aplicável a todos os métodos em uma API. Para aplicar uma política específica do método, use as variáveis de contexto `$context.path` e `$context.httpMethod`. 1. Selecione **Criar autorizador**. ------ #### [ TOKEN authorizer ] **Como configurar um autorizador `TOKEN` do Lambda** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API e selecione **Autorizadores**. 1. Selecione **Criar autorizador**. 1. Em **Nome do autorizador**, insira um nome para o autorizador. 1. Em **Tipo de autorizador**, selecione **Lambda**. 1. Em **Função do Lambda**, selecione a Região da AWS onde você criou a função do Lambda do autorizador e, depois, insira o nome da função. 1. Mantenha o campo **Função Lambda de invocação** em branco para permitir que o console da API REST do API Gateway defina uma política baseada em recursos. A política concede permissões ao API Gateway para invocar a função do autorizador do Lambda. Você também pode optar por inserir o nome de um perfil do IAM para permitir que o API Gateway invoque a função do autorizador do Lambda. Consulte um exemplo de função em [Criar uma função do IAM que pode ser assumida](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies). 1. Em **Carga de evento do Lambda**, escolha **Token**. 1. Em **Origem do token**, insira o nome do cabeçalho que contém o token de autorização. O chamador deve incluir um cabeçalho desse nome para enviar o token de autorização ao autorizador do Lambda. 1. (Opcional) Em **Validação do token**, insira uma instrução RegEx. O API Gateway executa a validação inicial do token de entrada em relação a esta expressão e invoca o autorizador mediante a validação com êxito. 1. Para armazenar em cache a política de autorização gerada pelo autorizador, mantenha **Armazenamento em cache de autorização** ativado. Quando o armazenamento em cache de políticas está habilitado, o nome de cabeçalho especificado em **Origem do token** se torna a chave de cache. Quando o armazenamento de políticas em cache está habilitado, é possível modificar o valor de **TTL**. A definição de **TTL** como zero desabilita o armazenamento em cache de políticas. Se você habilitar o armazenamento em cache, o autorizador deverá retornar uma política que seja aplicável a todos os métodos em uma API. Para aplicar uma política específica do método, desative **Armazenamento em cache de autorização**. 1. Selecione **Criar autorizador**. ------ Depois de criar o autorizador do Lambda, é possível testá-lo. O procedimento a seguir mostra como testar o autorizador do Lambda. ------ #### [ REQUEST authorizer ] **Como testar um autorizador `REQUEST` do Lambda** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione o nome do autorizador. 1. Em **Testar autorizador**, insira um valor para a fonte de identidades. Se você estiver usando o [Exemplo de função do Lambda do autorizador `REQUEST`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-request-lambda-function-create), faça o seguinte: 1. Selecione **Cabeçalho** e insira **headerValue1**; depois, escolha **Adicionar parâmetro**. 1. Em **Tipo de origem de identidade**, selecione **String de consulta**, insira **queryValue1** e escolha **Adicionar parâmetro**. 1. Em **Tipo de origem de identidade**, selecione **Variável de estágio** e insira **stageValue1**. Você não pode modificar as variáveis de contexto para a invocação do teste, mas pode modificar o modelo de evento de teste do **Autorizador do API Gateway** para a função do Lambda. Em seguida, você pode testar a função de autorizador do Lambda com variáveis de contexto modificadas. Para saber mais, consulte [Testing Lambda functions in the console](https://docs.aws.amazon.com/lambda/latest/dg/testing-functions.html) no *Guia do desenvolvedor do AWS Lambda*. 1. Escolha **Testar autorizador**. ------ #### [ TOKEN authorizer ] **Como testar um autorizador `TOKEN` do Lambda** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione o nome do autorizador. 1. Em **Testar autorizador**, insira um valor para o token. Se você estiver usando o [Exemplo de função do Lambda do autorizador `TOKEN`](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create), faça o seguinte: 1. Em **authorizationToken**, insira **allow**. 1. Escolha **Testar autorizador**. Se o autorizador do Lambda negar com sucesso uma solicitação no ambiente de teste, o teste responderá com uma resposta HTTP `200 OK`. No entanto, fora do ambiente de teste, o API Gateway retorna uma resposta HTTP `403 Forbidden` e ocorre uma falha na solicitação do método. ------ ## Configurar um autorizador do Lambda (AWS CLI) O comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) mostra como criar um autorizador do Lambda usando a AWS CLI. ------ #### [ REQUEST authorizer ] O comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) indicado abaixo cria um autorizador `REQUEST` e usa o cabeçalho `Authorizer` e a variável de contexto `accountId` como fontes de identidade: ``` aws apigateway create-authorizer \ --rest-api-id 1234123412 \ --name 'First_Request_Custom_Authorizer' \ --type REQUEST \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \ --identity-source 'method.request.header.Authorization,context.accountId' \ --authorizer-result-ttl-in-seconds 300 ``` ------ #### [ TOKEN authorizer ] O comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) indicado abaixo cria um autorizador `TOKEN` e usa o cabeçalho `Authorization` como fonte de identidade: ``` aws apigateway create-authorizer \ --rest-api-id 1234123412 \ --name 'First_Token_Custom_Authorizer' \ --type TOKEN \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \ --identity-source 'method.request.header.Authorization' \ --authorizer-result-ttl-in-seconds 300 ``` ------ Depois de criar o autorizador do Lambda, é possível testá-lo. O comando [test-invoke-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-authorizer.html) indicado abaixo testa o autorizador do Lambda: ``` aws apigateway test-invoke-authorizer --rest-api-id 1234123412 \ --authorizer-id efg1234 \ --headers Authorization='Value' ``` ## Configurar um método para usar um autorizador do Lambda (console) Depois de configurar o autorizador do Lambda, anexe-o a um método para a API. Se seu autorizador usa o armazenamento em cache de autorização, atualize a política para controlar o acesso ao método adicional. **Para configurar um método de API para usar um autorizador do Lambda** 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. 1. Selecione **Recursos** e escolha um novo método ou um já existente. 1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, escolha **Editar**. 1. Em **Autorizador**, no menu suspenso, selecione o autorizador do Lambda que você acabou de criar. 1. (Opcional) Se você quiser passar o token de autorização para o back-end, escolha **Cabeçalhos de solicitação HTTP**. Escolha **Adicionar cabeçalho** e adicione o nome do cabeçalho de autorização. Em **Nome**, insira um nome de cabeçalho que corresponda ao nome de **Origem do token** especificado quando você criou o autorizador do Lambda para a API. Esta etapa não se aplica a autorizadores `REQUEST`. 1. Escolha **Salvar**. 1. Escolha **Deploy API (Implantar API)** para implantar a API em um estágio. Para um autorizador `REQUEST` que usa variáveis de estágio, você também deve definir as variáveis de estágio necessárias e especificar os respectivos valores enquanto estiver na página **Estágio**. ## Configurar um método para usar um autorizador do Lambda (AWS CLI) Depois de configurar o autorizador do Lambda, anexe-o a um método para a API. Você pode criar um método ou usar uma operação de patch para anexar um autorizador a um método existente. Se seu autorizador usa o armazenamento em cache de autorização, atualize a política para controlar o acesso ao método adicional. O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo cria um método que usa um autorizador do Lambda: ``` aws apigateway put-method --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --authorization-type CUSTOM \ --authorizer-id efg1234 ``` O comando [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) indicado abaixo atualiza um método existente para usar um autorizador do Lambda: ``` aws apigateway update-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --patch-operations op="replace",path="/authorizationType",value="CUSTOM" op="replace",path="/authorizerId",value="efg1234" ``` # Entrada para um autorizador do Lambda do API Gateway A seção a seguir explica o formato da entrada do API Gateway para um autorizador do Lambda. ## Formato de entrada do `TOKEN` Para um autorizador do Lambda (anteriormente conhecido como autorizador personalizado) do tipo `TOKEN`, você deve especificar um cabeçalho personalizado como **Token Source (Origem do token)** quando configurar o autorizador para sua API. O cliente da API deve repassar o token de autorização necessário nesse cabeçalho na solicitação de entrada. Ao receber a solicitação do método de entrada, o API Gateway extrai o token do cabeçalho personalizado. Ele passa o token como a propriedade `authorizationToken` do objeto `event` da função do Lambda, além do método ARN como a propriedade `methodArn`: ``` { "type":"TOKEN", "authorizationToken":"{caller-supplied-token}",     "methodArn":"arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]" } ``` Neste exemplo, a propriedade `type` especifica o tipo de autorizador, que é um autorizador `TOKEN`. O `{caller-supplied-token}` origina-se do cabeçalho de autorização em uma solicitação do cliente e pode ser qualquer valor de string. O `methodArn` é o ARN da solicitação de método de entrada e é preenchido pelo API Gateway de acordo com a configuração do autorizador do Lambda. ## Formato de entrada da `REQUEST` Para um autorizador do Lambda do tipo `REQUEST`, o API Gateway passa os parâmetros de solicitação para a função do Lambda do autorizador como parte do objeto `event`. Os parâmetros de solicitação incluem cabeçalhos, parâmetros de caminho, parâmetros de string de consulta, variáveis de estágio e algumas das variáveis de contexto de solicitação. O autor da chamada da API pode definir parâmetros de caminho, cabeçalhos e parâmetros de string de consulta. O desenvolvedor da API deve definir as variáveis de estágio durante a implantação da API e o API Gateway fornece o contexto de solicitação em tempo de execução. **nota** Os parâmetros de caminho podem ser passados como parâmetros da solicitação para a função do autorizador do Lambda, mas não podem ser usados como origens de identidade. O exemplo a seguir mostra uma entrada para um autorizador `REQUEST` de um método API (`GET /request`) com uma integração de proxy: ``` { "type": "REQUEST", "methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request", "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" } } ``` O `requestContext` é um mapa de pares de chave/valor e corresponde à variável [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference). Seu resultado é dependente da API. O API Gateway pode adicionar novas chaves ao mapa. Para obter mais informações sobre a entrada de função do Lambda na integração de proxy do Lambda, consulte [Formato de entrada de uma função do Lambda para integração de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). # Saída de um autorizador do Lambda para o API Gateway A saída da função de autorizador do Lambda é um objeto em forma de dicionário, que deve incluir o identificador principal (`principalId`) e um documento de política (`policyDocument`) que contém uma lista de instruções da política. A saída também pode incluir um mapa `context` contendo pares de chave/valor. Se a API usar um plano de uso (o [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource) é definido como `AUTHORIZER`), a função de autorizador do Lambda deve retornar uma das chaves de API do plano de uso como o valor de propriedade `usageIdentifierKey`. Veja a seguir um exemplo dessa saída. ------ #### [ JSON ] **** ``` {   "principalId": "yyyyyyyy", "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": { "stringKey": "value", "numberKey": "1", "booleanKey": "true" }, "usageIdentifierKey": "{api-key}" } ``` ------ Aqui, uma declaração de política especifica se o serviço de execução do API Gateway deve ter permissão ou não (`Effect`) para invocar (`Action`) o método de API especificado (`Resource`). Talvez seja necessário controlar o acesso a vários recursos com base no seu autorizador. Você pode usar um caractere curinga (`*`) para especificar um tipo de recurso (método). Para obter informações sobre como configurar políticas válidas para chamar uma API, consulte [Referência de instrução de políticas do IAM para executar a API no API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-calling-api-permissions). Para o ARN de um método habilitado para autorização, por exemplo, `arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]`, o tamanho máximo é de 1600 bytes. Os valores de parâmetros de caminho, cujo tamanho é determinado em tempo de execução, podem fazer com que o comprimento do ARN exceda o limite. Quando isso acontecer, o cliente da API receberá uma resposta `414 Request URI too long`. Além disso, o Nome de recurso da Amazon (ARN) do recurso, como mostrado na saída da declaração de política pelo autorizador, atualmente está limitado a 512 caracteres. Por esse motivo, você não deve usar o URI com um token de JWT de um tamanho significativo em um URI de solicitação. Em vez disso, você pode passar o token de JWT com segurança em um cabeçalho de solicitação. Você pode acessar o valor `principalId` em um modelo de mapeamento usando a variável `$context.authorizer.principalId`. Isso é útil quando você deseja passar o valor para o backend. Para obter mais informações, consulte [Variáveis de contexto para transformações de dados](api-gateway-mapping-template-reference.md#context-variable-reference). Você pode acessar o valor `stringKey`, `numberKey` ou `booleanKey` (por exemplo, `"value"`, `"1"` ou `"true"`) do mapa `context` em um modelo de mapeamento chamando `$context.authorizer.stringKey`, `$context.authorizer.numberKey` ou `$context.authorizer.booleanKey`, respectivamente. Todos os valores retornados são transformados em string. Observe que não é possível definir um objeto JSON ou matriz como um valor válido de qualquer chave no mapa `context`. Você pode usar o mapa `context` para retornar credenciais em cache do autorizador para o backend usando um modelo de mapeamento de solicitação de integração. Isso permite que o backend forneça uma experiência de usuário aprimorada usando as credenciais em cache para reduzir a necessidade de acessar as chaves secretas e abrir o tokens de autorização para cada solicitação. Para a integração de proxy do Lambda, o API Gateway passa o objeto `context` de um autorizador do Lambda diretamente para a função backend do Lambda como parte da entrada `event`. Você pode recuperar os pares de chave-valor `context` na função do Lambda chamando `$event.requestContext.authorizer.key`. `{api-key}` significa uma chave de API no plano de uso do estágio da API. Para obter mais informações, consulte [Usar planos e chaves de API para APIs REST no APIs Gateway](api-gateway-api-usage-plans.md). Veja a seguir a saída de exemplo do autorizador do Lambda de exemplo. A saída de exemplo contém uma declaração de política para bloquear chamadas (`Deny`) para o método `GET` no estágio `dev` de uma API (`ymy8tbxw7b`) de uma conta da AWS (`123456789012`). ------ #### [ JSON ] **** ``` { "principalId": "user", "policyDocument": { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/" } ] } } ``` ------ # Chamar uma API com um autorizador do Lambda do API Gateway Depois de configurar o autorizador do Lambda (anteriormente conhecido como autorizador personalizado) e implantar a API, você deve testar a API com o autorizador do Lambda habilitado. Para isso, você precisa de um cliente REST, como cURL ou [Postman](https://www.postman.com/). Para os exemplos a seguir, usamos Postman. **nota** Ao chamar um método habilitado para o autorizador, o API Gateway não registrará a chamada para o CloudWatch se o token necessário para o autorizador `TOKEN` não estiver definido, for nulo ou for invalidado pela **Token validation expression (Expressão de validação do token)** especificada. Da mesma forma, o API Gateway não registrará a chamada para o CloudWatch se qualquer uma das origens de identidade necessárias para o autorizador `REQUEST` não estiver definida ou for nula ou vazia. No próximo exemplo, mostramos como usar o Postman para chamar ou testar uma API com um autorizador do Lambda `TOKEN`. O método pode ser aplicado para chamar uma API com um autorizador `REQUEST` do Lambda, se você especificar explicitamente o caminho, o cabeçalho ou os parâmetros de string de consulta necessários. **Para chamar uma API com o autorizador `TOKEN` personalizado** 1. Abra **Postman**, escolha o método **GET** e cole **Invoke URL (Invocar URL)** da API no campo de URL adjacente. Adicione o cabeçalho do token de autorização do Lambda e defina o valor como `allow`. Selecione **Send (Enviar)**. ![\[Chamar a API com o token de permissão de autorização do Lambda\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/custom-auth-call-api-with-allow-token.png) A resposta mostra que o autorizador do Lambda do API Gateway retorna uma resposta **200 OK** e autoriza com êxito a chamada para acessar o endpoint HTTP (http://httpbin.org/get) integrado com o método. 1. Ainda no Postman, altere o valor do cabeçalho do token de autorização do Lambda para `deny`. Selecione **Send (Enviar)**. ![\[Chamar a API com o token de autorização de negação do Lambda\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/custom-auth-call-api-with-deny-token.png) A resposta mostra que o autorizador do Lambda do API Gateway retorna uma resposta **403 Forbidden** sem autorizar a chamada para acessar o endpoint HTTP. 1. No Postman, altere o valor do cabeçalho do token de autorização do Lambda para `unauthorized` e escolha **Send (Enviar)**. ![\[Chamar a API com o token não autorizado de autorização do Lambda\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/custom-auth-call-api-with-unauthorized-token.png) A resposta mostra que o API Gateway retorna uma resposta **401 Unauthorized** sem autorizar a chamada para acessar o endpoint HTTP. 1. Agora, altere o valor do cabeçalho do token de autorização do Lambda para `fail`. Selecione **Send (Enviar)**. ![\[Chamar a API com o token de autorização de falha do Lambda\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/custom-auth-call-api-with-fail-token.png) A resposta mostra que o API Gateway retorna uma resposta **500 Internal Server Error** sem autorizar a chamada para acessar o endpoint HTTP. # Configurar um autorizador do Lambda do API Gateway entre contas Agora você também pode usar uma função do AWS Lambda de uma conta da AWS diferente como sua função do autorizador da API. Cada conta pode estar em qualquer região onde o Amazon API Gateway está disponível. A função do autorizador do Lambda pode usar estratégias de autenticação de token de portador, como OAuth ou SAML. Isso facilita o gerenciamento centralizado e o compartilhamento da função de autorizador do Lambda central em várias APIs do API Gateway. Nesta seção, mostramos como configurar uma função de autorização do Lambda entre contas usando o console do Amazon API Gateway. Estas instruções pressupõem que você já tem uma API do API Gateway em uma conta da AWS e uma função do autorizador do Lambda em outra conta. ## Como configurar um autorizador do Lambda entre contas usando o console do API Gateway Faça login no console do Amazon API Gateway na conta que contém a sua API e faça o seguinte: 1. Escolha sua API e, no painel de navegação principal, selecione **Autorizadores**. 1. Selecione **Criar autorizador**. 1. Em **Nome do autorizador**, insira um nome para o autorizador. 1. Em **Tipo de autorizador**, selecione **Lambda**. 1. Em **Função do Lambda**, insira o ARN completo da função do autorizador do Lambda na sua segunda conta. **nota** No console do Lambda, você pode encontrar o ARN da sua função no canto superior direito da janela. 1. Um aviso com uma string de comando `aws lambda add-permission` será exibido. A política concede permissão do API Gateway para invocar a função do Lambda do autorizador. Copie o comando e salve-o para mais tarde. Execute o comando depois de criar o autorizador. 1. Em **Carga útil do evento do Lambda**, escolha **Token** para um autorizador `TOKEN` ou **Solicitação** para um autorizador `REQUEST`. 1. Dependendo da opção da etapa anterior, siga um destes procedimentos: 1. Para a opção **Token**, faça o seguinte: + Em **Origem do token**, insira o nome do cabeçalho que contém o token de autorização. O cliente da API deve incluir um cabeçalho desse nome para enviar o token de autorização ao autorizador do Lambda. + Opcionalmente, em **Validação do Token**, insira uma instrução RegEx. O API Gateway executa a validação inicial do token de entrada em relação a esta expressão e invoca o autorizador mediante a validação com êxito. Isso ajuda a reduzir as chamadas para a API. + Para armazenar em cache a política de autorização gerada pelo autorizador, mantenha **Armazenamento em cache de autorização** ativado. Quando o armazenamento em cache de políticas está habilitado, você pode optar por modificar o valor **TTL**. A definição de **TTL** como zero desabilita o armazenamento em cache de políticas. Quando o armazenamento em cache de políticas está habilitado, o nome de cabeçalho especificado em **Origem do token** se torna a chave de cache. Se vários valores forem passados para esse cabeçalho na solicitação, todos os valores se tornarão a chave de cache, com a ordem preservada. **nota** O valor de **TTL** padrão é de 300 segundos. O valor máximo é de 3600 segundos. Não é possível aumentar esse limite. 1. Para a opção de **Request (Solicitação)**, faça o seguinte: + Em **Tipo de origem de identidade**, selecione um tipo de parâmetro. Os tipos de parâmetros com suporte são `Header`, `Query string`, `Stage variable` e `Context`. Para adicionar mais origens de identidade, escolha **Adicionar parâmetro**. + Para armazenar em cache a política de autorização gerada pelo autorizador, mantenha **Armazenamento em cache de autorização** ativado. Quando o armazenamento em cache de políticas está habilitado, você pode optar por modificar o valor **TTL**. A definição de **TTL** como zero desabilita o armazenamento em cache de políticas. O API Gateway usa as origens de identidade especificadas como a chave de cache do autorizador de solicitação. Quando o armazenamento em cache é ativado, o API Gateway chama a função do Lambda do autorizador somente depois de verificar com sucesso que todas as origens de identidade especificadas estão presentes em tempo de execução. Se uma origem de identidade especificada estiver ausente, for nula ou vazia, o API Gateway retornará uma resposta `401 Unauthorized` sem chamar a função do Lambda do autorizador. Quando várias origens de identidade são definidas, todas são usadas para derivar a chave de cache do autorizador. A alteração de qualquer parte da chave de cache faz com que o autorizador descarte o documento de política armazenado em cache e gere um novo. Se um cabeçalho com vários valores for passado na solicitação, todos os valores farão parte da chave de cache, com a ordem preservada. + Quando o armazenamento em cache está desativado, não é necessário especificar uma origem de identidade. **nota** Para habilitar o armazenamento em cache, o autorizador deve retornar uma política que seja aplicável a todos os métodos em uma API. Para aplicar uma política de método específico, você pode desativar **Armazenamento em cache de autorização**. 1. Selecione **Criar autorizador**. 1. Cole a string do comando `aws lambda add-permission` que você copiou de uma etapa anterior em uma janela da AWS CLI configurada para sua segunda conta. Substitua `AUTHORIZER_ID` pelo ID do seu autorizador. Isso concederá acesso para sua primeira conta à função do autorizador do Lambda da sua segunda conta. # Controlar o acesso com base nos atributos de uma identidade com o Verified Permissions Use o Amazon Verified Permissions para controlar o acesso à sua API do API Gateway. Quando você usa o API Gateway com o Verified Permissions, ele cria um autorizador do Lambda que usa decisões de autorização refinadas para controlar o acesso à sua API. O Verified Permissions autoriza os chamadores com base em políticas e em um esquema de armazenamento de políticas usando a linguagem Cedar para definir permissões refinadas para usuários de aplicações. Para saber mais, consulte [Create a policy store with a connected API and identity provider](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/getting-started-api-policy-store.html) no *Guia do usuário do Amazon Verified Permissions*. O Verified Permissions comporta grupos de usuários do Amazon Cognito ou provedores de identidade OpenID Connect (OIDC) como fontes de identidade. O Verified Permissions pressupõe que a entidade principal tenha sido previamente identificada e autenticada. O Verified Permissions só é compatível com APIs REST regionais e otimizadas para borda. ## Criar um autorizador do Lambda usando o Verified Permissions O Verified Permissions cria um autorizador do Lambda para determinar se uma entidade principal pode realizar uma ação em sua API. Você precisa criar a política do Cedar que o Verified Permissions usa para realizar suas tarefas de autorização. Veja a seguir um exemplo de política do Cedar que permite o acesso para invocar uma API com base no grupo de usuários do Amazon Cognito, `us-east-1_ABC1234`, para o grupo `developer` no recurso `GET /users` de uma API. O Verified Permissions determina a associação ao grupo analisando o token da identidade do chamador. ``` permit( principal in MyAPI::UserGroup::"us-east-1_ABC1234|developer", action in [ MyAPI::Action::"get /users" ], resource ); ``` O Verified Permissions também pode anexar o autorizador aos métodos da sua API. Nos estágios de produção da sua API, recomendamos não permitir que o Verified Permissions anexe o autorizador para você. A lista a seguir mostra como configurar o Verified Permissions para anexar ou não o autorizador do Lambda à solicitação dos métodos da sua API. **Anexar o autorizador para você (Console de gerenciamento da AWS)** Ao escolher **Criar armazenamento de políticas** no console do Verified Permissions, na página **Implantar integração de aplicações**, escolha **Agora**. **Não anexe o autorizador para você (Console de gerenciamento da AWS)** Ao escolher **Criar armazenamento de políticas** no console do Verified Permissions, na página **Implantar integração de aplicações**, escolha **Mais tarde**. O Verified Permissions ainda cria um autorizador do Lambda para você. O autorizador do Lambda começa com `AVPAuthorizerLambda-`. Para ter mais instruções sobre como anexar a autorização em um método, consulte [Configurar um método para usar um autorizador do Lambda (console)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-console). **Anexar o autorizador para você (CloudFormation)** No modelo do CloudFormation gerado pelo Verified Permissions, na seção `Conditions`, defina `"Ref": "shouldAttachAuthorizer"` como `true`. **Não anexe o autorizador para você (CloudFormation)** No modelo do CloudFormation gerado pelo Verified Permissions, na seção `Conditions`, defina `"Ref": "shouldAttachAuthorizer"` como `false`. O Verified Permissions ainda cria um autorizador do Lambda para você. O autorizador do Lambda começa com `AVPAuthorizerLambda-`. Para ter mais instruções sobre como anexar a autorização em um método, consulte [Configurar um método para usar um autorizador do Lambda (AWS CLI)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-cli). ## Chamar um autorizador do Lambda usando o Verified Permissions É possível chamar o autorizador do Lambda fornecendo uma identidade ou um token de acesso no cabeçalho `Authorization`. Para obter mais informações, consulte [Chamar uma API com um autorizador do Lambda do API Gateway](call-api-with-api-gateway-lambda-authorization.md). O API Gateway armazena em cache a política que o autorizador do Lambda exibe por 120 segundos. É possível modificar o TTL no console do API Gateway ou usando a AWS CLI. # Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador Em vez de usar [funções e políticas do IAM](permissions.md) ou [autorizadores do Lambda](apigateway-use-lambda-authorizer.md) (anteriormente conhecidos como autorizadores personalizados), você pode usar um [grupo de usuários do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) para controlar quem pode acessar sua API no Amazon API Gateway. Para usar um grupo de usuários do Amazon Cognito com sua API, primeiro é necessário criar um autorizador do tipo `COGNITO_USER_POOLS` e depois configurar um método da API para usar esse autorizador. Após a implantação da API, o cliente deve primeiro inserir o usuário no grupo de usuários, obter uma [identidade ou token de acesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) para o usuário e, então, chamar o método de API com um dos tokens, que são normalmente definidos para o cabeçalho `Authorization` da solicitação. A chamada de API é realizada somente se o token necessário é fornecido e válido; caso contrário, o cliente não está autorizado a fazer a chamada, pois o cliente não tem credenciais que poderiam ser autorizadas. O token de identidade é usado para autorizar chamadas de API com base nas declarações de identidade do usuário conectado. O token de acesso é usado para autorizar chamadas de API com base nos escopos personalizados de recursos protegidos por acesso especificado. Para obter mais informações, consulte [Uso de tokens com grupos de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) e [Servidor de recursos e escopos personalizados](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Para criar e configurar um grupo de usuários do Amazon Cognito para sua API, realize as seguintes tarefas: + Use o console, a CLI/SDK ou a API do Amazon Cognito para criar um grupo de usuários ou use um pertencente a outra conta da AWS. + Use o console, a CLI/SDK ou a API do API Gateway para criar um autorizador do API Gateway com o grupo de usuários escolhido. + Use o console, a CLI/SDK ou a API do API Gateway para habilitar o autorizador em métodos de API selecionados. Para chamar quaisquer métodos de API com um grupo de usuários ativado, os clientes da API realizam as seguintes tarefas: + Use a CLI/SDK ou a API do Amazon Cognito para conectar um usuário ao grupo de usuários escolhido e obter um token de identidade ou de acesso. Para saber mais sobre o uso dos SDKs, consulte [Exemplos de código do Amazon Cognito usando AWS SDKs](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html). + Use um framework específico do cliente para chamar a API do API Gateway e fornecer o token apropriado no cabeçalho `Authorization`. Como um desenvolvedor de API, você deve fornecer aos desenvolvedores de clientes o ID do grupo de usuários, um ID de cliente e, possivelmente, os segredos de cliente associado, que são definidos como parte do grupo de usuários. **nota** Para permitir que um usuário faça login usando as credenciais do Amazon Cognito e também obtenha credenciais temporárias para usar com as permissões de uma função do IAM, use as [identidades federadas do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html). Para cada método HTTP do endpoint de recurso de API, defina o tipo de autorização, categoria `Method Execution`, como `AWS_IAM`. Nesta seção, descrevemos como criar um grupo de usuários, integrar uma API do API Gateway a esse grupo de usuários e invocar essa API integrada a ele. **Topics** + [Criar um grupo de usuários do Amazon Cognito para uma API REST](apigateway-create-cognito-user-pool.md) + [Integre uma API REST com um grupo de usuários do Amazon Cognito](apigateway-enable-cognito-user-pool.md) + [Chamar uma API REST integrada a um grupo de usuários do Amazon Cognito](apigateway-invoke-api-integrated-with-cognito-user-pool.md) + [Configurar o autorizador do Amazon Cognito entre contas para uma API REST usando o console do API Gateway](apigateway-cross-account-cognito-authorizer.md) + [Criar um autorizador do Amazon Cognito para uma API REST usando o CloudFormation](apigateway-cognito-authorizer-cfn.md) # Criar um grupo de usuários do Amazon Cognito para uma API REST Antes de integrar sua API a um grupo de usuários, você deve criar o grupo de usuários no Amazon Cognito. A configuração do grupo de usuários deve seguir todas as [cotas de recursos do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). Todas as variáveis do Amazon Cognito definidas pelo usuário, como grupos, usuários e perfis, devem usar apenas caracteres alfanuméricos. Para obter instruções sobre como criar um grupo de usuários, consulte [Tutorial: criar um grupo de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) no *Guia do desenvolvedor do Amazon Cognito*. Anote o ID do grupo de usuários, o ID do cliente e qualquer segredo de cliente. O cliente deverá fornecê-los ao Amazon Cognito para que o usuário se registre no grupo de usuários, conecte-se a esse grupo de usuários e obtenha um token de identidade ou acesso a ser incluído em solicitações para chamar métodos de API que são configurados com o grupo de usuários. Além disso, você deve especificar o nome do grupo de usuários ao configurá-lo como um autorizador no API Gateway, conforme descrito a seguir. Se você estiver usando tokens de acesso para autorizar chamadas de método da API, certifique-se de configurar a integração do aplicativo com o grupo de usuários para definir os escopos personalizados que você deseja em um determinado servidor de recursos. Para obter mais informações sobre o uso de tokens com grupos de usuários do Amazon Cognito, consulte [Uso de tokens com grupos de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Para obter mais informações sobre servidores de recursos, consulte [Definir servidores de recursos para seu grupo de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Anote os identificadores do servidor de recursos configurado e os nomes de escopo personalizados. Você precisará deles para elaborar os nomes completos do escopo de acesso para **OAuth Scopes (Escopos OAuth)**, que são usados pelo autorizador do `COGNITO_USER_POOLS`. ![\[Servidores e escopos de recursos do grupo de usuários do Amazon Cognito\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png) # Integre uma API REST com um grupo de usuários do Amazon Cognito Depois de criar um grupo de usuários do Amazon Cognito, no API Gateway, você deve criar um autorizador `COGNITO_USER_POOLS` que use o grupo de usuários. O procedimento a seguir mostra como fazer isso usando o console do API Gateway. **nota** Você pode usar a ação [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) para criar um autorizador `COGNITO_USER_POOLS` que usa vários grupos de usuários. Você pode usar até 1.000 grupos de usuários para um autorizador `COGNITO_USER_POOLS`. Este limite não pode ser aumentado. **Importante** Depois de executar qualquer um dos procedimentos a seguir, você precisará implantar ou reimplantar sua API para propagar as alterações. Para mais informações sobre como implantar sua API, consulte [Implantar APIs REST no API Gateway](how-to-deploy-api.md). **Como criar um autorizador `COGNITO_USER_POOLS` usando o console do API Gateway** 1. Crie uma nova API ou selecione uma API existente no API Gateway. 1. No painel de navegação principal, selecione **Autorizadores**. 1. Selecione **Criar autorizador**. 1. Para configurar o novo autorizador para usar um grupo de usuários, faça o seguinte: 1. Em **Nome do autorizador**, insira um nome. 1. Em **Tipo de autorizador**, selecione **Cognito**. 1. Em **Grupo de usuários do Cognito**, escolha a Região da AWS onde você criou o Amazon Cognito e selecione um grupo de usuários disponível. É possível usar uma variável de estágio para definir o grupo de usuários. Use o seguinte formato para o grupo de usuários: `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`. 1. Em **Origem do token**, insira **Authorization** como o nome de cabeçalho para passar o token de identidade ou acesso que é retornado pelo Amazon Cognito quando um usuário faz login com êxito. 1. (Opcional) Insira uma expressão regular no campo **Validação do token** para validar o campo `aud` (público) do token de identidade antes de a solicitação ser autorizada com o Amazon Cognito. Observe que, ao usar um token de acesso, essa validação rejeita a solicitação porque o token de acesso não contém o campo `aud`. 1. Selecione **Criar autorizador**. 1. Depois de criar o autorizador `COGNITO_USER_POOLS`, você tem a opção de testar a invocação fornecendo um token de identidade provisionado do grupo de usuários. Não é possível usar um token de acesso para testar a invocação do autorizador. Você pode obter esse token de identidade chamando o [SDK de identidade do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) para fazer login do usuário. Você também pode usar a ação [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html). Se você não configurar **Escopos de autorização**, o API Gateway tratará o token fornecido como um token de identidade. O procedimento anterior cria um autorizador `COGNITO_USER_POOLS` que usa o grupo de usuários do Amazon Cognito recém-criado. Dependendo de como você habilita o autorizador em um método de API, você pode usar um token de identidade ou de acesso que é provisionado do grupo de usuários integrado. **Para configurar um autorizador do `COGNITO_USER_POOLS` nos métodos** 1. Escolha **atributos**. Selecione um novo método ou escolha um método existente. Se necessário, crie um recurso. 1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, escolha **Editar**. 1. Para **Autorizador**, no menu suspenso, selecione os **Autorizadores do grupo de usuários do Amazon Cognito** que você acabou de criar. 1. Para usar um token de identidade, faça o seguinte: 1. Mantenha **Escopos de autorização** em branco. 1. Se necessário, em **Solicitação de integração**, adicione as expressões `$context.authorizer.claims['property-name']` ou `$context.authorizer.claims.property-name` em um modelo de mapeamento de corpo para transmitir a propriedade de declarações de identidade especificada do grupo de usuários para o back-end. Para nomes de propriedades simples, como `sub` ou `custom-sub`, as duas notações são idênticas. Para nomes de propriedades complexos, como `custom:role`, você não pode usar a notação de pontos. Por exemplo, as seguintes expressões de mapeamento passam os [campos padrão](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) da declaração de `sub` e `email` para o backend: ``` { "context" : { "sub" : "$context.authorizer.claims.sub", "email" : "$context.authorizer.claims.email" } } ``` Se você tiver declarado um campo de declaração personalizado quando configurou um grupo de usuários, poderá seguir o mesmo padrão para acessar os campos personalizados. O exemplo a seguir obtém um campo `role` personalizado de uma declaração: ``` { "context" : { "role" : "$context.authorizer.claims.role" } } ``` Se o campo de declaração personalizada for declarado como `custom:role`, use o exemplo a seguir para obter a propriedade da declaração: ``` { "context" : { "role" : "$context.authorizer.claims['custom:role']" } } ``` 1. Para usar um token de acesso, faça o seguinte: 1. Em **Escopos de autorização**, insira um ou mais nomes completos de um escopo que tenha sido configurado quando o grupo de usuários do Amazon Cognito foi criado. Por exemplo, seguindo o exemplo apresentado em [Criar um grupo de usuários do Amazon Cognito para uma API REST](apigateway-create-cognito-user-pool.md), um dos escopos é `https://my-petstore-api.example.com/cats.read`. Durante o runtime, a chamada do método ocorre com êxito se qualquer escopo especificado no método desta etapa corresponder a um escopo que foi reivindicado no token de entrada. Caso contrário, a chamada falhará com uma resposta `401 Unauthorized`. 1. Escolha **Salvar**. 1. Repita essas etapas para outros métodos que você quiser. Com o autorizador `COGNITO_USER_POOLS`, se a opção **OAuth Scopes** não estiver especificada, o API Gateway trata o token fornecido como um token de identidade e verifica a identidade declarada em relação à do grupo de usuários. Caso contrário, o API Gateway trata o token fornecido como um token de acesso e verifica os escopos de acesso que são declarados no token em relação aos escopos de autorização declarados no método. Em vez de usar o console do API Gateway, você também pode habilitar um grupo de usuários do Amazon Cognito em um método especificando um arquivo de definição do OpenAPI e importando a definição da API para o API Gateway. **Para importar um autorizador COGNITO\$1USER\$1POOLS com um arquivo de definição do OpenAPI** 1. Crie (ou exporte) um arquivo de definição do OpenAPI para a sua API. 1. Especifique a definição JSON do autorizador `COGNITO_USER_POOLS` (`MyUserPool`) como parte da seção `securitySchemes` no OpenAPI 3.0 ou da seção `securityDefinitions` no OpenAPI 2.0 da seguinte forma: ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. Para usar o token de identidade para a autorização de método, adicione `{ "MyUserPool": [] }` à definição `security` do método, conforme mostrado no seguinte método GET no recurso raiz. ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": [] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Para usar o token de acesso para a autorização do método, mude a definição de segurança acima para `{ "MyUserPool": [resource-server/scope, ...] }`: ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Se necessário, é possível definir outras configurações de API usando as extensões ou definições do OpenAPI apropriadas. Para obter mais informações, consulte [Extensões OpenAPI para o API Gateway](api-gateway-swagger-extensions.md). # Chamar uma API REST integrada a um grupo de usuários do Amazon Cognito Para chamar um método com um autorizador de grupo de usuários configurado, o cliente deve fazer o seguinte: + Permitir que o usuário se inscreva no grupo de usuários. + Permitir que o usuário se conecte ao grupo de usuários. + Obtenha uma [token de acesso ou identidade](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) do usuário conectado no grupo de usuários. + Inclua o token no cabeçalho `Authorization` (ou outro cabeçalho especificado quando você criou o autorizador). Você pode usar o [AWS Amplify]() para executar essas tarefas. Para obter mais informações, consulte [Como integrar o Amazon Cognito com aplicações Web e móveis](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html). + Para Android, consulte [Conceitos básicos do Amplify para Android](https://docs.amplify.aws/android/build-a-backend/auth/). + Para usar o iOS, consulte [Conceitos básicos do Amplify para iOS](https://docs.amplify.aws/swift/build-a-backend/auth/). + Para usar o JavaScript, consulte [Conceitos básicos do Amplify para Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/). # Configurar o autorizador do Amazon Cognito entre contas para uma API REST usando o console do API Gateway Agora você também pode usar um grupo de usuários do Amazon Cognito de uma conta da AWS diferente como seu autorizador de API. O grupo de usuários do Amazon Cognito pode usar estratégias de autenticação de token de portador, como OAuth ou SAML. Isso facilita o gerenciamento central e o compartilhamento de um autorizador central do grupo de usuários do Amazon Cognito em várias APIs do API Gateway. Nesta seção, mostramos como configurar um grupo de usuários do Amazon Cognito entre contas usando o console do Amazon API Gateway. Essas instruções pressupõem que você já tem uma API do API Gateway em uma conta da AWS e um grupo de usuários do Amazon Cognito em outra conta. ## Configurar o autorizador do Amazon Cognito entre contas para uma API REST Faça login no console do Amazon API Gateway na conta que contém a sua API e faça o seguinte: 1. Crie uma nova API ou selecione uma API existente no API Gateway. 1. No painel de navegação principal, selecione **Autorizadores**. 1. Selecione **Criar autorizador**. 1. Para configurar o novo autorizador para usar um grupo de usuários, faça o seguinte: 1. Em **Nome do autorizador**, insira um nome. 1. Em **Tipo de autorizador**, selecione **Cognito**. 1. Em **Grupo de usuários do Cognito**, copie e cole o ARN completo do grupo de usuários de sua segunda conta. **nota** No console do Amazon Cognito é possível encontrar o ARN do grupo de usuários no campo **Pool ARN (ARN do grupo)** do painel **General Settings (Configurações gerais)**. 1. Em **Origem do token**, insira **Authorization** como o nome de cabeçalho para passar o token de identidade ou acesso que é retornado pelo Amazon Cognito quando um usuário faz login com êxito. 1. (Opcional) Insira uma expressão regular no campo **Validação do token** para validar o campo `aud` (público) do token de identidade antes de a solicitação ser autorizada com o Amazon Cognito. Observe que, ao usar um token de acesso, essa validação rejeita a solicitação porque o token de acesso não contém o campo `aud`. 1. Selecione **Criar autorizador**. # Criar um autorizador do Amazon Cognito para uma API REST usando o CloudFormation É possível usar o CloudFormation para criar um grupo de usuários e um autorizador do Amazon Cognito. O modelo do CloudFormation de exemplo faz o seguinte: + Criar um grupo de usuários do Amazon Cognito. O cliente deve primeiro inscrever o usuário no grupo de usuários e obter uma [identidade ou um token de acesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Se você estiver usando tokens de acesso para autorizar chamadas de método da API, certifique-se de configurar a integração do aplicativo com o grupo de usuários para definir os escopos personalizados que você deseja em um determinado servidor de recursos. + Cria uma API do API Gateway com um método `GET`. + Cria um autorizador do Amazon Cognito que usa o cabeçalho `Authorization` como fonte do token. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: UserPool: Type: AWS::Cognito::UserPool Properties: AccountRecoverySetting: RecoveryMechanisms: - Name: verified_phone_number Priority: 1 - Name: verified_email Priority: 2 AdminCreateUserConfig: AllowAdminCreateUserOnly: true EmailVerificationMessage: The verification code to your new account is {####} EmailVerificationSubject: Verify your new account SmsVerificationMessage: The verification code to your new account is {####} VerificationMessageTemplate: DefaultEmailOption: CONFIRM_WITH_CODE EmailMessage: The verification code to your new account is {####} EmailSubject: Verify your new account SmsMessage: The verification code to your new account is {####} UpdateReplacePolicy: Retain DeletionPolicy: Retain CogAuthorizer: Type: AWS::ApiGateway::Authorizer Properties: Name: CognitoAuthorizer RestApiId: Ref: Api Type: COGNITO_USER_POOLS IdentitySource: method.request.header.Authorization ProviderARNs: - Fn::GetAtt: - UserPool - Arn Api: Type: AWS::ApiGateway::RestApi Properties: Name: MyCogAuthApi ApiDeployment: Type: AWS::ApiGateway::Deployment Properties: RestApiId: Ref: Api DependsOn: - CogAuthorizer - ApiGET ApiDeploymentStageprod: Type: AWS::ApiGateway::Stage Properties: RestApiId: Ref: Api DeploymentId: Ref: ApiDeployment StageName: prod ApiGET: Type: AWS::ApiGateway::Method Properties: HttpMethod: GET ResourceId: Fn::GetAtt: - Api - RootResourceId RestApiId: Ref: Api AuthorizationType: COGNITO_USER_POOLS AuthorizerId: Ref: CogAuthorizer Integration: IntegrationHttpMethod: GET Type: HTTP_PROXY Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets Outputs: ApiEndpoint: Value: Fn::Join: - "" - - https:// - Ref: Api - .execute-api. - Ref: AWS::Region - "." - Ref: AWS::URLSuffix - / - Ref: ApiDeploymentStageprod - / ``` # Integrações para APIs REST no API Gateway Após a configuração de um método de API, você deve integrá-la a um endpoint no backend. Um endpoint de backend também é denominado endpoint de integração e pode ser uma função do Lambda, uma página da web HTTP ou uma ação de serviço da AWS. Assim como ocorre com o método de API, a integração de API tem uma solicitação e uma resposta de integração. Uma solicitação de integração encapsula uma solicitação HTTP recebida pelo backend. Ela pode ou não ser diferente da solicitação de método enviada pelo cliente. A resposta de integração é uma resposta HTTP que encapsula a saída retornada pelo backend. A configuração de uma solicitação de integração envolve o seguinte: configurar como transmitir solicitações de método enviadas pelo cliente para o backend; configurar como transformar os dados da solicitação, se necessário, para os dados da solicitação de integração; especificar qual função do Lambda chamar, especificar para qual servidor HTTP encaminhar a solicitação recebida ou especificar a ação de serviço da AWS a ser chamada. A configuração de uma resposta de integração (aplicável somente a integrações não proxy), envolve o seguinte: configurar como transmitir o resultado retornado pelo backend para uma resposta de método de um determinado código de status, configurar como transformar os parâmetros de resposta de integração especificados em parâmetros de resposta de método pré-configurados e configurar como mapear o corpo de resposta de integração para o corpo de resposta de método de acordo com os modelos de mapeamento de corpo especificados. Programaticamente, uma solicitação de integração é encapsulada pelo recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) e uma resposta de integração pelo recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) do API Gateway. Para configurar uma solicitação de integração, crie um recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) e use-o para configurar a URL de endpoint de integração. Depois, defina as permissões do IAM para acessar o backend e especifique os mapeamentos para transformar os dados da solicitação recebida antes de transmiti-los para o backend. Para configurar uma resposta para integração não proxy, crie um recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) e use-o para definir seu método de resposta de destino. Em seguida, configure como mapear a saída de backend para a resposta de método. **Topics** + [Configurar uma solicitação de integração no API Gateway](api-gateway-integration-settings-integration-request.md) + [Configurar uma resposta de integração no API Gateway](api-gateway-integration-settings-integration-response.md) + [Integrações do Lambda para APIs REST no API Gateway](set-up-lambda-integrations.md) + [Integrações de HTTP para APIs REST no API Gateway](setup-http-integrations.md) + [Transmitir a resposta para suas integrações de proxy no API Gateway](response-transfer-mode.md) + [Integrações privadas para APIs REST no API Gateway](private-integration.md) + [Simular integrações para APIs REST no API Gateway](how-to-mock-integration.md) # Configurar uma solicitação de integração no API Gateway Para configurar uma solicitação de integração, execute as seguintes tarefas obrigatórias e opcionais: 1. Escolha um tipo de integração que determine como os dados da solicitação de método são passados para o backend. 1. Para integrações não simuladas, especifique um método HTTP e o URI do endpoint de destino da integração, exceto para a integração `MOCK`. 1. Para integrações com funções do Lambda e outras ações de serviço da AWS, defina uma função do IAM com as permissões necessárias para o API Gateway chamar o backend em seu nome. 1. Para integrações não proxy, defina os mapeamentos de parâmetros necessários para mapear os parâmetros de solicitação de método predefinidos para os parâmetros de solicitação de integração apropriados. 1. Para integrações não proxy, defina os mapeamentos de corpo necessários para mapear o corpo de solicitação de método de entrada de um determinado tipo de conteúdo de acordo com o modelo de mapeamento especificado. 1. Para integrações não proxy, especifique a condição na qual os dados de solicitação de método de entrada são transmitidos para o backend no estado em que se encontram. 1. Opcionalmente, especifique como lidar com a conversão de tipo para uma carga útil binária. 1. Opcionalmente, declare um nome de namespace de cache e os parâmetros de chave de cache para habilitar o armazenamento em cache da API. A execução dessas tarefas envolve a criação de um recurso [Integração](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) do API Gateway e a definição dos valores de propriedade apropriados. Você pode fazer isso usando o console do API Gateway, os comandos da AWS CLI, um AWS SDK ou a API REST do API Gateway. **Topics** + [Tarefas básicas de uma solicitação de integração da API](integration-request-basic-setup.md) + [Escolher um tipo de integração de API do API Gateway](api-gateway-api-integration-types.md) + [Configurar a integração de proxy com um recurso de proxy](api-gateway-set-up-simple-proxy.md) + [Configurar uma solicitação de integração de API usando o console do API Gateway](how-to-method-settings-console.md) # Tarefas básicas de uma solicitação de integração da API Uma solicitação de integração é uma solicitação HTTP que o API Gateway envia para o backend, transmitindo os dados da solicitação enviada pelo cliente e transformação dos dados, se necessário. O método HTTP (ou o verbo) e o URI da solicitação de integração são determinados pelo backend (ou seja, o endpoint de integração). Eles podem ser os mesmos ou diferentes do método HTTP da solicitação de método e do URI, respectivamente. Por exemplo, quando uma função do Lambda retorna um arquivo que é procurado no Amazon S3, você pode expor essa operação intuitivamente como uma solicitação de método `GET` para o cliente, embora a solicitação de integração correspondente exija que uma solicitação `POST` seja usada para invocar a função do Lambda. Para um endpoint HTTP, é provável que a solicitação de método e a solicitação de integração correspondente usem o mesmo verbo HTTP. No entanto, isso não é obrigatório. Você pode integrar a seguinte solicitação de método: ``` GET /{var}?query=value Host: api.domain.net ``` Com a solicitação de integração a seguir: ``` POST / Host: service.domain.com Content-Type: application/json Content-Length: ... { path: "{var}'s value", type: "value" } ``` Como desenvolvedor de API, você pode usar qualquer verbo HTTP e URI para que uma solicitação de método atenda aos seus requisitos. No entanto, você deve seguir os requisitos do endpoint de integração. Quando os dados da solicitação de método diferem dos dados da solicitação de integração, você pode reconciliar a diferença ao fornecer mapeamentos dos dados da solicitação de método para os dados da solicitação de integração. Nos exemplos anteriores, o mapeamento converte a variável de caminho (`{var}`) e os valores do parâmetro de consulta (`query`) da solicitação de método `GET` nos valores das propriedades da carga útil da solicitação de integração de `path` e `type`. Outros dados de solicitação mapeáveis incluem cabeçalhos e corpo da solicitação. Eles estão descritos em [Mapeamento de parâmetros para APIs REST no API Gateway](rest-api-parameter-mapping.md). Ao configurar a solicitação de integração de proxy HTTP ou o HTTP, você atribui a URL de endpoint HTTP de backend como o valor de URI da solicitação de integração. Por exemplo, na API PetStore, a solicitação, o método para obter uma página de animais de estimação tem o seguinte URI de solicitação de integração: ``` http://petstore-demo-endpoint.execute-api.com/petstore/pets ``` Ao configurar o Lambda ou a integração do proxy do Lambda, você atribui o Nome de recurso da Amazon (ARN) para invocar a função do Lambda como o valor da solicitação de integração do URI. Esse Nome de recurso da Amazon (ARN) tem o seguinte formato: ``` arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations ``` A parte após `arn:aws:apigateway:api-region:lambda:path/`, ou seja, `/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations`, é o caminho do URI da API REST da ação [Invocar](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) do Lambda. Se você usar o console do API Gateway para configurar a integração do Lambda, o API Gateway cria o ARN e o atribui ao URI da integração depois de solicitar a escolha de `lambda-function-name` a partir de uma região. Depois de configurar a solicitação de integração com outra ação de serviço da AWS, o URI da solicitação de integração também é um ARN, semelhante à integração com a ação `Invoke` do Lambda. Por exemplo, para a integração com a ação [GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) do Amazon S3, o URI da solicitação de integração é um ARN do seguinte formato: ``` arn:aws:apigateway:api-region:s3:path/{bucket} ``` O URI da solicitação de integração segue a convenção de caminho para especificar a ação, em que `{bucket}` é o espaço reservado de um nome de bucket. Como alternativa, uma ação de serviço da AWS pode ser referenciada por seu nome. Usando o nome da ação, o URI da solicitação de integração para a ação `GetBucket` do Amazon S3 se torna o seguinte: ``` arn:aws:apigateway:api-region:s3:action/GetBucket ``` Com a URI da solicitação de integração com base em ação, o nome do bucket (`{bucket}`) deve ser especificado no corpo da solicitação de integração (`{ Bucket: "{bucket}" }`), seguindo o formato de entrada da ação `GetBucket`. Para integrações da AWS, você também deve configurar [credenciais](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#credentials) para permitir que o API Gateway chame as ações integradas. Você pode criar uma função nova do IAM ou escolher uma existente para o API Gateway chamar a ação e especificar a função usando seu ARN. Veja a seguir um exemplo desse Nome de recurso da Amazon (ARN): ``` arn:aws:iam::account-id:role/iam-role-name ``` Essa função do IAM deve conter uma política para permitir que a ação seja executada. Ela também deve ter o API Gateway declarado (na relação de confiança da função) como uma entidade confiável para assumir a função. Essas permissões podem ser concedidas na própria ação. Elas são conhecidas como permissões com base em recursos. Para a integração do Lambda, você pode chamar a ação [addPermission](https://docs.aws.amazon.com/lambda/latest/dg/API_AddPermission.html) do Lambda para definir as permissões baseadas em recursos e definir `credentials` como nulas na solicitação de integração do API Gateway. Já abordamos a configuração de integração básica. As configurações avançadas envolvem dados da solicitação de método de mapeamento para os dados da solicitação de integração. Para obter mais informações, consulte [Transformações de dados para APIs REST no API Gateway](rest-api-data-transformations.md). # Escolher um tipo de integração de API do API Gateway Escolha o tipo de integração da API de acordo com os tipos de parâmetro de integração usados e com o modo desejado para transmitir dados que têm origem ou destino no endpoint de integração. Para uma função do Lambda, você pode ter a integração do proxy do Lambda ou a integração personalizada do Lambda. Para um endpoint HTTP, você pode ter a integração de proxy HTTP ou a integração personalizada HTTP. Para uma ação de serviço da AWS, você só pode ter a integração da AWS do tipo não proxy. O API Gateway também oferece suporte à integração simulada, na qual o API Gateway serve como um endpoint de integração para responder a uma solicitação de método. A integração personalizada do Lambda é um caso especial da integração da AWS em que o endpoint de integração corresponde à ação [function-invoking do serviço ](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html)do Lambda. Programaticamente, você escolhe um tipo de integração definindo a propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type) no recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Para a integração de proxy do Lambda, o valor é `AWS_PROXY`. Para a integração personalizada do Lambda e todas as outras integrações da AWS, é `AWS`. Para a integração de proxy HTTP e integração HTTP, o valor é `HTTP_PROXY` e `HTTP`, respectivamente. Para a integração simulada, o valor `type` é `MOCK`. A integração proxy do Lambda oferece suporte a uma configuração de integração simplificada com uma única função do Lambda. A configuração é simples e pode evoluir com o backend sem a necessidade de descartar a configuração existente. Por esses motivos, é altamente recomendável para a integração com uma função do Lambda. Por outro lado, a integração personalizada do Lambda permite a reutilização de modelos de mapeamento configurados para vários endpoints de integração que tenham requisitos semelhantes dos formatos de dados de entrada e saída. A configuração é mais complexa e é recomendável para cenários de aplicativos mais avançados. Da mesma forma, a integração de proxy HTTP tem uma configuração de integração simplificada e pode evoluir com o backend sem a necessidade de descartar a configuração existente. A integração personalizada HTTP é mais difícil de configurar, mas permite a reutilização de modelos de mapeamento configurados para outros endpoints de integração. A lista a seguir resume os tipos de integração suportados: + `AWS`: esse tipo de integração permite que uma API exponha ações de serviço da AWS. Na integração `AWS`, você deve configurar a solicitação e a resposta de integração e configurar os mapeamentos de dados necessários da solicitação de método para a solicitação de integração, e da resposta de integração para a resposta de método. + `AWS_PROXY`: esse tipo de integração permite que um método de API seja integrado à invocação da função do Lambda com uma configuração de integração flexível, versátil e simplificada. Essa integração se baseia em interações diretas entre o cliente e a função integrada do Lambda. Com esse tipo de integração, também conhecida como integração de proxy do Lambda, você não define a solicitação de integração nem a resposta de integração. O API Gateway transmite a solicitação recebida do cliente como a entrada para a função do Lambda do backend. A função integrada do Lambda obtém a entrada [desse formato](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) e analisa a entrada de todas as origens disponíveis, incluindo cabeçalhos de solicitação, variáveis de caminho URL, parâmetros de string de consulta e o corpo aplicável. A função retorna o resultado seguindo esse [formato de saída](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format). Esse é o tipo de integração preferencial para chamar uma função do Lambda por meio do API Gateway e não se aplica a nenhuma outra ação de serviço da AWS, incluindo ações do Lambda diferentes de invocações de funções. + `HTTP`: Este tipo de integração permite que uma API exponha endpoints HTTP no backend. Com a integração `HTTP`, também conhecida como integração personalizada HTTP, você deve configurar a solicitação de integração e a resposta de integração. Devem-se configurar os mapeamentos de dados necessários da solicitação de integração com base na solicitação de método e da resposta de método com base na resposta de integração. + `HTTP_PROXY`: A integração de proxy HTTP permite que um cliente acesse os endpoints HTTP do backend com uma integração simplificada configurada em um único método de API. Você não define a solicitação de integração nem a resposta de integração. O API Gateway transmite a solicitação recebida do cliente para o endpoint HTTP e transmite a resposta de saída do endpoint HTTP para o cliente. + `MOCK`: Este tipo de integração permite que o API Gateway retorne uma resposta sem enviar a solicitação até o backend. Isso é útil para testes de API, pois ele pode ser usado para testar a configuração da integração sem incorrer em custos pelo uso do backend e para ativar o desenvolvimento colaborativo de uma API. Em desenvolvimento colaborativo, uma equipe pode isolar o esforço de desenvolvimento configurando simulações de componentes da API pertencentes a outras equipes com o uso das integrações `MOCK`. Também é usado para retornar cabeçalhos relacionados ao CORS a fim de garantir que o método de API permita acesso ao CORS. Na verdade, o console do API Gateway integra o método `OPTIONS` para oferecer suporte a CORS com uma integração de simulação. [Respostas de Gateway](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) são outros exemplos de integrações de simulação. # Configurar a integração de proxy com um recurso de proxy Para configurar uma integração de proxy em uma API do API Gateway com um [recurso de proxy](api-gateway-method-settings-method-request.md#api-gateway-proxy-resource), execute as seguintes tarefas: + Crie um recurso de proxy com uma variável de caminho voraz de `{proxy+}`. + Defina o método `ANY` no recurso de proxy. + Integre o recurso e o método com um backend usando o tipo de integração HTTP ou Lambda. **nota** Variáveis de caminho vorazes, métodos `ANY` e tipos de integração de proxy são recursos independentes, embora sejam comumente usados em conjunto. Você pode configurar um método HTTP específico em um recurso voraz ou pode aplicar tipos de não integração de proxy a um recurso de proxy. O API Gateway impõe certas restrições e limitações ao lidar com métodos com uma integração de proxy do Lambda ou uma integração de proxy HTTP. Para obter mais detalhes, consulte [Notas importantes do Amazon API Gateway](api-gateway-known-issues.md). **nota** Ao usar a integração de proxy com passagem direta, o API Gateway retornará o cabeçalho `Content-Type:application/json` padrão se o tipo de conteúdo de uma carga útil não for especificado. Um recurso de proxy é mais poderoso quando integrado a um backend que usa uma integração de proxy HTTP ou uma [integração](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) de proxy do Lambda. ## Integração de proxy HTTP com um recurso de proxy A integração de proxy HTTP, designada por `HTTP_PROXY` na API REST do API Gateway, é para integrar uma solicitação de método com um endpoint HTTP de backend. Com esse tipo de integração, o API Gateway simplesmente passa toda solicitação e resposta entre o front-end e o backend, sujeito a certas [restrições e limitações](api-gateway-known-issues.md). **nota** A integração de proxy HTTP oferece suporte para cabeçalhos de vários valores e strings de consulta. Ao aplicar a integração de proxy HTTP a um recurso de proxy, você pode configurar sua API para expor uma parte ou toda uma hierarquia de endpoint do backend HTTP com uma única configuração de integração. Por exemplo, suponha que o backend do site esteja organizado em várias ramificações de nós de árvore no nó raiz (`/site`) como: `/site/a0/a1/.../aN`, `/site/b0/b1/.../bM` etc. Se você integrar o método `ANY` no recurso de proxy de `/api/{proxy+}` aos endpoints de backend com caminhos de URL de `/site/{proxy}`, uma única solicitação de integração poderá oferecer suporte a qualquer operação HTTP (GET, POST etc.) em qualquer `[a0, a1, ..., aN, b0, b1, ...bM, ...]`. Se você aplicar uma integração de proxy a um método HTTP específico, por exemplo, `GET`, em vez disso, a solicitação de integração resultante funcionará com as operações especificadas (ou seja, `GET`) em qualquer um desses nós de backend. ## Integração de proxy do Lambda com um recurso de proxy A integração de proxy do Lambda, designada por `AWS_PROXY` na API REST do API Gateway, é para integrar uma solicitação de método com uma função do Lambda no backend. Com esse tipo de integração, o API Gateway aplica um modelo de mapeamento padrão para enviar a solicitação inteira à função do Lambda e transforma a saída da função do Lambda em respostas HTTP. De maneira semelhante, você pode aplicar a integração de proxy do Lambda a um recurso de proxy de `/api/{proxy+}` para configurar uma única integração para que uma função do Lambda de backend reaja individualmente a alterações em qualquer um dos recursos da API sob `/api`. # Configurar uma solicitação de integração de API usando o console do API Gateway A configuração de um método de API define o método e descreve seus comportamentos. Para configurar um método, você deve especificar um recurso, incluindo a raiz ("/"), na qual o método está exposto, um método HTTP (`GET`, `POST` etc.) e como ele será integrado com o backend de destino. A solicitação e a resposta do método especificam o contrato com o aplicativo iniciador da chamada, estipulando quais parâmetros a API pode receber e qual é a aparência da resposta. Os procedimentos a seguir descrevem como usar o console do API Gateway para criar uma solicitação de integração. **Topics** + [Configurar uma integração com o Lambda](#how-to-method-settings-console-lambda) + [Configurar uma integração HTTP](#how-to-method-settings-console-http) + [Configurar uma integração de serviços da AWS](#how-to-method-settings-console-aws) + [Configurar uma integração simulada](#how-to-method-settings-console-mock) ## Configurar uma integração com o Lambda Use uma integração de função do Lambda para integrar a API a uma função do Lambda. No nível da API, esse é um tipo de integração da `AWS`, se você criar uma integração sem proxy, ou um tipo de integração `AWS_PROXY`, se criar uma integração de proxy. **Configurar uma integração com o Lambda** 1. No painel **Recursos**, escolha **Criar método**. 1. Em **Tipo de método**, selecione um método HTTP. 1. Em **Integration type** (Tipo de integração), escolha **Lambda function** (Função do Lambda). 1. Para usar uma integração do proxy do Lambda, ative **Integração do proxy do Lambda**. Para saber mais sobre integrações do proxy do Lambda, consulte [Compreender a integração de proxy do Lambda do API Gateway](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy). 1. Em **Função do Lambda**, insira o nome da sua função do Lambda. Se você estiver usando uma função do Lambda em uma região que não seja a da API, selecione a região no menu suspenso e insira o nome da função do Lambda. Se você estiver usando uma função do Lambda entre contas, insira o ARN da função. 1. Para usar o valor de tempo limite padrão de 29 segundos, deixe a opção **Tempo limite padrão** ativada. Para definir um tempo limite personalizado, selecione **Tempo limite padrão** e insira um valor de tempo limite entre `50` e `29000` milissegundos. 1. (Opcional) É possível definir as configurações de solicitação de método usando os menus suspensos a seguir. Escolha **Configurações de solicitação de método** e defina a solicitação de método. Para saber mais, consulte a etapa 3 de [Editar uma solicitação de método do API Gateway no console do API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). Você também pode definir as configurações de solicitação de método depois de criar o método. 1. Escolha **Criar método**. ## Configurar uma integração HTTP Use uma integração HTTP para integrar a API a um endpoint HTTP. No nível da API, este é o tipo de integração `HTTP`. **Configurar uma integração HTTP** 1. No painel **Recursos**, escolha **Criar método**. 1. Em **Tipo de método**, selecione um método HTTP. 1. Em **Tipo de integração**, escolha **HTTP**. 1. Para usar uma integração de proxy HTTP, ative a **Integração do proxy HTTP**. Para saber mais sobre integrações de proxy HTTP, consulte [Configurar integrações de proxy HTTP no API Gateway](setup-http-integrations.md#api-gateway-set-up-http-proxy-integration-on-proxy-resource). 1. Em **HTTP method (Método HTTP)**, escolha o tipo de método HTTP mais parecido com o método no backend HTTP. 1. Em **URL do endpoint**, insira o URL do back-end HTTP que você deseja que esse método use. 1. Em **Manuseio de conteúdo**, selecione um comportamento de manuseio de conteúdo. 1. Para usar o valor de tempo limite padrão de 29 segundos, deixe a opção **Tempo limite padrão** ativada. Para definir um tempo limite personalizado, selecione **Tempo limite padrão** e insira um valor de tempo limite entre `50` e `29000` milissegundos. 1. (Opcional) É possível definir as configurações de solicitação de método usando os menus suspensos a seguir. Escolha **Configurações de solicitação de método** e defina a solicitação de método. Para saber mais, consulte a etapa 3 de [Editar uma solicitação de método do API Gateway no console do API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). Você também pode definir as configurações de solicitação de método depois de criar o método. 1. Escolha **Criar método**. ## Configurar uma integração de serviços da AWS Use uma integração de serviços da AWS para integrar a API diretamente a um serviço da AWS. No nível da API, este é o tipo de integração `AWS`. Para configurar uma API do API Gateway, siga qualquer um destes procedimentos: + Crie uma nova função do Lambda. + Defina uma permissão de recurso na função do Lambda. + Execute qualquer outra ação do serviço do Lambda. Você deve escolher o **Serviço da AWS**. **Configurar uma integração de serviços da AWS** 1. No painel **Recursos**, escolha **Criar método**. 1. Em **Tipo de método**, selecione um método HTTP. 1. Em **Tipo de integração**, selecione **Serviço da AWS **. 1. Para **Região da AWS**, escolha a região da AWS que esse método deve usar para chamar a ação. 1. Em **Serviço da AWS**, selecione o serviço da AWS que esse método deve chamar. 1. Em **Subdomínio da AWS**, digite o subdomínio usado pelo serviço da AWS. Normalmente, você deixaria este campo em branco. Alguns serviços da AWS podem oferecer suporte a subdomínios como parte dos hosts. Consulte a documentação do serviço para a disponibilidade e, se disponível, detalhes. 1. Para **HTTP method (Método HTTP)**, escolha o tipo de método HTTP que corresponde à ação. Para o tipo de método HTTP, consulte a documentação de referência da API para o serviço da AWS que você escolheu em **Serviço da AWS**. 1. Em **Tipo de ação**, selecione **Usar nome da ação** para usar uma ação de API ou **Usar a substituição de caminho** para usar um caminho de recurso personalizado. Para conhecer as ações e os caminho de recurso personalizado disponíveis, consulte a documentação de referência de API do serviço da AWS que você escolheu em **Serviço da AWS**. 1. Insira o **Nome da ação** ou **Substituição do caminho**. 1. Em **Função de execução**, digite o ARN do perfil do IAM que o método usará para chamar a ação. Para criar um perfil do IAM, é possível adaptar as instruções em [Etapa 1: Criar o perfil de execução do proxy de serviço da AWS](getting-started-aws-proxy.md#getting-started-aws-proxy-add-roles). Especifique uma política de acesso com o número desejado de instruções de recursos e ações: Para obter mais informações, consulte [Como o Amazon API Gateway funciona com o IAM](security_iam_service-with-iam.md). Para a sintaxe da instrução de ação e recurso, consulte a documentação do serviço da AWS que você escolheu em **Serviço da AWS**. Para a relação de confiança da função do IAM, especifique o seguinte, que permite que o API Gateway tome medidas em nome da sua conta da AWS: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 1. Para usar o valor de tempo limite padrão de 29 segundos, deixe a opção **Tempo limite padrão** ativada. Para definir um tempo limite personalizado, selecione **Tempo limite padrão** e insira um valor de tempo limite entre `50` e `29000` milissegundos. 1. (Opcional) É possível definir as configurações de solicitação de método usando os menus suspensos a seguir. Escolha **Configurações de solicitação de método** e defina a solicitação de método. Para saber mais, consulte a etapa 3 de [Editar uma solicitação de método do API Gateway no console do API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). Você também pode definir as configurações de solicitação de método depois de criar o método. 1. Escolha **Criar método**. ## Configurar uma integração simulada Use uma integração simulada se quiser que o API Gateway atue como seu back-end para retornar respostas estáticas. No nível da API, este é o tipo de integração `MOCK`. Normalmente, você pode usar a integração `MOCK` quando a sua API ainda não for final e você quiser gerar respostas de API para desbloquear equipes dependentes para testes. Para o método `OPTION`, o API Gateway define a integração `MOCK` como padrão para retornar cabeçalhos com compartilhamento de recursos de origem cruzada para o recurso da API aplicada. **Configurar uma integração simulada** 1. No painel **Recursos**, escolha **Criar método**. 1. Em **Tipo de método**, selecione um método HTTP. 1. Em **Tipo de integração**, escolha **Simulação**. 1. (Opcional) É possível definir as configurações de solicitação de método usando os menus suspensos a seguir. Escolha **Configurações de solicitação de método** e defina a solicitação de método. Para saber mais, consulte a etapa 3 de [Editar uma solicitação de método do API Gateway no console do API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). Você também pode definir as configurações de solicitação de método depois de criar o método. 1. Escolha **Criar método**. # Configurar uma resposta de integração no API Gateway Para uma integração não proxy, é necessário configurar pelo menos uma resposta de integração e transformá-la na resposta padrão, para passar o resultado retornado do backend para o cliente. Você pode optar por transmitir o resultado no estado em que se encontra e transformar os dados de resposta de integração para os dados da resposta de método se os dois tiverem formatos diferentes. Para uma integração de proxy, o API Gateway transmite automaticamente a saída de backend para o cliente como uma resposta HTTP. Você não define uma resposta de integração nem uma resposta de método. Para configurar uma resposta de integração, execute as seguintes tarefas obrigatórias e opcionais: 1. Especifique um código de status HTTP de uma resposta de método para a qual os dados da resposta de integração são mapeados. Isso é obrigatório. 1. Defina uma expressão regular para selecionar a saída de backend a ser representada por essa resposta de integração. Se você deixar isso em branco, a resposta será a padrão que é usada para detectar qualquer resposta ainda não configurada. 1. Se necessário, declare mapeamentos consistindo em pares de chave-valor para mapear os parâmetros de resposta de integração especificados para determinados parâmetros de resposta de método. 1. Se necessário, adicione modelos de mapeamento de corpo para transformar cargas úteis de resposta de integração determinadas nas cargas úteis de resposta de método especificadas. 1. Se necessário, especifique como lidar com a conversão de tipo para uma carga útil binária. Resposta de integração é uma resposta HTTP que encapsula a saída retornada pela resposta do backend. Para um endpoint HTTP, a resposta do backend é uma resposta HTTP. O código de status da resposta de integração pode obter o código de status retornado pelo backend e o corpo da resposta de integração é a carga útil retornada pelo backend. Para obter um endpoint do Lambda, a resposta do backend é a saída retornada do função do Lambda. Com a integração do Lambda a saída da função do Lambda é retornada como uma resposta `200 OK`. A carga útil pode conter o resultado como dados JSON, incluindo uma string JSON, um objeto JSON ou uma mensagem de erro como um objeto JSON. Você pode atribuir uma expressão regular à propriedade [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) para mapear uma resposta de erro para uma resposta de erro HTTP apropriada. Para obter mais informações sobre a resposta do erro da função do Lambda, consulte [Manipular erros do Lambda no API Gateway](handle-errors-in-lambda-integration.md). Com a integração de proxy do Lambda, a função do Lambda deve retornar uma saída com o seguinte formato: ``` { statusCode: "...", // a valid HTTP status code headers: { custom-header: "..." // any API-specific custom header }, body: "...", // a JSON string. isBase64Encoded: true|false // for binary support } ``` Não há necessidade de mapear a resposta da função do Lambda à sua resposta HTTP adequada. Para retornar o resultado para o cliente, configure a resposta de integração para transmitir a resposta do endpoint no estado em que se encontra para a resposta de método correspondente. Ou você pode mapear os dados da resposta de método do endpoint aos dados da resposta de método. Os dados da resposta que podem ser mapeados incluem o código de status da resposta, os parâmetros de cabeçalho da resposta e o corpo da resposta. Se nenhuma resposta de método for definida para o código de status retornado, o API Gateway retornará um erro 500. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). # Integrações do Lambda para APIs REST no API Gateway Você pode integrar um método de API a uma função do Lambda usando integração de proxy do Lambda ou integração sem proxy do Lambda (personalizada). Na integração de proxy do Lambda, a configuração necessária é simples. Defina o método HTTP da integração como POST, o URI de endpoint de integração como o ARN da ação de invocação da função do Lambda de uma função específica do Lambda e conceda ao API Gateway permissão para chamar a função do Lambda em seu nome. Na integração não proxy do Lambda, além das etapas de configuração da integração de proxy, você também especifica como os dados da solicitação de entrada serão mapeados para a solicitação de integração e como os dados da resposta de integração resultante serão mapeados para a resposta de método. **Topics** + [Integrações de proxy do Lambda no API Gateway](set-up-lambda-proxy-integrations.md) + [Configurar integrações personalizadas do Lambda no API Gateway](set-up-lambda-custom-integrations.md) + [Configurar a invocação assíncrona da função do Lambda do backend](set-up-lambda-integration-async.md) + [Manipular erros do Lambda no API Gateway](handle-errors-in-lambda-integration.md) # Integrações de proxy do Lambda no API Gateway A seção a seguir mostra como usar uma integração de proxy do Lambda. **Topics** + [Compreender a integração de proxy do Lambda do API Gateway](#api-gateway-create-api-as-simple-proxy) + [Suporte para cabeçalhos de vários valores e parâmetros de string de consulta](#apigateway-multivalue-headers-and-parameters) + [Formato de entrada de uma função do Lambda para integração de proxy](#api-gateway-simple-proxy-for-lambda-input-format) + [Formato de saída de uma função do Lambda para integração de proxy](#api-gateway-simple-proxy-for-lambda-output-format) + [Configurar a integração de proxy do Lambda para o API Gateway usando a AWS CLI](set-up-lambda-proxy-integration-using-cli.md) + [Configurar um recurso de proxy com a integração de proxy do Lambda com uma definição OpenAPI](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md) ## Compreender a integração de proxy do Lambda do API Gateway A integração de proxy do Lambda do Amazon API Gateway é um mecanismo simples, potente e ágil para criar uma API com uma configuração de um único método de API. A integração de proxy do Lambda permite que o cliente chame uma única função do Lambda no backend. A função acessa muitos recursos ou recursos de outros serviços da AWS, incluindo chamadas para outras funções do Lambda. Na integração de proxy do Lambda, quando um cliente envia uma solicitação de API, o API Gateway repassa um [objeto do evento](#api-gateway-simple-proxy-for-lambda-input-format) para a função do Lambda integrada, exceto pelo fato de que a ordem dos parâmetros da solicitação não é preservada. Esses [dados de solicitação](#api-gateway-simple-proxy-for-lambda-input-format) incluem cabeçalhos de solicitação, parâmetros de strings de consulta, variáveis de caminho URL, carga e dados de configuração da API. Os dados de configuração podem incluir o nome do estágio de implantação atual, variáveis de estágio, identidade do usuário ou contexto de autorização (se houver). A função do Lambda do backend analisa os dados da solicitação recebida para determinar a resposta que ela retorna. Para que o API Gateway passe a saída do Lambda como a resposta da API para o cliente, a função do Lambda deve retornar o resultado [neste formato](#api-gateway-simple-proxy-for-lambda-output-format). Como o API Gateway não interfere muito entre o cliente e a função do Lambda do backend para a integração de proxy do Lambda, o cliente e a função do Lambda integrada podem se adaptar às alterações mútuas sem quebrar a configuração de integração existente da API. Para permitir isso, o cliente deve seguir os protocolos de aplicação promulgados pela função do Lambda de backend. É possível configurar uma integração de proxy do Lambda para qualquer método de API. Mas uma integração de proxy do Lambda é mais potente quando configurada para um método de API que envolve um recurso de proxy genérico. O recurso de proxy genérico pode ser identificado por um modelo variável de caminho especial de `{proxy+}`, pelo espaço reservado de método `ANY` ou ambos. O cliente pode passar a entrada da função do Lambda de backend na solicitação recebida como parâmetros da solicitação ou carga aplicável. Os parâmetros de solicitação incluem cabeçalhos, variáveis de caminho URL, parâmetros de string de consulta e a carga aplicável. A função do Lambda integrada verifica todas as fontes de entrada antes de processar a solicitação e responder ao cliente com mensagens de erro significativas se qualquer uma das entradas obrigatórias estiver ausente. Ao chamar um método de API integrado ao método HTTP genérico de `ANY` e o recurso genérico de `{proxy+}`, o cliente envia uma solicitação com um método HTTP específico em vez de `ANY`. O cliente também especifica determinado caminho URL em vez de `{proxy+}`, e inclui todos os cabeçalhos necessários, parâmetros de strings de consulta ou uma carga aplicável. A lista a seguir resume comportamentos de tempo de execução de diferentes métodos de API com a integração de proxy do Lambda: + `ANY /{proxy+}`: o cliente deve escolher determinado método HTTP, definir determinada hierarquia de caminho de recursos e pode definir todos os cabeçalhos, parâmetros de strings de consulta e carga aplicáveis para passar os dados como entrada para a função do Lambda integrada. + `ANY /res`: o cliente deve escolher determinado método HTTP e pode definir todos os cabeçalhos, parâmetros de strings de consulta e carga aplicáveis para passar os dados como entrada para a função do Lambda integrada. + `GET|POST|PUT|... /{proxy+}`: o cliente pode definir determinada hierarquia de caminho de recursos, cabeçalhos, parâmetros de strings de consulta e carga aplicáveis para passar os dados como entrada para a função do Lambda integrada. + `GET|POST|PUT|... /res/{path}/...`: o cliente deve escolher determinado segmento de caminho (para a variável `{path}`) e pode definir os cabeçalhos de solicitação, parâmetros de strings de consulta e carga aplicáveis para passar os dados de entrada para a função do Lambda integrada. + `GET|POST|PUT|... /res`: o cliente pode escolher os cabeçalhos de solicitação, parâmetros de strings de consulta e carga aplicáveis para passar dados de entrada para a função do Lambda integrada. Tanto o recurso de proxy de `{proxy+}` quanto o recurso personalizado de `{custom}` são expressos como modelos de variáveis de caminho. No entanto, `{proxy+}` pode indicar qualquer recurso ao longo de uma hierarquia de caminho, enquanto `{custom}` refere-se apenas a determinado segmento de caminho. Por exemplo, um supermercado pode organizar seu inventário de produtos online por nomes de departamento, categorias de produtos e tipos de produtos. O site do supermercado pode representar os produtos disponíveis pelos seguintes modelos de variáveis de caminho de recursos personalizados: `/{department}/{produce-category}/{product-type}`. Por exemplo, maçãs são representadas por `/produce/fruit/apple` e cenouras por `/produce/vegetables/carrot`. Ele também pode usar `/{proxy+}` para representar qualquer departamento, categoria ou tipo de produto que o cliente pode procurar ao fazer compras na loja online. Por exemplo, `/{proxy+}` pode indicar qualquer um dos seguintes itens: + `/produce` + `/produce/fruit` + `/produce/vegetables/carrot` Para permitir que os clientes procurem qualquer produto disponível, a categoria do produto e o departamento associado, você pode expor um único método de `GET /{proxy+}` com permissões somente leitura. Da mesma forma, para permitir que um supervisor atualize o inventário do departamento do `produce`, você pode configurar outro método único de `PUT /produce/{proxy+}` com as permissões de leitura/gravação. Para permitir que um caixa atualize o total de um vegetal, você pode configurar um método `POST /produce/vegetables/{proxy+}` com permissões de leitura/gravação. Para permitir que um gerente de loja realize qualquer ação possível em qualquer produto disponível, o desenvolvedor da loja online pode expor o método `ANY /{proxy+}` com permissões de leitura/gravação. Em qualquer caso, na ocasião da execução, o cliente ou o funcionário deve selecionar um produto específico de determinado tipo em um departamento escolhido, uma categoria de produto específica em um departamento escolhido ou um departamento específico. Para obter mais informações sobre como configurar integrações de proxy do API Gateway, consulte [Configurar a integração de proxy com um recurso de proxy](api-gateway-set-up-simple-proxy.md). A integração de proxy exige que o cliente tenha um conhecimento mais detalhado dos requisitos de backend. Portanto, para garantir uma melhor performance das aplicações e da experiência do usuário, o desenvolvedor de backend deve comunicar claramente ao desenvolvedor cliente os requisitos do backend e fornecer um mecanismo de feedback de erro robusto quando os requisitos não são atendidos. ## Suporte para cabeçalhos de vários valores e parâmetros de string de consulta Agora o API Gateway oferece suporte a vários cabeçalhos e parâmetros de string de consulta que possuem o mesmo nome. Cabeçalhos de vários valores, bem como cabeçalhos e parâmetros de valor único, podem ser combinados nas mesmas solicitações e respostas. Para obter mais informações, consulte [Formato de entrada de uma função do Lambda para integração de proxy](#api-gateway-simple-proxy-for-lambda-input-format) e [Formato de saída de uma função do Lambda para integração de proxy](#api-gateway-simple-proxy-for-lambda-output-format). ## Formato de entrada de uma função do Lambda para integração de proxy Com a integração de proxy do Lambda, o API Gateway mapeia toda a solicitação do cliente para o parâmetro `event` de entrada da função do Lambda de back-end. O exemplo a seguir mostra a estrutura de um evento que o API Gateway envia para uma integração de proxy do Lambda. Neste exemplo, supomos que a invocação ao API Gateway tenha sido a seguinte: ``` curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2' ``` A saída será exibida como a seguir: ``` { "resource": "/my/path", "path": "/my/path", "httpMethod": "GET", "headers": { "header1": "value1", "header2": "value2", "header3": "value1,value2" }, "multiValueHeaders": { "header1": ["value1"], "header2": ["value1","value2"], "header3": ["value1,value2"] }, "queryStringParameters": { "parameter1": "value1", "parameter2": "value2", "parameter3": "value1,value2" }, "multiValueQueryStringParameters": { "parameter1": ["value1"], "parameter2": ["value1","value2"], "parameter3": ["value1,value2"] }, "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": "IP", "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 } ``` **nota** Na entrada: A chave `headers` só pode conter cabeçalhos de valor único. A chave `multiValueHeaders` pode conter cabeçalhos de vários valores e cabeçalhos de valor único. Se você especificar valores para `headers` e `multiValueHeaders`, o API Gateway os mesclará em uma única lista. Se o mesmo de chave/valor for especificado em ambos, somente os valores de `multiValueHeaders` aparecerão na lista mesclada. Na entrada para a função do Lambda do backend, o objeto `requestContext` é um mapa de pares de chave/valor. Em cada par, a chave é o nome de uma propriedade de variável [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference), e o valor é o valor dessa propriedade. O API Gateway pode adicionar novas chaves ao mapa. Dependendo dos recursos que estão habilitados, o mapa `requestContext` pode variar de acordo com a API. Por exemplo, no exemplo anterior, nenhum tipo de autorização é especificado. Portanto, nenhuma propriedade `$context.authorizer.*` ou `$context.identity.*` está presente. Quando um tipo de autorização é especificado, isso faz com que o API Gateway repasse informações do usuário autorizado para o endpoint de integração em um objeto `requestContext.identity` da seguinte forma: + Quando o tipo de autorização é `AWS_IAM`, as informações do usuário autorizado incluem propriedades `$context.identity.*`. + Quando o tipo de autorização é `COGNITO_USER_POOLS` (autorizador do Amazon Cognito), as informações do usuário autorizado incluem propriedades `$context.identity.cognito*` e `$context.authorizer.claims.*`. + Quando o tipo de autorização é `CUSTOM` (autorizador do Lambda), as informações do usuário autorizado incluem propriedades `$context.authorizer.principalId` e outras `$context.authorizer.*` aplicáveis. ## Formato de saída de uma função do Lambda para integração de proxy Na integração de proxy do Lambda, o API Gateway requer a função do Lambda do backend para retornar a saída de acordo com o seguinte formato JSON: ``` { "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headerName": "headerValue", ... }, "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... }, "body": "..." } ``` Na saída: + As chaves `headers` e `multiValueHeaders` podem ser não especificadas se nenhum cabeçalho de resposta extra precisar ser retornado. + A chave `headers` só pode conter cabeçalhos de valor único. + A chave `multiValueHeaders` pode conter cabeçalhos de vários valores e cabeçalhos de valor único. Você pode usar a chave `multiValueHeaders` para especificar todos os seus cabeçalhos extras, incluindo os de valor único. + Se você especificar valores para `headers` e `multiValueHeaders`, o API Gateway os mesclará em uma única lista. Se o mesmo de chave/valor for especificado em ambos, somente os valores de `multiValueHeaders` aparecerão na lista mesclada. Para ativar o CORS da integração de proxy do Lambda, você deve adicionar `Access-Control-Allow-Origin:domain-name` à saída `headers`. `domain-name` pode ser `*` para qualquer nome de domínio. A saída `body` é organizado para o front-end como a carga de resposta do método. Se `body` for um blob binário, você poderá codificá-lo como uma string codificada em Base64, definindo `isBase64Encoded` como `true` e configurando `*/*` como **Binary Media Type (Tipo de mídia binário)**. Caso contrário, será possível defini-lo como `false` ou deixá-lo sem especificação. **nota** Para obter mais informações sobre como habilitar o suporte a binários, consulte [Ativação do suporte binário usando o console do API Gateway](api-gateway-payload-encodings-configure-with-console.md). Para obter um exemplo de função do Lambda, consulte [Exibir mídia binária de uma integração do proxy do Lambda no API Gateway](lambda-proxy-binary-media.md). Se a saída da função for de um formato diferente, o API Gateway retorna uma resposta de erro `502 Bad Gateway`. Para retornar uma resposta em uma função do Lambda em Node.js, você poderá usar comandos como o seguinte: + Para retornar um resultado bem-sucedido, chame `callback(null, {"statusCode": 200, "body": "results"})`. + Para lançar uma exceção, chame `callback(new Error('internal server error'))`. + Para um erro no lado do cliente, (se, por exemplo, um parâmetro necessário estiver ausente), você poderá chamar `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` para retornar o erro sem lançar uma exceção. Em uma função do Lambda `async` no Node.js, a sintaxe equivalente seria: + Para retornar um resultado bem-sucedido, chame `return {"statusCode": 200, "body": "results"}`. + Para lançar uma exceção, chame `throw new Error("internal server error")`. + Para um erro no lado do cliente, (se, por exemplo, um parâmetro necessário estiver ausente), você poderá chamar `return {"statusCode": 400, "body": "Missing parameters of ..."}` para retornar o erro sem lançar uma exceção. # Configurar a integração de proxy do Lambda para o API Gateway usando a AWS CLI Nesta seção, mostramos como usar uma API com a integração de proxy do Lambda usando a AWS CLI. Para obter instruções detalhadas sobre como usar o console do API Gateway para configurar um recurso de proxy com a integração de proxy do Lambda, consulte [Tutorial: Crie uma API REST com uma integração de proxy do Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md). Como exemplo, usamos a seguinte função do Lambda como o backend da API: ``` export const handler = async(event, context) => { console.log('Received event:', JSON.stringify(event, null, 2)); var res ={ "statusCode": 200, "headers": { "Content-Type": "*/*" } }; var greeter = 'World'; if (event.greeter && event.greeter!=="") { greeter = event.greeter; } else if (event.body && event.body !== "") { var body = JSON.parse(event.body); if (body.greeter && body.greeter !== "") { greeter = body.greeter; } } else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") { greeter = event.queryStringParameters.greeter; } else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") { greeter = event.multiValueHeaders.greeter.join(" and "); } else if (event.headers && event.headers.greeter && event.headers.greeter != "") { greeter = event.headers.greeter; } res.body = "Hello, " + greeter + "!"; return res }; ``` Comparando isso à configuração de integração personalizada do Lambda em [Configurar integrações personalizadas do Lambda no API Gateway](set-up-lambda-custom-integrations.md), a entrada para essa função do Lambda pode ser expressa nos parâmetros da solicitação e no corpo. Você tem mais latitude para permitir que o cliente transmita os mesmos dados de entrada. Aqui, o cliente pode transmitir o nome do greeter como um parâmetro de string de consulta, um cabeçalho ou uma propriedade de corpo. A função também pode oferecer suporte à integração personalizada do Lambda. A configuração da API é mais simples. Você não configura a resposta de método nem a resposta de integração. **Como configurar uma integração de proxy do Lambda usando a AWS CLI** 1. Use o comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo para criar uma API: ``` aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' ``` A saída será exibida da seguinte forma: ``` { "name": "HelloWorldProxy (AWS CLI)", "id": "te6si5ach7", "rootResourceId" : "krznpq9xpg", "createdDate": 1508461860 } ``` A API `id` (`te6si5ach7`) e o `rootResourceId` (`krznpq9xpg`) são usados em todo este exemplo. 1. Use o comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) indicado abaixo para criar um [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting` do API Gateway: ``` aws apigateway create-resource \ --rest-api-id te6si5ach7 \ --parent-id krznpq9xpg \ --path-part {proxy+} ``` A saída será exibida da seguinte forma: ``` { "path": "/{proxy+}", "pathPart": "{proxy+}", "id": "2jf6xt", "parentId": "krznpq9xpg" } ``` Na próxima etapa, você usa o valor `id` (`2jf6xt`) do recurso `{proxy+}` para criar um método no recurso `/{proxy+}`. 1. Use o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo para criar uma solicitação de método `ANY` de `ANY /{proxy+}`: ``` aws apigateway put-method --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method ANY \ --authorization-type "NONE" ``` A saída será exibida da seguinte forma: ``` { "apiKeyRequired": false, "httpMethod": "ANY", "authorizationType": "NONE" } ``` Esse método de API permite que o cliente receba ou envie saudações da função do Lambda no backend. 1. Use o comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) indicado abaixo para configurar a integração do método `ANY /{proxy+}` com uma função do Lambda denominada `HelloWorld`. Essa função responde à solicitação com uma mensagem de `"Hello, {name}!"`, se o parâmetro `greeter` for fornecido ou `"Hello, World!"`, se o parâmetro de string de consulta não for definido. ``` aws apigateway put-integration \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method ANY \ --type AWS_PROXY \ --integration-http-method POST \ --uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \ --credentials arn:aws:iam::123456789012:role/apigAwsProxyRole ``` **Importante** Para integrações do Lambda, você deve usar o método HTTP de `POST` para a solicitação de integração, de acordo com a [especificação da ação do serviço do Lambda para invocações de função](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). A função do IAM de `apigAwsProxyRole` deve ter políticas que permitem ao serviço `apigateway` invocar funções do Lambda. Para obter mais informações sobre as permissões do IAM, consulte [Modelo de permissões do API Gateway para invocar uma API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api). A saída será exibida da seguinte forma: ``` { "passthroughBehavior": "WHEN_NO_MATCH", "cacheKeyParameters": [], "uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:1234567890:function:HelloWorld/invocations", "httpMethod": "POST", "cacheNamespace": "vvom7n", "credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole", "type": "AWS_PROXY" } ``` Em vez de fornecer um perfil do IAM para `credentials`, você pode usar o comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) para adicionar permissões baseadas em recurso. Isso é o que o console do API Gateway faz. 1. Use o comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) indicado abaixo para implantar a API em um estágio `test`: ``` aws apigateway create-deployment \ --rest-api-id te6si5ach7 \ --stage-name test ``` 1. Teste a API usando os seguintes comandos cURL em um terminal. Chamando a API com o parâmetro de string de consulta de `?greeter=jane`: ``` curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane' ``` Chamando a API com um parâmetro de cabeçalho de `greeter:jane`: ``` curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \ -H 'content-type: application/json' \ -H 'greeter: jane' ``` Chamando a API com um corpo de `{"greeter":"jane"}`: ``` curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \ -H 'content-type: application/json' \ -d '{ "greeter": "jane" }' ``` Em todos os casos, a saída é uma resposta 200 com o corpo de resposta a seguir: ``` Hello, jane! ``` # Configurar um recurso de proxy com a integração de proxy do Lambda com uma definição OpenAPI Para configurar um recurso de proxy com o tipo de integração de proxy do Lambda, crie um recurso de API com um parâmetro de caminho voraz (por exemplo, `/parent/{proxy+}`) e integre esse recurso a um backend da função do Lambda (por exemplo, `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource`) no método `ANY`. O parâmetro de caminho voraz deve estar no final do caminho do recurso da API. Como no caso de um recurso não proxy, é possível configurar o recurso de proxy usando o console do API Gateway, importando um arquivo de definição do OpenAPI ou chamando diretamente a API REST do API Gateway. O seguinte arquivo de definição de API do OpenAPI mostra um exemplo de uma API com um recurso de proxy que está integrado à função do Lambda chamada `SimpleLambda4ProxyResource`. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "parameters": [ { "name": "proxy", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "cacheNamespace": "roq9wj", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "aws_proxy" } } } }, "servers": [ { "url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/testStage" } } } ] } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "host": "gy415nuibc.execute-api.us-east-1.amazonaws.com", "basePath": "/testStage", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "cacheNamespace": "roq9wj", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "aws_proxy" } } } } } ``` ------ Na integração de proxy do Lambda, em tempo de execução, o API Gateway mapeia uma solicitação de entrada no parâmetro `event` de entrada da função do Lambda. A entrada inclui o método de solicitação, o caminho, os cabeçalhos, qualquer parâmetro de consulta, qualquer carga, o contexto associado e quaisquer variáveis de estágio definidas. O formato de entrada é explicado em [Formato de entrada de uma função do Lambda para integração de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Para o API Gateway mapear a saída do Lambda para respostas HTTP com êxito, a função do Lambda deve processar a saída do resultado no formato descrito em [Formato de saída de uma função do Lambda para integração de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format). Com a integração de proxy do Lambda de um recurso de proxy por meio do método `ANY`, a função do Lambda de backend única serve como o manipulador de eventos para todas as solicitações por meio do recurso de proxy. Por exemplo, para registrar padrões de tráfego, você pode fazer com que um dispositivo móvel envie suas informações de localização de estado, cidade, rua e edifício, enviando uma solicitação com `/state/city/street/house` no caminho da URL para o recurso de proxy. Dessa forma, a função do Lambda de backend pode analisar o caminho da URL e inserir as tuplas de localização em uma tabela do DynamoDB. # Configurar integrações personalizadas do Lambda no API Gateway Para mostrar como configurar a integração personalizada ou sem proxy do Lambda, criamos uma API do API Gateway para expor o método `GET /greeting?greeter={name}` para invocar uma função do Lambda. Use um dos exemplos de funções do Lambda a seguir para a API. Use um dos seguintes exemplos de funções do Lambda: ------ #### [ Node.js ] ``` 'use strict'; var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']; var times = ['morning', 'afternoon', 'evening', 'night', 'day']; export const handler = async(event) => { console.log(event); // Parse the input for the name, city, time and day property values let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name; let city = event.city === undefined ? 'World' : event.city; let time = times.indexOf(event.time)<0 ? 'day' : event.time; let day = days.indexOf(event.day)<0 ? null : event.day; // Generate a greeting let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. '; if (day) greeting += 'Happy ' + day + '!'; // Log the greeting to CloudWatch console.log('Hello: ', greeting); // Return a greeting to the caller return greeting; }; ``` ------ #### [ Python ] ``` import json def lambda_handler(event, context): print(event) res = { "statusCode": 200, "headers": { "Content-Type": "*/*" } } if event['greeter'] == "": res['body'] = "Hello, World" elif (event['greeter']): res['body'] = "Hello, " + event['greeter'] + "!" else: raise Exception('Missing the required greeter parameter.') return res ``` ------ A função responde com uma mensagem de `"Hello, {name}!"` se o valor do parâmetro `greeter` for uma string não vazia. Ela retornará uma mensagem de `"Hello, World!"` se o valor `greeter` for uma string vazia. A função retornará uma mensagem de erro de `"Missing the required greeter parameter."` se o parâmetro do greeter não estiver definido na solicitação de entrada. Atribuímos o nome à funçã `HelloWorld`. Ela pode ser criada no console do Lambda ou usando a AWS CLI. Nesta seção, fazemos referência a essa função usando o seguinte Nome de recurso da Amazon (ARN): ``` arn:aws:lambda:us-east-1:123456789012:function:HelloWorld ``` Com a função do Lambda definida no backend, configure a API. **Como configurar a integração personalizada do Lambda usando a AWS CLI** 1. Use o comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo para criar uma API: ``` aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' ``` A saída será exibida da seguinte forma: ``` { "name": "HelloWorld (AWS CLI)", "id": "te6si5ach7", "rootResourceId" : "krznpq9xpg", "createdDate": 1508461860 } ``` A API `id` (`te6si5ach7`) e o `rootResourceId` (`krznpq9xpg`) são usados em todo este exemplo. 1. Use o comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) indicado abaixo para criar um [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting` do API Gateway: ``` aws apigateway create-resource \ --rest-api-id te6si5ach7 \ --parent-id krznpq9xpg \ --path-part greeting ``` A saída será exibida da seguinte forma: ``` { "path": "/greeting", "pathPart": "greeting", "id": "2jf6xt", "parentId": "krznpq9xpg" } ``` Na próxima etapa, você usa o valor `id` (`2jf6xt`) do recurso `greeting` para criar um método no recurso `/greeting`. 1. Use o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo para criar uma solicitação de método de API de `GET /greeting?greeter={name}`: ``` aws apigateway put-method --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.querystring.greeter=false ``` A saída será exibida da seguinte forma: ``` { "apiKeyRequired": false, "httpMethod": "GET", "authorizationType": "NONE", "requestParameters": { "method.request.querystring.greeter": false } } ``` Esse método de API permite que o cliente receba uma saudação da função do Lambda no backend. O parâmetro `greeter` é opcional, pois o backend deve lidar com um autor da chamada anônimo ou um autor da chamada autoidentificado. 1. Use o comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) indicado abaixo para configurar a resposta `200 OK` à solicitação de método de `GET /greeting?greeter={name}`: ``` aws apigateway put-method-response \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --status-code 200 ``` 1. Use o comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) indicado abaixo para configurar a integração do método `GET /greeting?greeter={name}` com uma função do Lambda denominada `HelloWorld`. A função responde à solicitação com uma mensagem de `"Hello, {name}!"`, se o parâmetro `greeter` for fornecido ou `"Hello, World!"`, se o parâmetro de string de consulta não for definido. ``` aws apigateway put-integration \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --type AWS \ --integration-http-method POST \ --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \ --request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \ --credentials arn:aws:iam::123456789012:role/apigAwsProxyRole ``` O modelo de mapeamento fornecido aqui converte o parâmetro de string de consulta `greeter` na propriedade `greeter` da carga útil JSON. Isso é necessário porque a entrada para uma função do Lambda deve ser expressa no corpo. **Importante** Para integrações do Lambda, você deve usar o método HTTP de `POST` para a solicitação de integração, de acordo com a [especificação da ação do serviço do Lambda para invocações de função](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). O parâmetro `uri` é o Nome de recurso da Amazon (ARN) da ação de invocação da função. A saída será exibida da seguinte forma: ``` { "passthroughBehavior": "WHEN_NO_MATCH", "cacheKeyParameters": [], "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations", "httpMethod": "POST", "requestTemplates": { "application/json": "{\"greeter\":\"$input.params('greeter')\"}" }, "cacheNamespace": "krznpq9xpg", "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "type": "AWS" } ``` A função do IAM de `apigAwsProxyRole` deve ter políticas que permitem ao serviço `apigateway` invocar funções do Lambda. Em vez de fornecer uma função do IAM para `credentials`, você pode chamar o comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) para adicionar permissões baseadas em recurso. É assim que o console do API Gateway adiciona essas permissões. 1. Use o comando [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html) indicado abaixo para configurar a resposta de integração e transmitir a saída da função do Lambda ao cliente como a resposta de método `200 OK`. ``` aws apigateway put-integration-response \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --status-code 200 \ --selection-pattern "" ``` Ao definir o padrão de seleção como uma string vazia, a resposta `200 OK` é o padrão. A saída será exibida da seguinte forma: ``` { "selectionPattern": "", "statusCode": "200" } ``` 1. Use o comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) indicado abaixo para implantar a API em um estágio `test`: ``` aws apigateway create-deployment \ --rest-api-id te6si5ach7 \ --stage-name test ``` 1. Teste a API usando o seguinte comando cURL em um terminal: ``` curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \ -H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751' ``` # Configurar a invocação assíncrona da função do Lambda do backend Na integração não proxy do Lambda (personalizada), a função do Lambda do backend é invocada de forma síncrona por padrão. Este é o comportamento desejado para a maioria das operações da API REST. No entanto, alguns aplicativos exigem que o trabalho seja executado de forma assíncrona (como uma operação em lote ou uma operação de longa latência), normalmente por um componente de backend separado. Nesse caso, a função de backend do Lambda é invocada de forma assíncrona, o método da API REST do front-end não retorna o resultado. É possível configurar a função do Lambda para que uma integração não proxy do Lambda seja invocada de forma assíncrona especificando `'Event'` como o [tipo de invocação do ](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html). Isso é feito da seguinte forma: ## Configurar a invocação assíncrona do Lambda no console do API Gateway Para que todas as invocações sejam assíncronas: + Em **Solicitação de integração**, adicione um cabeçalho `X-Amz-Invocation-Type` com um valor estático de `'Event'`. Para que os clientes decidam se as invocações são assíncronas ou síncronas: 1. Em **Solicitação de método**, adicione um cabeçalho `InvocationType`. 1. Em **Solicitação de integração**, adicione um cabeçalho `X-Amz-Invocation-Type` com uma expressão de mapeamento de `method.request.header.InvocationType`. 1. Os clientes podem incluir o cabeçalho `InvocationType: Event` em solicitações de API para chamadas assíncronas ou `InvocationType: RequestResponse` para chamadas síncronas. ## Configurar a invocação assíncrona do Lambda usando o OpenAPI Para que todas as invocações sejam assíncronas: + Adicione o cabeçalho `X-Amz-Invocation-Type` à seção **x-amazon-apigateway-integration**. ``` "x-amazon-apigateway-integration" : { "type" : "aws", "httpMethod" : "POST", "uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.X-Amz-Invocation-Type" : "'Event'" }, "passthroughBehavior" : "when_no_match", "contentHandling" : "CONVERT_TO_TEXT" } ``` Para que os clientes decidam se as invocações são assíncronas ou síncronas: 1. Adicione o cabeçalho a seguir em qualquer [objeto de item de caminho do OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). ``` "parameters" : [ { "name" : "InvocationType", "in" : "header", "schema" : { "type" : "string" } } ] ``` 1. Adicione o cabeçalho `X-Amz-Invocation-Type` à seção **x-amazon-apigateway-integration**. ``` "x-amazon-apigateway-integration" : { "type" : "aws", "httpMethod" : "POST", "uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType" }, "passthroughBehavior" : "when_no_match", "contentHandling" : "CONVERT_TO_TEXT" } ``` 1. Os clientes podem incluir o cabeçalho `InvocationType: Event` em solicitações de API para chamadas assíncronas ou `InvocationType: RequestResponse` para chamadas síncronas. ## Configurar a invocação assíncrona do Lambda usando o CloudFormation Os modelos CloudFormation a seguir mostram como configurar o `AWS::ApiGateway::Method` para invocações assíncronas. Para que todas as invocações sejam assíncronas: ``` AsyncMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref AsyncResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: AWS RequestParameters: integration.request.header.X-Amz-Invocation-Type: "'Event'" IntegrationResponses: - StatusCode: '200' IntegrationHttpMethod: POST Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations MethodResponses: - StatusCode: '200' ``` Para que os clientes decidam se as invocações são assíncronas ou síncronas: ``` AsyncMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref AsyncResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE RequestParameters: method.request.header.InvocationType: false Integration: Type: AWS RequestParameters: integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType IntegrationResponses: - StatusCode: '200' IntegrationHttpMethod: POST Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations MethodResponses: - StatusCode: '200' ``` Os clientes podem incluir o cabeçalho `InvocationType: Event` em solicitações de API para chamadas assíncronas ou `InvocationType: RequestResponse` para chamadas síncronas. # Manipular erros do Lambda no API Gateway Para integrações personalizadas do Lambda, você deve mapear erros retornados pelo Lambda na resposta de integração para respostas de erro HTTP padrão para os seus clientes. Caso contrário, os erros do Lambda serão retornados como respostas `200 OK` por padrão, e o resultado não será intuitivo para os usuários da sua API. Existem dois tipos de erros que o Lambda pode retornar: erros padrão e erros personalizados. Na sua API, você deve lidar com eles de maneira diferente. Com a integração de proxy do Lambda, o Lambda precisa retornar uma saída com o seguinte formato: ``` { "isBase64Encoded" : "boolean", "statusCode": "number", "headers": { ... }, "body": "JSON string" } ``` Nessa saída, `statusCode` é normalmente `4XX` para um erro de cliente e `5XX` para um erro de servidor. O API Gateway lida com esses erros, mapeando o erro do Lambda para uma resposta de erro HTTP, de acordo com o especificad `statusCode`. Para que o API Gateway transmita o tipo de erro (por exemplo, `InvalidParameterException`) como parte da resposta ao cliente, a função do Lambda deve incluir um cabeçalho (por exemplo, `"X-Amzn-ErrorType":"InvalidParameterException"`) na propriedade `headers`. **Topics** + [Manipule erros padrão do Lambda no API Gateway](#handle-standard-errors-in-lambda-integration) + [Manipule erros personalizados do Lambda no API Gateway](#handle-custom-errors-in-lambda-integration) ## Manipule erros padrão do Lambda no API Gateway Um erro do AWS Lambda padrão tem o seguinte formato: ``` { "errorMessage": "string", "errorType": "string", "stackTrace": [ "string", ... ] } ``` Aqui, `errorMessage` é uma expressão de string do erro. O `errorType` é um erro ou tipo de exceção que depende da linguagem. O `stackTrace` é uma lista de expressões de string que mostra o rastreamento de pilha que leva à ocorrência do erro. Por exemplo, considere a seguinte função do Lambda do JavaScript (Node.js). ``` export const handler = function(event, context, callback) { callback(new Error("Malformed input ...")); }; ``` Essa função retorna o seguinte erro padrão do Lambda, contendo `Malformed input ...` como a mensagem de erro: ``` { "errorMessage": "Malformed input ...", "errorType": "Error", "stackTrace": [ "export const handler (/var/task/index.js:3:14)" ] } ``` Da mesma forma, considere a seguinte função do Lambda Python, que gera um `Exception` com a mesma mensagem de erro `Malformed input ...`. ``` def lambda_handler(event, context): raise Exception('Malformed input ...') ``` Essa função retorna o seguinte erro padrão do Lambda: ``` { "stackTrace": [ [ "/var/task/lambda_function.py", 3, "lambda_handler", "raise Exception('Malformed input ...')" ] ], "errorType": "Exception", "errorMessage": "Malformed input ..." } ``` Observe que os valores de propriedade `errorType` e `stackTrace` são dependentes da linguagem. O erro-padrão também se aplica a qualquer objeto de erro que seja uma extensão do objeto `Error` ou uma subclasse da classe `Exception`. Para mapear o erro padrão do Lambda para uma resposta de método, você deve primeiro decidir sobre um código de status HTTP para um determinado erro do Lambda. Depois, defina um padrão de expressão regular na propriedade `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` do recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) associado ao código de status HTTP especificado. No console do API Gateway, este `selectionPattern` é indicado como **regex de erro do Lambda** na seção **Resposta de integração**, abaixo de cada resposta de integração. **nota** O API Gateway usa regexes de estilo padrão de Java para o mapeamento de resposta. Para obter mais informações, consulte [Padrão](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) na documentação do Oracle. Por exemplo, use o comando [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html) indicado abaixo para definir uma nova expressão `selectionPattern`: ``` aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2 ``` Certifique-se de configurar também o código de erro correspondente (`400`) na [resposta do método](api-gateway-method-settings-method-response.md#setup-method-response-status-code). Caso contrário, o API Gateway lançará uma resposta de erro de configuração inválida em tempo de execução. **nota** No tempo de execução, o API Gateway corresponde a `errorMessage` do erro do Lambda em relação ao padrão da expressão regular na propriedade `selectionPattern`. Se houver uma correspondência, o API Gateway retornará o erro do Lambda como uma resposta HTTP do código de status HTTP correspondente. Se não houver correspondência, o API Gateway retornará o erro como uma resposta padrão ou lançará uma exceção de configuração inválida se não houver uma resposta padrão configurada. Definir o valor `selectionPattern` como `.*` para uma determinada resposta redefine essa resposta como a resposta padrão. Isso ocorre porque esse padrão de seleção corresponderá a todas as mensagens de erro, incluindo nulo, ou seja, qualquer mensagem de erro não especificado. O mapeamento resultante substitui o mapeamento padrão. Se você usar `.+` como o padrão de seleção para filtrar respostas, saiba que ele pode não corresponder a uma resposta que contém um caractere de nova linha (`\n`). Para atualizar um valor `selectionPattern` existente usando a AWS CLI, chame a operação [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) para substituir o valor do caminho `/selectionPattern` pela expressão regex especificada do padrão `Malformed*`​. Para definir a expressão `selectionPattern` usando o console do API Gateway, digite a expressão na caixa de texto **Regex de erro do Lambda** ao configurar ou atualizar uma resposta de integração de um código de status HTTP especificado. ## Manipule erros personalizados do Lambda no API Gateway Em vez do erro padrão descrito na seção anterior, o AWS Lambda permite retornar um objeto de erro personalizado como uma string JSON. O erro pode ser qualquer objeto JSON válido. Por exemplo, a seguinte função do Lambda do JavaScript (Node.js) retorna um erro personalizado: ``` export const handler = (event, context, callback) => { ... // Error caught here: var myErrorObj = { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } callback(JSON.stringify(myErrorObj)); }; ``` Você deve transformar o objeto `myErrorObj` em uma string JSON antes de chamar `callback` para sair da função. Caso contrário, `myErrorObj` será retornado como uma string de `"[object Object]"`. Quando um método da sua API é integrado com a função do Lambda anterior, o API Gateway recebe uma resposta de integração com a seguinte carga: ``` { "errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}" } ``` Como ocorre com qualquer resposta de integração, é possível transmitir essa resposta de erro em seu estado inalterado como a reposta do método. Outra opção é fazer com que um modelo de mapeamento transforme a carga útil em um formato diferente. Por exemplo, considere o seguinte modelo de mapeamento de corpo para uma resposta de método do código de status `500`: ``` { errorMessage: $input.path('$.errorMessage'); } ``` Esse modelo converte o corpo da resposta de integração que contém a string JSON no seguinte corpo de resposta de método. Esse corpo de resposta de método contém o objeto JSON de erro personalizado: ``` { "errorMessage" : { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } }; ``` Dependendo dos requisitos da sua API, talvez você precise transmitir algumas das propriedades do erro personalizado, ou todas elas, como parâmetros de cabeçalho da resposta de método. Isso pode ser feito aplicando os mapeamentos de erros personalizados do corpo da resposta de integração aos cabeçalhos da resposta de método. Por exemplo, a seguinte extensão do OpenAPI define um mapeamento das propriedades `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` e `errorMessage.trace` para os cabeçalhos `error_type`, `error_status`, `error_trace_function` e `error_trace`, respectivamente. ``` "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function", "method.response.header.error_status": "integration.response.body.errorMessage.httpStatus", "method.response.header.error_type": "integration.response.body.errorMessage.errorType", "method.response.header.error_trace": "integration.response.body.errorMessage.trace" }, ... } } } ``` Em tempo de execução, o API Gateway desserializa o parâmetro `integration.response.body` ao executar mapeamentos de cabeçalho. No entanto, essa desserialização aplica-se somente aos mapeamentos de corpo para cabeçalho de respostas de erro personalizado do Lambda, e não a mapeamentos de corpo para corpo usando `$input.body`. Com esses mapeamentos de corpo para cabeçalho de erro personalizado, o cliente recebe os seguintes cabeçalhos como parte da resposta de método, desde que os cabeçalhos `error_status`, `error_trace`, `error_trace_function` e `error_type` estejam declarados na solicitação do método. ``` "error_status":"500", "error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}", "error_trace_function":"abc()", "error_type":"InternalServerError" ``` A propriedade `errorMessage.trace` do corpo da resposta de integração é uma propriedade complexa. Ela é mapeada para o cabeçalho `error_trace` como uma string JSON. # Integrações de HTTP para APIs REST no API Gateway Você pode integrar um método de API com um endpoint HTTP usando a integração de proxy ou a integração personalizada HTTP. O API Gateway oferece suporte às seguintes portas endpoint: 80, 443 e 1024-65535. Com a integração de proxy, a configuração é simples. Você só precisa definir o método HTTP e o URI de endpoint HTTP de acordo com os requisitos de backend, se você não estiver preocupado com a codificação de conteúdo nem o armazenamento em cache. Com a integração personalizada, a configuração é mais complexa. Além das etapas de configuração da integração de proxy, você precisa especificar como os dados da solicitação de entrada serão mapeados para a solicitação de integração e como os dados da resposta de integração resultante serão mapeados para a resposta do método. **Topics** + [Configurar integrações de proxy HTTP no API Gateway](#api-gateway-set-up-http-proxy-integration-on-proxy-resource) + [Configurar integrações personalizadas HTTP no API Gateway](#set-up-http-custom-integrations) ## Configurar integrações de proxy HTTP no API Gateway Para configurar um recurso de proxy com o tipo de integração de proxy HTTP, crie um recurso de API com um parâmetro de caminho voraz (por exemplo, `/parent/{proxy+}`) e integre esse recurso a um endpoint de backend 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. Como no caso de um recurso não proxy, é possível configurar um recurso de proxy com a integração de proxy HTTP usando o console do API Gateway, importando um arquivo de definição do OpenAPI ou chamando diretamente a API REST do API Gateway. Para obter instruções detalhadas sobre como usar o console do API Gateway para configurar um recurso de proxy com a integração HTTP, consulte [Tutorial: Crie uma API REST com uma integração de proxy de HTTP](api-gateway-create-api-as-simple-proxy-for-http.md). O seguinte arquivo de definição do OpenAPI mostra um exemplo de uma API com um recurso de proxy que está integrado ao site [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets). ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-09-12T23:19:28Z", "title": "PetStoreWithProxyResource" }, "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "parameters": [ { "name": "proxy", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.proxy": "method.request.path.proxy" }, "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}", "passthroughBehavior": "when_no_match", "httpMethod": "ANY", "cacheNamespace": "rbftud", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "http_proxy" } } } }, "servers": [ { "url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/test" } } } ] } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-09-12T23:19:28Z", "title": "PetStoreWithProxyResource" }, "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com", "basePath": "/test", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.proxy": "method.request.path.proxy" }, "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}", "passthroughBehavior": "when_no_match", "httpMethod": "ANY", "cacheNamespace": "rbftud", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "http_proxy" } } } } } ``` ------ Neste exemplo, uma chave de cache é declarada no parâmetro de caminho `method.request.path.proxy` do recurso de proxy. Esta é a configuração padrão quando você cria a API usando o console do API Gateway. O caminho base da API (`/test`, correspondente a um estágio) é mapeado para a página PetStore do site (`/petstore`). A solicitação de integração única espelha o site PetStore inteiro usando a variável de caminho voraz da API e o método genérico `ANY`. Os exemplos a seguir ilustram esse espelhamento. + **Defina `ANY` como `GET` e `{proxy+}` como `pets`** Solicitação de método iniciada no front-end: ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1 ``` Solicitação de integração enviada ao backend: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1 ``` As instâncias de tempo de execução do método `ANY` e o recurso de proxy são ambos válidos. A chamada retorna uma resposta `200 OK` com a carga que contém o primeiro lote de animais de estimação, conforme retornado do backend. + **Defina `ANY` como `GET` e `{proxy+}` como `pets?type=dog`** ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1 ``` Solicitação de integração enviada ao backend: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1 ``` As instâncias de tempo de execução do método `ANY` e o recurso de proxy são ambos válidos. A chamada retorna uma resposta `200 OK` com a carga que contém o primeiro lote de cães especificados, conforme retornado do backend. + **Defina `ANY` como `GET` e `{proxy+}` como `pets/{petId}`** Solicitação de método iniciada no front-end: ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1 ``` Solicitação de integração enviada ao backend: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1 ``` As instâncias de tempo de execução do método `ANY` e o recurso de proxy são ambos válidos. A chamada retorna uma resposta `200 OK` com a carga que contém o animal de estimação especificado, conforme retornado do backend. + **Defina `ANY` como `POST` e `{proxy+}` como `pets`** Solicitação de método iniciada no front-end: ``` POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 } ``` Solicitação de integração enviada ao backend: ``` POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 } ``` As instâncias de tempo de execução do método `ANY` e o recurso de proxy são ambos válidos. A chamada retorna uma resposta `200 OK` com a carga que contém o animal de estimação recém-criado, conforme retornado do backend. + **Defina `ANY` como `GET` e `{proxy+}` como `pets/cat`** Solicitação de método iniciada no front-end: ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat ``` Solicitação de integração enviada ao backend: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat ``` A instância de runtime do caminho do recurso de proxy não corresponde a um endpoint de backend, e a solicitação resultante é inválida. Como resultado, uma resposta `400 Bad Request` é retornada com a seguinte mensagem de erro. ``` { "errors": [ { "key": "Pet2.type", "message": "Missing required field" }, { "key": "Pet2.price", "message": "Missing required field" } ] } ``` + **Defina `ANY` como `GET` e `{proxy+}` como `null`** Solicitação de método iniciada no front-end: ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test ``` Solicitação de integração enviada ao backend: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets ``` O recurso direcionado é o pai do recurso de proxy, mas a instância de tempo de execução do método `ANY` não está definida na API nesse recurso. Como resultado, essa solicitação `GET` retorna uma resposta `403 Forbidden` com a mensagem de erro `Missing Authentication Token` retornada pelo API Gateway. Se a API expõe o método `ANY` ou `GET` no recurso pai, (`/`), a chamada retorna uma resposta `404 Not Found` com a mensagem `Cannot GET /petstore` conforme retornada do backend. Para qualquer solicitação de cliente, se a URL do endpoint de destino for inválida ou se o verbo HTTP for válido, mas não tiver suporte, o backend retornará uma resposta `404 Not Found`. Para um método HTTP sem suporte, uma resposta `403 Forbidden` é retornada. ## Configurar integrações personalizadas HTTP no API Gateway Com a integração HTTP personalizada, também conhecida como integração sem proxy, você tem mais controle de quais dados passar entre um método de API e uma integração de API e como passar os dados. Isso é feito pelo mapeamento de dados. Como parte da configuração da solicitação do método, defina a propriedade [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#requestParameters) em um recurso [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). Isso declara quais parâmetros da solicitação do método, que são provisionados pelo cliente, devem ser mapeados para os parâmetros da solicitação de integração ou para as propriedades do corpo aplicáveis antes de serem enviados para o backend. Depois, como parte da configuração da solicitação de integração, defina a propriedade [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestParameters) no recurso [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) correspondente para especificar os mapeamentos entre parâmetros. Você também define a propriedade [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestTemplates) para especificar modelos de mapeamento, um para cada tipo de conteúdo com suporte. Os modelos de mapeamento mapeiam o corpo ou os parâmetros da solicitação do método ao corpo da solicitação da integração. De forma similar, como parte da configuração da resposta do método, você define a propriedade [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) no recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). Isso declara quais parâmetros de resposta do método, a serem enviados ao cliente, devem ser mapeados dos parâmetros da resposta de integração ou de determinadas propriedades do corpo aplicáveis que foram retornadas do backend. Depois, você configura o [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) para escolher uma resposta de integração com base na resposta do backend. Para uma integração HTTP sem proxy, isso é uma expressão regular. Por exemplo, para mapear todos os códigos de status de resposta HTTP 2xx de um endpoint HTTP para esse mapeamento de saída, use `2\d{2}`. **nota** O API Gateway usa regexes de estilo padrão de Java para o mapeamento de resposta. Para obter mais informações, consulte [Padrão](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) na documentação do Oracle. Depois, como parte da configuração da resposta de integração, defina a propriedade [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseParameters) no recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) correspondente para especificar os mapeamentos entre parâmetros. Você também define o mapa [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseTemplates) para especificar modelos de mapeamento, um para cada tipo de conteúdo com suporte. Os modelos de mapeamento mapeiam os parâmetros da resposta de integração ou as propriedades do corpo da resposta de integração ao corpo da resposta do método. Para obter mais informações sobre como configurar modelos de mapeamento, consulte [Transformações de dados para APIs REST no API Gateway](rest-api-data-transformations.md). # Transmitir a resposta para suas integrações de proxy no API Gateway É possível configurar sua integração de proxy para controlar como o API Gateway exibe sua resposta de integração. Por padrão, o API Gateway espera receber a resposta completa antes de iniciar a transmissão. No entanto, se você definir o modo de transferência de resposta da sua integração como `STREAM`, o API Gateway vai esperar uma resposta ser completamente calculada antes de enviá-la ao cliente. O streaming de resposta funciona para todos os tipos de endpoints da API REST. Use o streaming de resposta para os seguintes casos de uso: + Reduzir o tempo até o primeiro byte (TTFB) para aplicações de IA generativa, como chatbots. + Transmitir arquivos grandes de imagem, vídeo ou música sem utilizar um URL pré-assinado do S3. + Realizar operações de longa duração enquanto relata o progresso incremental, como eventos enviados pelo servidor (SSE). + Exceder o limite de carga útil de resposta de 10 MB do API Gateway. + Exceder o limite de tempo limite de 29 segundos do API Gateway sem solicitar aumento do tempo limite de integração. + Receber uma carga útil binária sem configurar os tipos de mídia binária. ## Considerações sobre streaming de carga útil de resposta As seguintes considerações podem afetar o uso de streaming de carga útil de resposta: + Você só pode usar streaming de carga útil de resposta para os tipos de integração `HTTP_PROXY` ou `AWS_PROXY`. Isso inclui integrações de proxy do Lambda e integrações privadas que utilizem integrações `HTTP_PROXY`. + A configuração padrão do modo de transferência é `BUFFERED`. Para usar o streaming de resposta, você deve alterar o modo de transferência de resposta para `STREAM`. + O streaming de resposta só aceita APIs REST. + A solicitação de streaming não é aceita. + Você pode transmitir sua resposta por até 15 minutos. + Seus fluxos estão sujeitos a tempos limite de inatividade. No caso de endpoints regionais ou privados, o tempo limite é de 5 minutos. Em relação a endpoints otimizados para borda, o tempo limite é de 30 segundos. + Se você usar streaming de resposta para uma API REST regional com sua própria distribuição do CloudFront, poderá atingir um tempo limite de inatividade superior a 30 segundos aumentando o tempo limite de resposta da sua distribuição do CloudFront. Para acessar mais informações, consulte [Tempo limite de resposta](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesOrigin.html#DownloadDistValuesOriginResponseTimeout). + Quando o modo de transferência de resposta está definido como`STREAM`, o API Gateway não comporta recursos que exijam o armazenamento em buffer de toda a resposta da integração. Por esse motivo, os seguintes recursos não comportam o streaming de respostas: + Cache de endpoints + Codificação de conteúdo. Se você quiser compactar sua resposta de integração, faça isso em sua integração. + Transformação de resposta com VTL + Em cada resposta de streaming, os primeiros 10 MB de carga útil de resposta não estão sujeitos a nenhuma restrição de largura de banda. Os dados de carga útil de resposta que excedem 10 MB ficam restritos a 2 MB/s. + Quando a conexão entre o cliente e o API Gateway ou entre o API Gateway e o Lambda é fechada devido ao tempo limite, a função do Lambda pode continuar sendo executada. Para acessar mais informações, consulte [Configurar tempo limite das funções do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). + O streaming de resposta gera um custo. Para obter mais informações, consulte [Preços do API Gateway](https://aws.amazon.com/api-gateway/pricing/). # Configurar uma integração de proxy HTTP com streaming de resposta de carga útil no API Gateway Ao configurar o streaming de carga útil de resposta, você especifica o modo de transferência de resposta na solicitação de integração do seu método. Você precisa definir essas configurações na solicitação de integração a fim de controlar como o API Gateway se comporta antes e durante a resposta de integração. Quando você utiliza o streaming de resposta, pode configurar o tempo limite de integração como até 15 minutos. Quando você usa o streaming de resposta de carga útil com uma integração `HTTP_PROXY`, o API Gateway não envia o código de status da resposta HTTP nem o cabeçalho de resposta HTTP até receber integralmente todos os cabeçalhos. ## Configurar uma integração de proxy HTTP com streaming de resposta de carga útil O procedimento a seguir mostra como importar uma nova API com o `responseTransferMode` definido como `STREAM`. Se você tiver uma API de integração existente e quiser modificar o `responseTransferMode`, consulte [Atualizar o modo de transferência de resposta para uma integração de proxy HTTP](#response-streaming-http-update). ------ #### [ Console de gerenciamento da AWS ] **Como configurar uma integração de proxy HTTP com streaming de resposta de carga útil** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Selecione **Criar recurso**. 1. Em **Resource Name (Nome do recurso)**, insira **streaming**. 1. Selecione **Criar recurso**. 1. Com o recurso **/streaming** selecionado, escolha **Criar método**. 1. Em **Tipo de método**, selecione **ANY**. 1. Em **Tipo de integração**, escolha **HTTP**. 1. Selecione **Integração de proxy HTTP**. 1. Em **Modo de transferência de resposta**, selecione **Fluxo**. 1. Em **Método HTTP**, escolha um método. 1. Em **URL do endpoint**, insira um endpoint de integração. Escolha um endpoint que produza uma grande carga útil para ser transmitida de volta para você. 1. Escolha **Criar método**. Depois de criar o método, implante a API. **Para implantar sua API** 1. Escolha **Implantar API**. 1. Em **Estágio**, selecione **Novo estágio**. 1. Em **Stage name (Nome do estágio)**, insira **prod**. 1. (Opcional) Em **Description (Descrição)**, insira uma descrição. 1. Escolha **Implantar**. ------ #### [ AWS CLI ] **Como criar uma API com streaming de resposta de carga útil** 1. Copie o arquivo Open API a seguir e, depois, salve-o como `ResponseStreamDemoSwagger.yaml`. Nesse arquivo, `responseTransferMode` está definido como `STREAM`. O endpoint de integração está definido como `https://example.com`, mas recomendamos que você o modifique para um endpoint que produza uma grande carga útil a ser transmitida de volta para você. ``` openapi: "3.0.1" info: title: "ResponseStreamingDemo" version: "2025-04-28T17:28:25Z" servers: - url: "{basePath}" variables: basePath: default: "prod" paths: /streaming: get: x-amazon-apigateway-integration: httpMethod: "GET" uri: "https://example.com" type: "http_proxy" timeoutInMillis: 900000 responseTransferMode: "STREAM" ``` 1. Utilize o seguinte comando `import-rest-api` para importar sua definição de OpenAPI: ``` aws apigateway import-rest-api \ --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \ --parameters endpointConfigurationTypes=REGIONAL \ --region us-west-1 ``` 1. Utilize o seguinte comando `create-deployment` para implantar a nova API em um estágio: ``` aws apigateway create-deployment \ --rest-api-id a1b2c3 \ --stage-name prod \ --region us-west-1 ``` ------ ## Atualizar o modo de transferência de resposta para uma integração de proxy HTTP O procedimento a seguir mostra como atualizar o modo de transferência de resposta para uma integração de proxy HTTP. ------ #### [ Console de gerenciamento da AWS ] **Como atualizar o modo de transferência de resposta para uma integração de proxy HTTP** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Escolha um método. 1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**. 1. Em **Modo de transferência de resposta**, selecione **Fluxo**. 1. Escolha **Salvar**. Depois de atualizar o método, implante a API. **Para implantar sua API** 1. Escolha **Implantar API**. 1. Em **Estágio**, selecione **Novo estágio**. 1. Em **Stage name (Nome do estágio)**, insira **prod**. 1. (Opcional) Em **Description (Descrição)**, insira uma descrição. 1. Escolha **Implantar**. ------ #### [ AWS CLI ] O comando `update-integration` a seguir atualiza o modo de transferência de uma integração de `BUFFERED` para `STREAM`. Para todas as APIs existentes, o modo de transferência de resposta para todas as integrações está definido como `BUFFERED`. ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method GET \ --patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \ --region us-west-1 ``` Será necessário implantar a API novamente para que as alterações sejam implementadas. Se você personalizou o tempo limite de integração, esse valor de tempo limite será removido, pois o API Gateway transmite sua resposta por até 5 minutos. O seguinte comando `update-integration` atualiza o modo de transferência de uma integração de `STREAM` para `BUFFERED`. ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method GET \ --patch-operations "op='replace',path='/responseTransferMode',value=BUFFERED" \ --region us-west-1 ``` Será necessário implantar a API novamente para que as alterações sejam implementadas. ------ # Configurar uma integração de proxy do Lambda com streaming de resposta da carga útil no API Gateway É possível realizar o streaming da resposta de uma função do Lambda para melhorar a performance do tempo até o primeiro byte (TTFB) e enviar respostas parciais de volta ao cliente assim que elas se tornam disponíveis. O API Gateway exige que você use a API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) do Lambda para invocar sua função do Lambda. O API Gateway transmite um objeto de evento para a função do Lambda. A função do Lambda do backend analisa os dados da solicitação recebida para determinar a resposta que ela retorna. Para o API Gateway transmitir a saída do Lambda, a função do Lambda deve gerar o [formato](#response-transfer-mode-lambda-format) exigido pelo API Gateway. ## Diferenças nas integrações de proxy do Lambda entre o modo de transferência de fluxo e resposta em buffer A lista a seguir descreve as diferenças entre uma integração do proxy do Lambda e uma integração do proxy do Lambda para streaming de resposta: + O API Gateway utiliza a API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) para invocar a integração do proxy do Lambda para streaming de respostas. Isso gera um URI diferente, que é o seguinte: ``` arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations ``` Esse ARN utiliza uma data diferente para a versão da API e uma ação de serviço diferente em comparação à integração do proxy do Lambda. Se você utiliza o console do API Gateway para streaming de respostas, o console usa o URI correto para você. + Em uma integração do proxy do Lambda, o API Gateway envia a resposta ao cliente somente depois de receber a resposta completa do Lambda. Em uma integração do proxy do Lambda para streaming de resposta, o API Gateway inicia o fluxo de carga útil depois de receber os metadados e o delimitador válidos do Lambda. + A integração do proxy do Lambda para streaming de respostas utiliza o mesmo formato de entrada que o da integração de proxy, mas exige um formato de saída diferente. ## Formato de integração do proxy do Lambda para streaming de resposta Quando o API Gateway invoca uma função do Lambda com streaming de resposta, o formato de entrada é igual ao formato de entrada de uma função do Lambda para integração de proxy. Para obter mais informações, consulte [Formato de entrada de uma função do Lambda para integração de proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Quando o Lambda transmite uma resposta para o API Gateway, ela deve seguir o formato a seguir. Esse formato utiliza um delimitador para separar o JSON dos metadados e a carga útil bruta. Nesse caso, os dados da carga útil são transmitidos no decorrer do streaming realizado pela função de streaming do Lambda: ``` { "headers": {"headerName": "headerValue", ...}, "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... }, "cookies" : ["cookie1", "cookie2"], "statusCode": httpStatusCode }PAYLOAD1 | PAYLOAD2 | PAYLOAD3 ``` Na saída: + As chaves `headers`, `multiValueHeaders`, `cookies` e `statusCode` poderão ficar sem especificação se nenhum cabeçalho de resposta extra precisar ser exibido. + A chave `headers` só pode conter cabeçalhos de valor único. + A saída espera que os cabeçalhos contenham `Transfer-Encoding: chunked` ou `Content-length: number`. Se sua função não exibir nenhum desses cabeçalhos, o API Gateway anexará `Transfer-Encoding: chunked` ao cabeçalho de resposta. + A chave `multiValueHeaders` pode conter cabeçalhos de vários valores e cabeçalhos de valor único. Você pode usar a chave `multiValueHeaders` para especificar todos os seus cabeçalhos extras, incluindo os de valor único. + Se você especificar valores para `headers` e `multiValueHeaders`, o API Gateway os mesclará em uma única lista. Se o mesmo de chave/valor for especificado em ambos, somente os valores de `multiValueHeaders` aparecerão na lista mesclada. + Os metadados devem ser JSON válido. Somente as chaves `headers`, `multiValueHeaders`, `cookies` e `statusCode` são aceitas. + Você deve fornecer um delimitador após o JSON dos metadados. O delimitador deve ter 8 bytes nulos e deve aparecer nos primeiros 16 KB de dados do fluxo. + O API Gateway não exige um formato específico para a carga útil de resposta do método. Se você estiver usando um URL de função para transmitir sua função do Lambda, deverá modificar a entrada e a saída da sua função do Lambda para atender a esses requisitos. Se a saída da função do Lambda não atender aos requisitos desse formato, o API Gateway ainda poderá invocar sua função do Lambda. A tabela a seguir mostra as combinações das configurações de solicitação de integração da API e do código da função do Lambda que comportam o API Gateway. Isso inclui combinações aceitas pelo modo de transferência de resposta em buffer. | Modo de transferência de resposta | O código da função segue o formato exigido | API de invocação do Lambda | Aceito pelo API Gateway. | | --- | --- | --- | --- | | Fluxo | Sim | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Sim. O API Gateway transmite sua resposta. | | Fluxo | Não | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Não. O API Gateway invocará a função do Lambda e exibirá uma resposta de erro de 500. | | Fluxo | Sim | [Invocar](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Não. O API Gateway não aceita essa configuração de integração. | | Fluxo | Não | [Invocar](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Não. O API Gateway não aceita essa configuração de integração. | | Armazenado em buffer | Sim | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Não. O API Gateway não aceita essa configuração de integração. | | Armazenado em buffer | Não | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Não. O API Gateway não aceita essa configuração de integração. | | Armazenado em buffer | Sim | [Invocar](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | O API Gateway exibe os cabeçalhos HTTP e o código de status, mas não o corpo da resposta. | | Armazenado em buffer | Não | [Invocar](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Sim. Esta é uma integração do proxy do Lambda. Para acessar mais informações, consulte [Integração do proxy do Lambda](set-up-lambda-proxy-integrations.md). | # Configurar uma integração de proxy do Lambda com streaming de resposta da carga útil no API Gateway Quando você configura o streaming de carga útil de resposta, especifica o modo de transferência na resposta de integração do seu recurso. Você precisa definir essas configurações na solicitação de integração a fim de controlar como o API Gateway se comporta antes e durante a resposta de integração. ## Exemplos de função do Lambda para streaming de resposta A sua função do Lambda deve seguir o [Formato de integração do proxy do Lambda para streaming de resposta](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format). Recomendamos que você use um dos três exemplos de funções do Lambda para testar o streaming de respostas. Ao criar a função do Lambda, faça o seguinte: + Forneça um tempo limite adequado para sua função. Recomendamos que você configure um tempo limite de pelo menos 1 minuto para saber mais sobre o streaming de respostas. Ao criar seus recursos de produção, garanta que o tempo limite da função do Lambda abranja todo o ciclo de solicitações. Para acessar mais informações, consulte [Configurar tempo limite das funções do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). + Use o runtime mais recente do Node.js. + Use uma região onde o streaming de respostas do Lambda esteja disponível. ------ #### [ Using HttpResponseStream.from ] O exemplo de código a seguir transmite os objetos e cargas úteis de metadados JSON de volta para o cliente utilizando o método `awslambda.HttpResponseStream()` sem usar o método de pipeline. Não é necessário criar o delimitador. Para acessar mais informações, consulte [Escrever funções do Lambda habilitadas para streaming de resposta](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html). ``` export const handler = awslambda.streamifyResponse( async (event, responseStream, context) => { const httpResponseMetadata = { "statusCode": 200, "headers": { "x-foo": "bar" }, "multiValueHeaders": { "x-mv1": ["hello", "world"], "Set-Cookie": ["c1=blue", "c2=red"] } }; responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata); await new Promise(r => setTimeout(r, 1000)); // synthetic delay responseStream.write("First payload "); await new Promise(r => setTimeout(r, 1000)); // synthetic delay responseStream.write("Final payload"); responseStream.end(); }); ``` ------ #### [ Using the pipeline method ] O Lambda recomenda que, ao escrever funções habilitadas para streaming de resposta, você use o decorador `awslambda.streamifyResponse()` fornecido pelos runtimes nativos do Node.js e o método `pipeline()`. Quando você utiliza o método de pipeline, não precisa criar o delimitador. O Lambda faz isso para você. Para acessar mais informações, consulte [Escrever funções do Lambda habilitadas para streaming de resposta](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html). O exemplo de código a seguir transmite os objetos e cargas úteis de metadados JSON de volta para o cliente. ``` import { pipeline } from 'node:stream/promises'; import { Readable } from 'node:stream'; export const handler = awslambda.streamifyResponse( async (event, responseStream, context) => { const httpResponseMetadata = { statusCode: 200, headers: { "Content-Type": "text/plain", "X-Custom-Header": "Example-Custom-Header" } }; responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata); const dataStream = Readable.from(async function* () { yield "FIRST payload\n"; await new Promise(r => setTimeout(r, 1000)); yield "SECOND payload\n"; await new Promise(r => setTimeout(r, 1000)); yield "THIRD payload\n"; await new Promise(r => setTimeout(r, 1000)); }()); await pipeline(dataStream, responseStream); } ); ``` ------ #### [ Without using the pipeline method ] O exemplo de código a seguir transmite os objetos e cargas úteis de metadados JSON de volta para o cliente sem utilizar o método `awslambda.HttpResponseStream()`. Sem o método `awslambda.HttpResponseStream()`, você deve incluir um delimitador de 8 bytes nulos entre os metadados e a carga útil. ``` export const handler = awslambda.streamifyResponse(async (event, response, ctx) => { response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}'); response.write("\x00".repeat(8)); // DELIMITER await new Promise(r => setTimeout(r, 1000)); response.write("FIRST payload"); await new Promise(r => setTimeout(r, 1000)); response.write("SECOND payload"); await new Promise(r => setTimeout(r, 1000)); response.write("FINAL payload"); response.end(); }); ``` ------ ## Criar uma integração de proxy do Lambda com streaming de resposta da carga útil O procedimento a seguir mostra como criar uma integração do proxy do Lambda com streaming da resposta da carga útil. Use o exemplo da função do Lambda ou crie a sua própria. ------ #### [ Console de gerenciamento da AWS ] **Como criar uma integração do proxy do Lambda com streaming de resposta da carga útil** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Selecione **Criar recurso**. 1. Em **Resource Name (Nome do recurso)**, insira **streaming**. 1. Selecione **Criar recurso**. 1. Com o recurso **/streaming** selecionado, escolha **Criar método**. 1. Em **Tipo de método**, selecione **ANY**. 1. Em **Tipo de integração**, escolha **Lambda**. 1. Selecione **Integração de proxy do Lambda**. 1. Em **Modo de transferência de resposta**, selecione **Fluxo**. 1. Em **Função do Lambda**, escolha o nome da sua função do Lambda. O console do API Gateway utiliza automaticamente a API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) para invocar a função do Lambda. Você é responsável por escrever uma função do Lambda habilitada para streaming de resposta. Para ver um exemplo, consulte [Exemplos de função do Lambda para streaming de resposta](#response-streaming-lambda-example). 1. Escolha **Criar método**. Depois de criar o método, implante a API. **Para implantar sua API** 1. Escolha **Implantar API**. 1. Em **Estágio**, selecione **Novo estágio**. 1. Em **Stage name (Nome do estágio)**, insira **prod**. 1. (Opcional) Em **Description (Descrição)**, insira uma descrição. 1. Escolha **Implantar**. ------ #### [ AWS CLI ] O procedimento a seguir mostra como importar uma nova API com o `responseTransferMode` definido como `STREAM`. Se você tiver uma API de integração existente e quiser modificar o `responseTransferMode`, consulte [Atualizar o modo de transferência de resposta para uma integração de proxy do Lambda](#response-streaming-lambda-update). **Como criar uma API com streaming de resposta de carga útil** 1. Copie o arquivo Open API a seguir e, depois, salve-o como `ResponseStreamDemoSwagger.yaml`. Nesse arquivo, `responseTransferMode` é definido como `STREAM`, e o URI de integração é definido como `arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations`. Substitua o nome da função de `my-function` por uma função habilitada para streaming e substitua as credenciais por um perfil do IAM que tenha políticas que permitem que o serviço `apigateway` invoque funções do Lambda. ``` openapi: "3.0.1" info: title: "ResponseStreamingDemo" version: "2025-04-28T17:28:25Z" servers: - url: "{basePath}" variables: basePath: default: "prod" paths: /lambda: get: x-amazon-apigateway-integration: httpMethod: "POST" uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations" type: "aws_proxy" timeoutInMillis: 90000 responseTransferMode: "STREAM" credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role" ``` Em vez de fornecer um perfil do IAM para recuperar credenciais, você pode utilizar o comando `add-permission` para o Lambda adicionar permissões baseadas em recurso. 1. Utilize o seguinte comando `import-rest-api` para importar sua definição de OpenAPI: ``` aws apigateway import-rest-api \ --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \ --parameters endpointConfigurationTypes=REGIONAL \ --region us-west-1 ``` 1. Utilize o seguinte comando `create-deployment` para implantar a nova API em um estágio: ``` aws apigateway create-deployment \ --rest-api-id a1b2c2 \ --stage-name prod \ --region us-west-1 ``` ------ ### Atualizar o modo de transferência de resposta para uma integração de proxy do Lambda O procedimento a seguir mostra como atualizar o modo de transferência de resposta para uma integração de proxy do Lambda. Ao alterar o modo de transferência de resposta para streaming, atualize sua função do Lambda para que ela atenda aos requisitos de streaming de resposta. Use o exemplo da função do Lambda ou crie a sua própria. ------ #### [ Console de gerenciamento da AWS ] **Como atualizar o modo de transferência de resposta para uma integração do proxy do Lambda** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Escolha um método. 1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**. 1. Em **Modo de transferência de resposta**, selecione **Fluxo**. 1. Em **Função do Lambda**, escolha o nome da sua função do Lambda. 1. Escolha **Salvar**. Depois de atualizar o método, implante a API. **Para implantar sua API** 1. Escolha **Implantar API**. 1. Em **Estágio**, selecione **Novo estágio**. 1. Em **Stage name (Nome do estágio)**, insira **prod**. 1. (Opcional) Em **Description (Descrição)**, insira uma descrição. 1. Escolha **Implantar**. ------ #### [ AWS CLI ] 1. Atualize a função do Lambda para que seja habilitada para streaming. 1. Use o seguinte comando da AWS CLI para atualizar o URI de integração e o modo de transferência de resposta da sua integração: ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method ANY \ --patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \ --region us-west-1 ``` 1. Implante a API novamente para que as alterações entrem em vigor. ------ # Solucionar problemas com o streaming de respostas no API Gateway As diretrizes de solução de problemas a seguir podem ajudar a resolver problemas com suas APIs que utilizam streaming de resposta. ## Solução de problemas gerais Você pode usar o [TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html) a guia de teste do console para testar a resposta do fluxo. As seguintes considerações podem afetar o uso da invocação de teste para streaming de resposta: + Quando você testa seu método, o API Gateway armazena em buffer sua carga útil de resposta transmitida. Depois que qualquer uma das condições a seguir for atendida, o API Gateway exibirá uma resposta única contendo a carga útil armazenada em buffer: + A solicitação está completa + 35 segundos se passaram + Mais de 1 MB de carga útil de resposta foi armazenada em buffer + Se transcorrerem mais de 35 segundos antes que seu método exiba um status de resposta HTTP e todos os cabeçalhos, o status da resposta exibido em TestInvokeMethod será 0. + O API Gateway não produz nenhum log de execução. Depois de implantar sua API, você pode testar a resposta do fluxo utilizando um comando curl. É recomendável utilizar a opção `-i` de incluir cabeçalhos da resposta de protocolo na saída. Para ver os dados de resposta à medida que eles chegam, utilize a opção `--no-buffer`. ## Solucionar problemas de cURL Se você estiver testando uma integração e receber o erro `curl: (18) transfer closed with outstanding read data remaining`, verifique se o tempo limite da integração é longo o suficiente. Se você estiver usando uma função do Lambda, precisará atualizar o tempo limite de resposta dela. Para acessar mais informações, consulte [Configurar tempo limite das funções do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). ## Solução de problemas no uso do registro em log do acesso Você pode usar logs de acesso para o estágio da API REST a fim de registrar em log e solucionar problemas em seu fluxo de resposta. Além das variáveis existentes, você pode usar as seguintes variáveis de log de acesso: `$context.integration.responseTransferMode` O modo de transferência de resposta da integração. Ele pode ser `BUFFERED` ou `STREAMED`. `$context.integration.timeToAllHeaders` O tempo entre o momento em que o API Gateway estabelece a conexão de integração e o momento em que recebe todos os cabeçalhos de resposta de integração do cliente. `$context.integration.timeToFirstContent` O tempo entre o momento em que o API Gateway estabelece a conexão de integração e o momento em que recebe os primeiros bytes de conteúdo. `$context.integration.latency` ou `$context.integrationLatency` O momento em que o API Gateway estabelece a conexão de integração e o momento em que o fluxo de resposta de integração é concluído. A figura a seguir mostra como essas variáveis de log de acesso representam diferentes componentes de um fluxo de resposta. ![\[Variáveis de log de acesso para streaming de resposta no API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/response-streaming-figure.png) Para obter mais informações sobre os logs de acesso, consulte [Configurar o registro em log do CloudWatch para APIs REST no API Gateway](set-up-logging.md). Você também pode usar o X-Ray para monitorar seu fluxo de resposta. Para obter mais informações, consulte [Rastrear solicitações de usuário para APIs REST usando o X-Ray no API Gateway](apigateway-xray.md). # Integrações privadas para APIs REST no API Gateway Utilize uma integração privada para expor seus recursos HTTP/HTTPS em uma Amazon VPC para acesso por clientes fora da VPC. Isso estende o acesso a seus recursos privados da VPC além dos limites da VPC. Você pode controlar o acesso à sua API usando qualquer um dos [ métodos de autorização](apigateway-control-access-to-api.md) compatíveis com o API Gateway. Para criar uma integração privada, primeiro crie um link de VPC. O API Gateway aceita links da VPC V2 para APIs REST. Os links da VPC V2 permitem criar integrações privadas que conectam sua API REST aos Application Load Balancers sem utilizar um Network Load Balancer. O uso de um Application Load Balancer permite que você se conecte às aplicações baseadas em contêineres do Amazon ECS e a muitos outros backends. Os links da VPC V1 são considerados um tipo de integração legado. Embora sejam aceitos no API Gateway, recomendamos que você não crie outros links da VPC V1. ## 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, o link de VPC e a API REST. + Por padrão, o tráfego de integração privada usa o protocolo HTTP. Para usar HTTPS, especifique um [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri) que contenha um nome de servidor seguro, como `https://example.com:443/test`. + Em uma integração privada, o API Gateway inclui a parte do [estágio](set-up-stages.md) do endpoint da API na solicitação para seus recursos de backend. Por exemplo, se você solicitar o estágio `test` de uma API, o API Gateway incluirá `test/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](rest-api-parameter-mapping.md) para criar uma substituição para a variável `$context.requestOverride.path`. + Integrações privadas com AWS Cloud Map não são aceitas. **Topics** + [Considerações](#private-integrations-considerations) + [Configurar links da VPC V2 no API Gateway](apigateway-vpc-links-v2.md) + [Configurar uma integração privada](set-up-private-integration.md) + [Integração privada utilizando links da VPC V1 (legado)](vpc-links-v1.md) # Configurar links da VPC V2 no API Gateway Os links de VPC permitem criar integrações privadas que conectem suas rotas de API a recursos privados em uma VPC, como Application Load Balancers ou aplicações baseadas em contêiner do Amazon ECS. A integração privada usa um link de VPC V2 para encapsular conexões entre o API Gateway e os recursos de VPC desejados. Você pode reutilizar links da VPC em diferentes recursos e APIs. Quando um link de VPC é criado, o API Gateway cria e gerencia [interfaces de rede elásticas](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) para o link de VPC V2 em sua conta. Esse processo pode levar alguns minutos. Quando um link de VPC V2 está pronto para uso, seu estado faz a transição de `PENDING` para `AVAILABLE`. **nota** Se nenhum tráfego for enviado pelo link da VPC por 60 dias, ele se tornará `INACTIVE`. Quando um link de VPC está em um estado `INACTIVE`, o API Gateway exclui todas as interfaces de rede do link de VPC. Isso faz com que as solicitações de API que dependem do link da VPC falhem. Se as solicitações de API forem retomadas, o API Gateway provisionará as interfaces de rede novamente. Pode levar alguns minutos para criar as interfaces de rede e reativar o link da VPC. Você pode usar o status do link da VPC para monitorar o estado do link da VPC. ## Criar um link da VPC V2 usando a AWS CLI Para criar um link de VPC V2, todos os recursos envolvidos devem pertencer à mesma conta da AWS. O comando [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html) indicado abaixo cria um link de VPC: ``` aws apigatewayv2 create-vpc-link --name MyVpcLink \ --subnet-ids subnet-aaaa subnet-bbbb \ --security-group-ids sg1234 sg5678 ``` **nota** Os links da VPC V2 são imutáveis. Depois de criar um link de VPC V2, você não poderá alterar suas sub-redes ou grupos de segurança. ## Excluir um link da VPC V2 usando a AWS CLI O comando [delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html) indicado a seguir exclui um link de VPC. ``` aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123 ``` ## Disponibilidade por região Os links da VPC V2 são aceitos nas seguintes regiões e zonas de disponibilidade: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/apigateway-vpc-links-v2.html) # Configurar uma integração privada 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 da VPC V2](apigateway-vpc-links-v2.md) a ser usado e forneça o ARN de um Network Load Balancer ou um Application Load Balancer. Por padrão, o tráfego de integração privada usa o protocolo HTTP. Para usar HTTPS, especifique um [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri) que contenha um nome de servidor seguro, como `https://example.com:443/test`. Para ver um tutorial completo sobre como criar uma API REST com uma integração privada, consulte [Tutorial: Crie uma API REST com uma integração privada](getting-started-with-private-integration.md). ## Criar uma integração privada O procedimento a seguir mostra como criar uma integração privada que se conecte a um balanceador de carga utilizando um link da VPC V2. ------ #### [ Console de gerenciamento da AWS ] Para ver um tutorial sobre como criar uma integração privada, consulte [Tutorial: Crie uma API REST com uma integração privada](getting-started-with-private-integration.md). ------ #### [ AWS CLI ] O comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) indicado abaixo cria uma integração privada que se conecta a um balanceador de carga utilizando um link da VPC V2: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id aaa000 \ --integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \ --uri 'https://example.com:443/path' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id bbb111 ``` Em vez de fornecer diretamente o ID da conexão, você pode usar uma variável de estágio. Ao implantar a API em um estágio, você define o ID do link da VPC V2. O comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) a seguir cria uma integração privada utilizando uma variável de estágio para o ID do link da VPC V2: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id aaa000 \ --integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \ --uri 'https://example.com:443/path' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id "\${stageVariables.vpcLinkV2Id}" ``` Inclua aspas duplas na expressão da variável de estágio (\$1\$1stageVariables.vpcLinkV2Id\$1) e insira um caractere de escape para \$1. ------ #### [ OpenAPI ] Você pode configurar uma API com a integração privada importando o arquivo OpenAPI da API. As configurações são semelhantes às definições do OpenAPI de uma API com integrações de HTTP, com as seguintes exceções: + Você deve definir explicitamente `connectionType` como `VPC_LINK`. + Você deve definir explicitamente `connectionId` como o ID de um `VpcLinkV2` ou como uma variável de estágio que faça referência ao ID de um `VpcLinkV2`. + O parâmetro `uri` na integração privada aponta para um endpoint de HTTP/HTTPS na VPC, mas é usado para configurar o cabeçalho `Host` da solicitação de integração. + O parâmetro `uri` na integração privada com um endpoint de HTTPS na VPC é usado para verificar o nome de domínio mencionado em relação ao nome no certificado instalado no VPC endpoint. Você pode usar uma variável de estágio para fazer referência ao ID do `VpcLinkV2`. Ou você pode atribuir o valor do ID diretamente ao `connectionId`. O arquivo OpenAPI em formato JSON a seguir mostra um exemplo de API com um link de VPC referenciado por uma variável de estágio (`${stageVariables.vpcLinkIdV2}`): ``` { "swagger": "2.0", "info": { "version": "2017-11-17T04:40:23Z", "title": "MyApiWithVpcLinkV2" }, "host": "abcdef123.execute-api.us-west-2.amazonaws.com", "basePath": "/test", "schemes": [ "https" ], "paths": { "/": { "get": { "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } }, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "https://example.com:443/path", "passthroughBehavior": "when_no_match", "connectionType": "VPC_LINK", "connectionId": "${stageVariables.vpcLinkV2Id}", "integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011", "httpMethod": "GET", "type": "http_proxy" } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Atualizar uma integração privada O exemplo a seguir atualiza o link da VPC V2 para uma integração privada. ------ #### [ Console de gerenciamento da AWS ] **Como atualizar uma integração privada** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST com uma integração privada. 1. Escolha o recurso e o método que usa uma integração privada. 1. Na guia **Solicitação de integração** em **Configurações de solicitação de integração**, selecione **Editar**. 1. Você pode editar a configuração da sua integração privada. Se você estiver usando atualmente um link da VPC V1, poderá alterá-lo para um link da VPC V2. 1. Escolha **Salvar**. 1. Implante a API novamente para que as alterações entrem em vigor. ------ #### [ AWS CLI ] O seguinte comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) atualiza uma integração privada para usar um link da VPC V2: ``` aws apigateway update-integration \ --rest-api-id a1b2c3d4e5 \ --resource-id a1b2c3 \ --http-method GET \ --patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]" ``` ------ # Integração privada utilizando links da VPC V1 (legado) **nota** A implementação de integrações privadas a seguir utiliza links da VPC V1. Os links da VPC V1 são recursos legados. Recomendamos que você utilize [links da VPC V2 para APIs REST](apigateway-vpc-links-v2.md). Para criar uma integração privada, primeiro crie um link do Network Load Balancer. Seu Network Load Balancer deve ter um [listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) que envia solicitações para recursos em sua VPC. Para melhorar a disponibilidade da sua API, certifique-se de que o seu Network Load Balancer encaminhe o tráfego para recursos em mais de uma zona de disponibilidade na Região da AWS. Em seguida, você cria um link de VPC usado para conectar sua API e seu Network Load Balancer. Depois de criar um link de VPC, você cria integrações privadas para rotear o tráfego de sua API para recursos na VPC pelo link de VPC e pelo Network Load Balancer. O Network Load Balancer e a API devem pertencer à mesma Conta da AWS. **Topics** + [Configurar um Network Load Balancer para integrações privadas do API Gateway (legado)](set-up-nlb-for-vpclink-using-console.md) + [Conceder permissões para o API Gateway criar um link de VPC (legado)](grant-permissions-to-create-vpclink.md) + [Configurar uma API do API Gateway com integrações privadas usando a AWS CLI (legado)](set-up-api-with-vpclink-cli.md) + [Contas do API Gateway usadas para integrações privadas (legado)](set-up-api-with-vpclink-accounts.md) # Configurar um Network Load Balancer para integrações privadas do API Gateway (legado) **nota** A implementação de integrações privadas a seguir utiliza links da VPC V1. Os links da VPC V1 são recursos legados. Recomendamos que você utilize [links da VPC V2 para APIs REST](apigateway-vpc-links-v2.md). O procedimento a seguir descreve as etapas para configurar um Network Load Balancer (NLB) para as integrações privadas do API Gateway usando o console do Amazon EC2 e fornece referências para a obtenção de instruções detalhadas em cada etapa. Para cada VPC na qual você tem recursos, só é necessário configurar um NLB e um VPCLink. O NLB oferece suporte a vários [listeners](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) e [grupos de destino](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html) por NLB. É possível configurar cada serviço como um listener específico no NLB e usar um único VPCLink para se conectar ao NLB. Ao criar a integração privada no API Gateway, você define cada serviço usando a porta específica que é atribuída para cada serviço. Para obter mais informações, consulte [Tutorial: Crie uma API REST com uma integração privada](getting-started-with-private-integration.md). O Network Load Balancer e a API devem pertencer à mesma Conta da AWS. **Para criar um Network Load Balancer para a integração privada usando o console do API Gateway** 1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon EC2 em [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. Configure um servidor web em uma instância do Amazon EC2. Para ver um exemplo de configuração, consulte [Tutorial: Instalar um servidor web LAMP no Amazon Linux 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html). 1. Crie um Network Load Balancer, registre a instância do EC2 com um grupo de destino e adicione o grupo de destino a um listener do Network Load Balancer. Para obter detalhes, siga as instruções em [Conceitos básicos de Network Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html). 1. Após a criação do Network Load Balancer, faça o seguinte: 1. Anote o ARN do Network Load Balancer. Você precisará dele para criar um link de VPC no API Gateway para integrar a API aos recursos da VPC por trás do Network Load Balancer. 1. Desative a avaliação do grupo de segurança para o PrivateLink. + Para desativar a avaliação do grupo de segurança para o tráfego do PrivateLink usando o console, escolha a guia **Segurança** e **Editar**. Em **Configurações de segurança**, desmarque a opção **Aplicar regras de entrada ao tráfego do PrivateLink**. + Use o comando [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html) indicado abaixo para desativar a avaliação do grupo de segurança referente ao tráfego do PrivateLink: ``` aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \ --security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off ``` **nota** Não adicione nenhuma dependência aos CIDRs do API Gateway, pois elas podem ser alteradas sem aviso prévio. # Conceder permissões para o API Gateway criar um link de VPC (legado) **nota** A implementação de integrações privadas a seguir utiliza links da VPC V1. Os links da VPC V1 são recursos legados. Recomendamos que você utilize [links da VPC V2 para APIs REST](apigateway-vpc-links-v2.md). Para que possa criar e manter um link de VPC, você, ou um usuário em sua conta, deve ter as permissões para criar, excluir e visualizar as configurações de serviço do VPC endpoint, alterar as permissões de serviço do VPC endpoint e examinar os load balancers. Para conceder essas permissões, use as seguintes etapas. **Para conceder as permissões de criação, atualização e exclusão de um link da VPC** 1. Crie uma política do IAM semelhante a esta: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:POST", "apigateway:GET", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:us-east-1::/vpclinks", "arn:aws:apigateway:us-east-1::/vpclinks/*" ] }, { "Effect": "Allow", "Action": [ "elasticloadbalancing:DescribeLoadBalancers" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:CreateVpcEndpointServiceConfiguration", "ec2:DeleteVpcEndpointServiceConfigurations", "ec2:DescribeVpcEndpointServiceConfigurations", "ec2:ModifyVpcEndpointServicePermissions" ], "Resource": "*" } ] } ``` ------ Se você quiser habilitar a marcação para o link de VPC, permita as operações de marcação. Para obter mais informações, consulte [Permitir operações de marcação](apigateway-tagging-iam-policy.md#allow-tagging). 1. Crie ou escolha uma função do IAM e anexe a política anterior à função. 1. Atribua a função do IAM a si mesmo ou ao usuário em sua conta que está criando os links da VPC. # Configurar uma API do API Gateway com integrações privadas usando a AWS CLI (legado) **nota** A implementação de integrações privadas a seguir utiliza links da VPC V1. Os links da VPC V1 são recursos legados. Recomendamos que você utilize [links da VPC V2 para APIs REST](apigateway-vpc-links-v2.md). O tutorial a seguir mostra como usar a AWS CLI para criar um link de VPC e uma integração privada. Os seguintes pré-requisitos se aplicam: + É necessário ter um Network Load Balancer criado e configurado com a origem da VPC como o destino. Para obter mais informações, consulte [Configurar um Network Load Balancer para integrações privadas do API Gateway (legado)](set-up-nlb-for-vpclink-using-console.md). Isso deve ser feito na mesma Conta da AWS que a API. É necessário ter o ARN do Network Load Balancer para criar o link da VPC. + Para criar e gerenciar um `VpcLink`, é preciso ter permissões para criar um `VpcLink` na API. Não é necessário ter permissões para usar o `VpcLink`. Para obter mais informações, consulte [Conceder permissões para o API Gateway criar um link de VPC (legado)](grant-permissions-to-create-vpclink.md). **Para configurar uma API com a integração privada usando a AWS CLI** 1. Use o comando [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html) a seguir para criar um `VpcLink` para o Network Load Balancer especificado. ``` aws apigateway create-vpc-link \ --name my-test-vpc-link \ --target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef ``` A saída desse comando confirma o recebimento da solicitação e mostra o status `PENDING` da `VpcLink` que está sendo criada. ``` { "status": "PENDING", "targetArns": [ "arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef" ], "id": "gim7c3", "name": "my-test-vpc-link" } ``` Demora de 2 a 4 minutos para que o API Gateway conclua a criação do `VpcLink`. Quando a operação é concluída com êxito, o `status` é `AVAILABLE`. É possível verificar isso usando o comando [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html) indicado abaixo: ``` aws apigateway get-vpc-link --vpc-link-id gim7c3 ``` Se a operação falhar, você obterá o status `FAILED` e a `statusMessage` conterá uma mensagem de erro. Por exemplo, se você tentar criar um `VpcLink` com um Network Load Balancer que já esteja associado a um VPC endpoint, obterá a seguinte mensagem na propriedade `statusMessage`: ``` "NLB is already associated with another VPC Endpoint Service" ``` Depois que a `VpcLink` for criada com sucesso, você poderá criar uma API e integrá-la ao recurso da VPC por meio da `VpcLink`. Anote o valor de `id` do `VpcLink` recém-criado. Neste exemplo de saída, é `gim7c3`. Você precisará dele para configurar a integração privada. 1. Use o comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo para criar um recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) do API Gateway: ``` aws apigateway create-rest-api --name 'My VPC Link Test' ``` Anote o valor de `id` da `RestApi` e o valor de `rootResourceId` da `RestApi` no resultado obtido. Você precisa desse valor para executar outras operações na API. Em seguida, crie uma API com apenas um método `GET` no recurso raiz (`/`) e integre o método ao `VpcLink`. 1. Use o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo para criar o método `GET /`: ``` aws apigateway put-method \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --http-method GET \ --authorization-type "NONE" ``` Se você não usa a integração de proxy com o `VpcLink`, também deve configurar pelo menos uma resposta do método para o código de status `200`. Use a integração de proxy aqui. 1. Depois de criar o método `GET /`, você configura a integração. Em uma integração privada, use o parâmetro `connection-id` para fornecer o ID do `VpcLink`. É possível usar uma variável de estágio ou inserir diretamente o ID do `VpcLink`. O parâmetro `uri` não é usado para rotear solicitações para o endpoint, mas sim para configurar o cabeçalho do `Host` e para a validação do certificado. ------ #### [ Use the VPC link ID ] Use o comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) indicado abaixo para utilizar o ID do `VpcLink` diretamente na integração: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id gim7c3 ``` ------ #### [ Use a stage variable ] Use o comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) a seguir para fazer referência ao ID do link de VPC por meio de uma variável de estágio. Ao implantar a API em um estágio, você define o ID do link da VPC. ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id "\${stageVariables.vpcLinkId}" ``` Inclua aspas duplas na expressão da variável de estágio (`${stageVariables.vpcLinkId}`) e insira um caractere de escape para o caractere `$`. ------ A qualquer momento, também é possível atualizar a integração para alterar o `connection-id`. Use o comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) indicado abaixo para atualizar a integração: ``` aws apigateway update-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --http-method GET \ --patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]' ``` Certifique-se de usar uma lista JSON transformada em string como o valor do parâmetro `patch-operations`. Como você usou a integração de proxy privada, a API agora está pronta para implantação e execução de testes. 1. Se você usou a variável de estágio para definir o `connection-id`, precisará implantar a API para testá-la. Use o comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) indicado abaixo para implantar a API com uma variável de estágio: ``` aws apigateway create-deployment \ --rest-api-id abcdef123 \ --stage-name test \ --variables vpcLinkId=gim7c3 ``` Para atualizar a variável de estágio com um ID do `VpcLink` diferente (por exemplo, `asf9d7`), use o comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) indicado abaixo: ``` aws apigateway update-stage \ --rest-api-id abcdef123 \ --stage-name test \ --patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7' ``` Ao codificar a propriedade `connection-id` com o ID literal do `VpcLink`, não é necessário implantar a API para testá-la. Use o comando [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html) para testar a API antes que ela seja implantada. 1. Use o seguinte comando para invocar a API: ``` curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test ``` Também é possível inserir o URL de invocação da API em um navegador da web para visualizar o resultado. # Contas do API Gateway usadas para integrações privadas (legado) Os seguintes IDs de conta do API Gateway específicos da região são adicionados automaticamente ao serviço de VPC endpoint como `AllowedPrincipals` quando você cria um `VpcLink`. | **Região** | **ID da conta** | | --- | --- | | us-east-1 | 392220576650 | | us-east-2 | 718770453195 | | us-west-1 | 968246515281 | | us-west-2 | 109351309407 | | ca-central-1 | 796887884028 | | eu-west-1 | 631144002099 | | eu-west-2 | 544388816663 | | eu-west-3 | 061510835048 | | eu-central-1 | 474240146802 | | eu-central-2 | 166639821150 | | eu-north-1 | 394634713161 | | eu-south-1 | 753362059629 | | eu-south-2 | 359345898052 | | ap-northeast-1 | 969236854626 | | ap-northeast-2 | 020402002396 | | ap-northeast-3 | 360671645888 | | ap-southeast-1 | 195145609632 | | ap-southeast-2 | 798376113853 | | ap-southeast-3 | 652364314486 | | ap-southeast-4 | 849137399833 | | ap-south-1 | 507069717855 | | ap-south-2 | 644042651268 | | ap-east-1 | 174803364771 | | sa-east-1 | 287228555773 | | me-south-1 | 855739686837 | | me-central-1 | 614065512851 | # Simular integrações para APIs REST no API Gateway O Amazon API Gateway oferece suporte a integrações simuladas para métodos de API. Esse recurso permite que os desenvolvedores de API gerem respostas de API do API Gateway diretamente, sem necessidade de um backend de integração. Como desenvolvedor de API, você pode usar esse recurso para desbloquear as equipes dependentes que precisam trabalhar com uma API antes que o desenvolvimento do projeto seja concluído. Você também pode usar esse recurso para provisionar uma página de destino para sua API, que pode fornecer uma visão geral e a navegação para a sua API. Para obter um exemplo dessa página de aterrissagem, consulte a solicitação e a resposta de integração do método GET no recurso raiz da API, discutida no exemplo [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). Como desenvolvedor de APIs, você decide como o API Gateway responde a uma solicitação de integração simulada. Para isso, você configura a solicitação de integração e a resposta de integração do método para associar uma resposta a um determinado código de status. Para que um método com a integração de simulação retorne uma resposta `200`, configure o modelo de mapeamento do corpo da solicitação de integração para retornar o seguinte. ``` {"statusCode": 200} ``` Configure uma resposta de integração `200` para ter o seguinte modelo de mapeamento do corpo, por exemplo: ``` { "statusCode": 200, "message": "Go ahead without me." } ``` De forma parecida, para que o método retorne, por exemplo, uma resposta de erro `500`, defina o modelo de mapeamento do corpo da solicitação de integração para retornar o seguinte. ``` {"statusCode": 500} ``` Defina uma resposta de integração `500` com, por exemplo, o seguinte modelo de mapeamento: ``` { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } ``` Como alternativa, você pode fazer com que um método de integração simulada retorne a resposta de integração padrão sem definir o modelo de mapeamento de solicitação de integração. A resposta de integração padrão é aquela com um **HTTP status regex (Regex de status HTTP)** indefinido. Certifique-se de que os comportamentos de passagem apropriados estejam definidos. **nota** As integrações simuladas não são destinadas a oferecer suporte a modelos de respostas grandes. Se eles forem necessários ao seu caso de uso, considere usar a integração do Lambda. Com um modelo de mapeamento de solicitação de integração, você pode fazer com que a lógica do aplicativo decida qual resposta de integração simulada deve ser retornada com base em certas condições. Por exemplo, você pode usar um parâmetro de consulta `scope` na solicitação recebida para determinar se será retornada uma resposta bem-sucedida ou uma resposta de erro: ``` { #if( $input.params('scope') == "internal" ) "statusCode": 200 #else "statusCode": 500 #end } ``` Dessa forma, o método de integração simulada permite a passagem das chamadas internas, ao mesmo tempo, rejeitando outros tipos de chamadas com uma resposta de erro. Nesta seção, descrevemos como usar o console do API Gateway para habilitar a integração simulada para um método da API. **Topics** + [Ativar a integração simulada usando o console do API Gateway](how-to-mock-integration-console.md) # Ativar a integração simulada usando o console do API Gateway É necessário ter o método disponível no API Gateway. Siga as instruções em [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md). 1. Selecione um recurso de API e **Criar método**. Para configurar o método, faça o seguinte: 1. Em **Tipo de método**, selecione um método. 1. Em **Tipo de integração**, selecione **Simulação**. 1. Escolha **Criar método**. 1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, selecione **Editar**. 1. Selecione **Parâmetros de string de consulta de URL**. Selecione **Adicionar string de consulta** e, em **Nome**, insira **scope**. Esse parâmetro de consulta determina se o autor da chamada é interno ou não. 1. Escolha **Salvar**. 1. Na guia **Resposta do método**, selecione **Criar resposta** e faça o seguinte: 1. Em **Status HTTP**, insira **500**. 1. Escolha **Salvar**. 1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**. 1. Selecione **Modelos de mapeamento** e, depois, faça o seguinte: 1. Escolha **Add mapping template** (Adicionar modelo de mapeamento). 1. Em **Tipo de conteúdo**, insira **application/json**. 1. Em **Corpo do modelo**, insira o seguinte: ``` { #if( $input.params('scope') == "internal" ) "statusCode": 200 #else "statusCode": 500 #end } ``` 1. Escolha **Salvar**. 1. Na guia **Resposta de integração**, em **Padrão - Resposta**, selecione **Editar**. 1. Selecione **Modelos de mapeamento** e, depois, faça o seguinte: 1. Em **Tipo de conteúdo**, insira **application/json**. 1. Em **Corpo do modelo**, insira o seguinte: ``` { "statusCode": 200, "message": "Go ahead without me" } ``` 1. Escolha **Salvar**. 1. Selecione **Criar resposta**. Para criar uma resposta 500, faça o seguinte: 1. Em **HTTP status regex (Regex de status HTTP)**, insira **5\$1d\$12\$1**. 1. Em **Status de resposta do método**, selecione **500**. 1. Escolha **Salvar**. 1. Em **5\$1d\$12\$1 - Resposta**, selecione **Editar**. 1. Selecione **Modelos de mapeamento** e, depois, **Adicionar modelo de mapeamento**. 1. Em **Tipo de conteúdo**, insira **application/json**. 1. Em **Corpo do modelo**, insira o seguinte: ``` { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } ``` 1. Escolha **Salvar**. 1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. Para testar a integração simulada, faça o seguinte: 1. Digite `scope=internal` em **Strings de consulta**. Escolha **Test** (Testar). O resultado do teste mostra: ``` Request: /?scope=internal Status: 200 Latency: 26 ms Response Body { "statusCode": 200, "message": "Go ahead without me" } Response Headers {"Content-Type":"application/json"} ``` 1. Digite `scope=public` em `Query strings` ou deixe em branco. Escolha **Test** (Testar). O resultado do teste mostra: ``` Request: / Status: 500 Latency: 16 ms Response Body { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } Response Headers {"Content-Type":"application/json"} ``` Você também pode retornar os cabeçalhos em uma resposta de integração simulada, adicionando primeiro um cabeçalho à resposta de método e, em seguida, configurando um mapeamento de cabeçalho na resposta de integração. Na verdade, é assim que o console do API Gateway permite o suporte a CORS ao retornar os cabeçalhos necessários do CORS. # Solicitar validação para APIs REST no API Gateway Você pode configurar o API Gateway para realizar a validação básica de uma solicitação de API antes de prosseguir com a solicitação de integração. Quando a validação falha, o API Gateway marca a solicitação como falha imediatamente, retorna uma resposta de erro 400 para o autor da chamada e publica os resultados da validação em CloudWatch Logs. Isso reduz as chamadas desnecessárias para o backend. O mais importante, isso permite concentrar-se nos esforços de validação específicos para o seu aplicativo. É possível validar um corpo de solicitação verificando se os parâmetros de solicitação necessários são válidos e não nulos especificando um esquema de modelo para uma validação de dados mais complicada. **Topics** + [Visão geral da validação básica de solicitações no API Gateway](#api-gateway-request-validation-basic-definitions) + [Modelos de dados para APIs REST](models-mappings-models.md) + [Configurar a validação básica de solicitações no API Gateway](api-gateway-request-validation-set-up.md) + [Modelo do AWS CloudFormation de uma API de amostra com validação de solicitação básica](api-gateway-request-validation-sample-cloudformation.md) ## Visão geral da validação básica de solicitações no API Gateway O API Gateway pode realizar a validação básica da solicitação, para que você possa enfocar a validação específica do aplicativo no back-end. Para a validação, o API Gateway verifica uma das seguintes condições ou ambas: + Se os parâmetros de solicitação necessários no URI, a string de consulta e os cabeçalhos de uma solicitação de entrada estão incluídos e não estão vazios. O API Gateway verifica apenas a existência de um parâmetro e não verifica o tipo ou o formato. + Se a carga útil da solicitação aplicável atende à solicitação do [esquema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) do método para determinado tipo de conteúdo. Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, defina o tipo de conteúdo do modelo de dados como `$default`. Para ativar a validação, você deve especificar regras de validação em um [validador de solicitação](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html), adicionar o validador ao [mapa de validadores de solicitação](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) da API e atribuir o validador a métodos de API individuais. **nota** Solicite a validação do corpo e os [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md) são dois tópicos distintos. Quando uma carga útil de solicitação não tem nenhum esquema de modelo correspondente, você pode optar por transmitir ou bloquear a carga útil original. Para obter mais informações, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md). # Modelos de dados para APIs REST No API Gateway, um modelo define a estrutura de dados de uma carga. No API Gateway, modelos são definidos usando o [esquema JSON rascunho 4](https://tools.ietf.org/html/draft-zyp-json-schema-04). O objeto JSON a seguir é uma amostra de dados no exemplo da Pet Store. ``` { "id": 1, "type": "dog", "price": 249.99 } ``` Os dados contêm o `id`, o `type` e o `price` do animal de estimação. Um modelo desses dados possibilita que você: + Use a validação básica da solicitação. + Crie modelos de mapeamento para transformação de dados. + Crie um tipo de dados definido pelo usuário (UDT) ao gerar um SDK. ![\[Exemplo de modelo de dados JSON para a API PetStore.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/how-to-validate-requests.png) Neste modelo: 1. O objeto `$schema` representa um identificador de versão do Esquema JSON válido. Esse esquema é o rascunho do JSON Schema v4. 1. O objeto `title` é um identificador humanamente legível para o modelo. Esse título é `PetStoreModel`. 1. A palavra-chave de validação `required` exige o `type` e o `price` para validação básica da solicitação. 1. As `properties` do modelo são `id`, `type` e `price`. Cada objeto tem propriedades que são descritas no modelo. 1. O objeto `type` pode ter somente os valores `dog`, `cat` ou `fish`. 1. O objeto `price` é um número e está limitado ao `minimum` de 25 e ao `maximum` de 500. ## Modelo PetStore ``` 1 { 2 "$schema": "http://json-schema.org/draft-04/schema#", 3 "title": "PetStoreModel", 4 "type" : "object", 5 "required" : [ "price", "type" ], 6 "properties" : { 7 "id" : { 8 "type" : "integer" 9 }, 10 "type" : { 11 "type" : "string", 12 "enum" : [ "dog", "cat", "fish" ] 13 }, 14 "price" : { 15 "type" : "number", 16 "minimum" : 25.0, 17 "maximum" : 500.0 18 } 19 } 20 } ``` Neste modelo: 1. Na linha 2, o objeto `$schema` representa um identificador de versão do JSON Schema válido. Esse esquema é o rascunho do JSON Schema v4. 1. Na linha 3, o objeto `title` é um identificador legível para o modelo. Esse título é `PetStoreModel`. 1. Na linha 5, a palavra-chave de validação `required` exige o `type` e o `price` para validação básica da solicitação. 1. Nas linhas 6 a 17, as `properties` do modelo são `id`, `type` e `price`. Cada objeto tem propriedades que são descritas no modelo. 1. Na linha 12, o objeto `type` pode ter somente os valores `dog`, `cat` ou `fish`. 1. Nas linhas 14 a 17, o objeto `price` é um número e está limitado ao `minimum` de 25 e ao `maximum` de 500. ## Criar modelos mais complexos É possível usar o `$ref` primitivo para criar definições reutilizáveis para modelos mais longos. Por exemplo, você pode criar uma definição chamada `Price` na seção `definitions` que descreve o objeto `price`. O valor de `$ref` é a definição `Price`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStoreModelReUsableRef", "required" : ["price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "price" : { "$ref": "#/definitions/Price" } }, "definitions" : { "Price": { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } } ``` Você também pode referenciar outro esquema de modelo definido em um arquivo de modelo externo. Defina o valor da propriedade `$ref` para a localização do modelo. No exemplo a seguir, o modelo `Price` é definido no modelo `PetStorePrice` na API `a1234`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStorePrice", "type": "number", "minimum": 25, "maximum": 500 } ``` O modelo mais longo pode referenciar o modelo `PetStorePrice`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStoreModelReusableRefAPI", "required" : [ "price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "price" : { "$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice" } } } ``` ## Usar modelos de dados de saída Se você transformar seus dados, poderá definir um modelo de carga útil na resposta de integração. Um modelo de carga útil pode ser usado quando você gera um SDK. Para linguagens de tipo forte, como Java, Objective-C ou Swift, o objeto corresponde a um tipo de dados definido pelo usuário (UDT). O API Gateway cria um UDT se você fornecê-lo com um modelo de dados ao gerar um SDK. Para ter mais informações sobre transformações de dados, consulte [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). O exemplo a seguir são dados de saída de uma resposta de integração. ``` { [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] } ``` O exemplo a seguir é um modelo de payload que descreve os dados de saída. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetStoreOutputModel", "type" : "object", "required" : [ "description", "askingPrice" ], "properties" : { "description" : { "type" : "string" }, "askingPrice" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } } ``` Com esse modelo, você pode chamar um SDK para recuperar os valores de propriedades `description` e `askingPrice`, lendo as propriedades `PetStoreOutputModel[i].description` e `PetStoreOutputModel[i].askingPrice`. Se nenhum modelo for fornecido, o API Gateway usará o modelo vazio para criar um UDT padrão. ## Próximas etapas + Esta seção fornece recursos que você pode usar para ter mais conhecimento sobre os conceitos apresentados neste tópico. É possível seguir os tutoriais de validação da solicitação: + [Configurar a validação de solicitação usando o console do API Gateway](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console) + [Configurar a validação básica de solicitações usando a AWS CLI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli) + [Configurar a validação básica de solicitações importando a definição de OpenAPI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger) + Consulte mais informações sobre modelos de mapeamento e transformação de dados em [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). # Configurar a validação básica de solicitações no API Gateway Esta seção mostra como configurar a validação de solicitações para o API Gateway usando o console, a AWS CLI e uma definição de OpenAPI. **Topics** + [Configurar a validação de solicitação usando o console do API Gateway](#api-gateway-request-validation-setup-in-console) + [Configurar a validação básica de solicitações usando a AWS CLI](#api-gateway-request-validation-setup-cli) + [Configurar a validação básica de solicitações importando a definição de OpenAPI](#api-gateway-request-validation-setup-importing-swagger) ## Configurar a validação de solicitação usando o console do API Gateway Você pode usar o console do API Gateway para validar uma solicitação selecionando um dos três validadores para uma solicitação de API: + **Validar o corpo**. + **Valide parâmetros e cabeçalhos da string de consulta**. + **Validar o corpo, parâmetros da string de consulta e cabeçalhos**. Ao aplicar um dos validadores em um método de API, o console do API Gateway adiciona o validador ao mapa [RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) da API. Para seguir esse tutorial, você usará um modelo CloudFormation para criar uma API incompleta do API Gateway. Essa API tem um recurso `/validator` com os métodos `GET` e `POST`. Os dois métodos são integrados ao endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Você vai configurar dois tipos de validação de solicitação: + No método `GET`, você vai configurar a validação da solicitação para os parâmetros da string de consulta de URL. + No método `POST`, você vai configurar a validação da solicitação para o corpo da solicitação. Isso vai possibilitar que somente determinadas chamadas de API sejam transmitidas à API. Baixe e descompacte [o modelo de criação de aplicativos para CloudFormation](samples/request-validation-tutorial-console.zip). Você usará esse modelo para criar uma API incompleta. Você concluirá o restante das etapas no console do API Gateway. **Como criar uma pilha do CloudFormation** 1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Selecione **Create stack (Criar pilha)** e **With new resources (standard) (Com novos recursos (padrão))**. 1. Em **Specify template (Especificar modelo)**, escolha **Upload a template file (Fazer upload de um arquivo de modelo)**. 1. Selecione o modelo que você baixou. 1. Escolha **Next (Próximo)**. 1. Em **Nome da pilha**, insira **request-validation-tutorial-console** e escolha **Avançar**. 1. Para **Configurar opções de pilha**, escolha **Avançar**. 1. Para **Capabilities** (Recursos), reconheça que CloudFormation pode criar recursos do IAM em sua conta. 1. Escolha **Próximo** e, depois, **Enviar**. CloudFormationO fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Quando o status da sua pilha do CloudFormation for **CREATE\$1COMPLETE**, você estará pronto para passar para a próxima etapa. **Como selecionar sua API recém-criada** 1. Selecione a pilha **request-validation-tutorial-console** recém-criada. 1. Escolha **atributos**. 1. Em **ID físico**, escolha sua API. Esse link direcionará você para o console do API Gateway. Antes de modificar os métodos `GET` e `POST`, é necessário criar um modelo. **Como criar um modelo** 1. É necessário um modelo para usar a validação da solicitação no corpo de uma solicitação recebida. Para criar um modelo, no painel de navegação principal, selecione **Modelos**. 1. Escolha **Criar modelo**. 1. Em **Name (Nome)**, insira **PetStoreModel**. 1. Em **Tipo de conteúdo**, insira **application/json**. Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira **\$1default**. 1. Em **Descrição**, insira **My PetStore Model** como descrição do modelo. 1. Em **Esquema do modelo**, cole o modelo a seguir no editor de código e escolha **Criar**. ``` { "type" : "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } } ``` Para obter mais informações sobre o modelo, consulte [Modelos de dados para APIs REST](models-mappings-models.md). **Como configurar a validação da solicitação para um método `GET`** 1. No painel de navegação, selecione **Recursos** e, depois, selecione o método **GET**. 1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, escolha **Editar**. 1. Em **Validador de solicitação**, selecione **Validar parâmetros de string de consulta e cabeçalhos**. 1. Em **Parâmetros de string de consulta de URL**, faça o seguinte: 1. Escolha **Add query string** (Adicionar string de consulta). 1. Em **Name (Nome)**, insira **petType**. 1. Ative a opção **Obrigatório**. 1. Mantenha **Armazenamento em cache** desativado. 1. Escolha **Salvar**. 1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**. 1. Em **Parâmetros de string de consulta de URL**, faça o seguinte: 1. Escolha **Add query string** (Adicionar string de consulta). 1. Em **Name (Nome)**, insira **petType**. 1. Em **Mapeado de**, insira **method.request.querystring.petType**. Isso associa o **petType** ao tipo do animal de estimação. Para ter mais informações sobre mapeamento de dados, consulte [ o tutorial de mapeamento de dados](set-up-data-transformations-in-api-gateway.md#mapping-example-console). 1. Mantenha **Armazenamento em cache** desativado. 1. Escolha **Salvar**. **Como testar a validação da solicitação para o método `GET`** 1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. 1. Em **Strings de consulta**, insira **petType=dog** e escolha **Testar**. 1. O teste de método vai gerar `200 OK` e uma lista de cães. Para ter informações sobre como transformar esses dados de saída, consulte o [tutorial de mapeamento de dados](set-up-data-transformations-in-api-gateway.md#mapping-example-console). 1. Remova **petType=dog** e escolha **Testar**. 1. O teste de método vai gerar um erro `400` com a seguinte mensagem de erro: ``` { "message": "Missing required request parameters: [petType]" } ``` **Como configurar a validação da solicitação para o método `POST`** 1. No painel de navegação principal, selecione **Recursos** e, depois, selecione o método **POST**. 1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, escolha **Editar**. 1. Em **Validador de solicitação**, selecione **Validar corpo.** 1. Em **Corpo da solicitação**, escolha **Adicionar modelo**. 1. Em **Tipo de conteúdo**, insira **application/json**. Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira `$default`. Em **Modelo**, selecione **PetStoreModel**. 1. Escolha **Salvar**. **Como testar a validação da solicitação para um método `POST`** 1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. 1. Em **Corpo da solicitação**, cole o seguinte no editor de código: ``` { "id": 2, "name": "Bella", "type": "dog", "price": 400 } ``` Escolha **Testar**. 1. O teste de método vai gerar `200 OK` e uma mensagem de êxito. 1. Em **Corpo da solicitação**, cole o seguinte no editor de código: ``` { "id": 2, "name": "Bella", "type": "dog", "price": 4000 } ``` Escolha **Testar**. 1. O teste de método vai gerar um erro `400` com a seguinte mensagem de erro: ``` { "message": "Invalid request body" } ``` Na parte inferior dos logs de teste, o motivo do corpo de solicitação inválido será exibido. Nesse caso, o preço do animal de estimação estava fora do máximo especificado no modelo. **Para excluir uma pilha do CloudFormation** 1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Selecione sua pilha do CloudFormation. 1. Escolha **Excluir** e, em seguida, confirme sua escolha. ### Próximas etapas + Para ter informações sobre como transformar os dados de saída e realizar o mapeamento de mais dados, consulte o [tutorial de mapeamento de dados](set-up-data-transformations-in-api-gateway.md#mapping-example-console). + Siga o tutorial [Configurar a validação básica da solicitação usando o AWS CLI](#api-gateway-request-validation-setup-cli), para realizar etapas semelhantes usando a AWS CLI. ## Configurar a validação básica de solicitações usando a AWS CLI Você pode criar um validador para configurar a validação da solicitação usando a AWS CLI. Para seguir esse tutorial, você usará um modelo CloudFormation para criar uma API incompleta do API Gateway. **nota** Esse não é o mesmo modelo CloudFormation do tutorial do console. Usando um recurso `/validator` pré-exposto, você criará os métodos `GET` e `POST`. Os dois métodos serão integrados ao endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Você vai configurar as duas validações de solicitação a seguir: + No método `GET`, você criará um validador `params-only` para validar os parâmetros da string de consulta de URL. + No método `POST`, você criará um validador `body-only` para validar o corpo da solicitação. Isso vai possibilitar que somente determinadas chamadas de API sejam transmitidas à API. **Como criar uma pilha do CloudFormation** Baixe e descompacte [o modelo de criação de aplicativos para CloudFormation](samples/request-validation-tutorial-cli.zip). Para concluir o tutorial a seguir, é necessária a [AWS Command Line Interface (AWS CLI) versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). Para comandos longos, um caractere de escape (`\`) é usado para dividir um comando em várias linhas. **nota** No Windows, alguns comandos da CLI do Bash que você costuma usar (como `zip`) não são compatíveis com os terminais integrados do sistema operacional. Para obter uma versão do Ubuntu com o Bash integrada no Windows, [instale o Subsistema do Windows para Linux](https://learn.microsoft.com/en-us/windows/wsl/install). Os exemplos de comandos da CLI neste guia usam a formatação Linux. Os comandos que incluem documentos JSON em linha deverão ser reformatados se você estiver usando a CLI do Windows. 1. Use o comando a seguir para criar a pilha de CloudFormation. ``` aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM ``` 1. CloudFormationO fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Use o comando a seguir para ver o status de sua pilha de CloudFormation. ``` aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli ``` 1. Quando o status da sua pilha de CloudFormation for `StackStatus: "CREATE_COMPLETE"`, use o comando a seguir para recuperar valores de saída relevantes para etapas futuras. ``` aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}" ``` Os valores de saída são os seguintes: + ApiId, que é o ID da API. Para este tutorial, o ID da API é `abc123`. + ResourceId, que é a ID do recurso validador em que os métodos `GET` e `POST` são expostos. Para este tutorial, o ID do recurso é `efg456`. **Como criar os validadores de solicitação e importar um modelo** 1. É necessário um validador para usar a validação da solicitação com o AWS CLI. Use o comando a seguir para criar um validador que valide somente os parâmetros da solicitação. ``` aws apigateway create-request-validator --rest-api-id abc123 \ --no-validate-request-body \ --validate-request-parameters \ --name params-only ``` Anote o ID do validador `params-only`. 1. Use o comando a seguir para criar um validador que valide somente o corpo da solicitação. ``` aws apigateway create-request-validator --rest-api-id abc123 \ --validate-request-body \ --no-validate-request-parameters \ --name body-only ``` Anote o ID do validador `body-only`. 1. É necessário um modelo para usar a validação da solicitação no corpo de uma solicitação recebida. Use o comando a seguir para importar um modelo. ``` aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}' ``` Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, especifique `$default` como a chave. **Como criar os métodos `GET` e `POST`** 1. Use o comando a seguir para adicionar o método HTTP `GET` ao recurso `/validate`. Esse comando cria o método `GET`, adiciona o validador `params-only` e define a string de consulta `petType` conforme necessário. ``` aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --authorization-type "NONE" \ --request-validator-id aaa111 \ --request-parameters "method.request.querystring.petType=true" ``` Use o comando a seguir para adicionar o método HTTP `POST` ao recurso `/validate`. Esse comando cria o método `POST`, adiciona o validador `body-only` e anexa o modelo ao validador exclusivo do corpo. ``` aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --authorization-type "NONE" \ --request-validator-id bbb222 \ --request-models 'application/json'=PetStoreModel ``` 1. Use o comando a seguir para configurar a reposta `200 OK` do método como `GET /validate`. ``` aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --status-code 200 ``` Use o comando a seguir para configurar a reposta `200 OK` do método como `POST /validate`. ``` aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 ``` 1. Use o comando a seguir para configurar uma `Integration` com um endpoint HTTP especificado para o método `GET /validation`. ``` aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --type HTTP \ --integration-http-method GET \ --request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets' ``` Use o comando a seguir para configurar uma `Integration` com um endpoint HTTP especificado para o método `POST /validation`. ``` aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --type HTTP \ --integration-http-method GET \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets' ``` 1. Use o comando a seguir para configurar a resposta de integração do método `GET /validation`. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456\ --http-method GET \ --status-code 200 \ --selection-pattern "" ``` Use o comando a seguir para configurar a resposta de integração do método `POST /validation`. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 \ --selection-pattern "" ``` **Como testar a API** 1. Para testar o método `GET`, que executará a validação da solicitação para as strings de consulta, use o seguinte comando: ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --path-with-query-string '/validate?petType=dog' ``` O resultado retornará `200 OK` e uma lista de cães. 1. Use o comando a seguir para testar sem incluir a string de consulta `petType`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET ``` O resultado retornará um erro `400`. 1. Para testar o método `POST`, que executará a validação da solicitação para o corpo da string, use o seguinte comando: ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }' ``` O resultado retornará `200 OK` e uma mensagem de êxito. 1. Use o comando a seguir para testar usando um corpo inválido. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }' ``` O resultado retornará um erro `400`, pois o preço do cachorro está acima do preço máximo definido pelo modelo. **Para excluir uma pilha do CloudFormation** + Use o comando a seguir para excluir seus recursos de CloudFormation. ``` aws cloudformation delete-stack --stack-name request-validation-tutorial-cli ``` ## Configurar a validação básica de solicitações importando a definição de OpenAPI Você pode declarar um validador de solicitação no nível da API especificando um conjunto de objetos [Objeto x-amazon-apigateway-request-validators.requestValidator](api-gateway-swagger-extensions-request-validators.requestValidator.md) no mapa [Objeto x-amazon-apigateway-request-validators](api-gateway-swagger-extensions-request-validators.md) para selecionar qual parte da solicitação será validada. No exemplo de definição de OpenAPI, há dois validadores: + O validador `all` que valida o corpo, usando o modelo de dados `RequestBodyModel`, e os parâmetros. O modelo de dados `RequestBodyModel` requer que o objeto JSON de entrada contenha as propriedades `name`, `type` e `price`. A propriedade `name` pode ser qualquer string, `type` deve ser um dos campos de enumeração especificados (`["dog", "cat", "fish"]`) e `price` deve variar entre 25 e 500. O parâmetro `id` não é necessário. + `param-only` que valida somente os parâmetros. Para ativar um validador de solicitação em todos os métodos de uma API, especifique uma propriedade [Propriedade x-amazon-apigateway-request-validator](api-gateway-swagger-extensions-request-validator.md) em nível de API da definição de OpenAPI. Na definição de OpenAPI de exemplo, o validador `all` é usado em todos os métodos de API, a menos que ele seja substituído de outra forma. Ao usar um modelo para validar o corpo, se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, especifique `$default` como a chave. Para ativar um validador de solicitação em um método individual, especifique a propriedade `x-amazon-apigateway-request-validator` no nível do método. No exemplo, definição de OpenAPI, o validador `param-only` sobrescreve o validador `all` no método `GET`. Para importar o exemplo de OpenAPI para o API Gateway, consulte as instruções a seguir para [Importar uma API regional para o API Gateway](import-export-api-endpoints.md) ou [Importar uma API otimizada para bordas para o API Gateway](import-edge-optimized-api.md). ------ #### [ OpenAPI 3.0 ] ``` { "openapi" : "3.0.1", "info" : { "title" : "ReqValidators Sample", "version" : "1.0.0" }, "servers" : [ { "url" : "/{basePath}", "variables" : { "basePath" : { "default" : "/v1" } } } ], "paths" : { "/validation" : { "get" : { "parameters" : [ { "name" : "q1", "in" : "query", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response", "headers" : { "test-method-response-header" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ArrayOfError" } } } } }, "x-amazon-apigateway-request-validator" : "params-only", "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.type" : "method.request.querystring.q1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } }, "post" : { "parameters" : [ { "name" : "h1", "in" : "header", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RequestBodyModel" } } }, "required" : true }, "responses" : { "200" : { "description" : "200 response", "headers" : { "test-method-response-header" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ArrayOfError" } } } } }, "x-amazon-apigateway-request-validator" : "all", "x-amazon-apigateway-integration" : { "httpMethod" : "POST", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.custom_h1" : "method.request.header.h1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "components" : { "schemas" : { "RequestBodyModel" : { "required" : [ "name", "price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "maximum" : 500.0, "minimum" : 25.0, "type" : "number" } } }, "ArrayOfError" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Error" } }, "Error" : { "type" : "object" } } }, "x-amazon-apigateway-request-validators" : { "all" : { "validateRequestParameters" : true, "validateRequestBody" : true }, "params-only" : { "validateRequestParameters" : true, "validateRequestBody" : false } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger" : "2.0", "info" : { "version" : "1.0.0", "title" : "ReqValidators Sample" }, "basePath" : "/v1", "schemes" : [ "https" ], "paths" : { "/validation" : { "get" : { "produces" : [ "application/json", "application/xml" ], "parameters" : [ { "name" : "q1", "in" : "query", "required" : true, "type" : "string" } ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/ArrayOfError" }, "headers" : { "test-method-response-header" : { "type" : "string" } } } }, "x-amazon-apigateway-request-validator" : "params-only", "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.type" : "method.request.querystring.q1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } }, "post" : { "consumes" : [ "application/json" ], "produces" : [ "application/json", "application/xml" ], "parameters" : [ { "name" : "h1", "in" : "header", "required" : true, "type" : "string" }, { "in" : "body", "name" : "RequestBodyModel", "required" : true, "schema" : { "$ref" : "#/definitions/RequestBodyModel" } } ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/ArrayOfError" }, "headers" : { "test-method-response-header" : { "type" : "string" } } } }, "x-amazon-apigateway-request-validator" : "all", "x-amazon-apigateway-integration" : { "httpMethod" : "POST", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.custom_h1" : "method.request.header.h1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "definitions" : { "RequestBodyModel" : { "type" : "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } }, "ArrayOfError" : { "type" : "array", "items" : { "$ref" : "#/definitions/Error" } }, "Error" : { "type" : "object" } }, "x-amazon-apigateway-request-validators" : { "all" : { "validateRequestParameters" : true, "validateRequestBody" : true }, "params-only" : { "validateRequestParameters" : true, "validateRequestBody" : false } } } ``` ------ # Modelo do AWS CloudFormation de uma API de amostra com validação de solicitação básica A definição a seguir do modelo de exemplo do CloudFormation especifica uma API de amostra com a validação de solicitações habilitada. A API é um subconjunto da [API PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets). Ela expõe um método `POST` para adicionar um animal de estimação à coleção `pets` e um método `GET` para consulta animais de estimação por um tipo especificado. Há dois validadores de solicitações declarados: **`GETValidator`** Esse validador está habilitado no método `GET`. Ele permite que o API Gateway verifique se o parâmetro de consulta necessário (`q1`) está incluído e não está em branco na solicitação de entrada. **`POSTValidator`** Esse validador está habilitado no método `POST`. Isso permite que o API Gateway verifique se o formato da solicitação de carga está de acordo com o `RequestBodyModel` especificado quando o tipo de conteúdo é `application/json`. Caso nenhum tipo de conteúdo correspondente seja encontrado, a validação da solicitação não será realizada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, especifique `$default`. `RequestBodyModel` contém um modelo adicional, `RequestBodyModelId`, para definir a identificação do animal de estimação. ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: StageName: Type: String Default: v1 Description: Name of API stage. Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: ReqValidatorsSample RequestBodyModelId: Type: 'AWS::ApiGateway::Model' Properties: RestApiId: !Ref Api ContentType: application/json Description: Request body model for Pet ID. Schema: $schema: 'http://json-schema.org/draft-04/schema#' title: RequestBodyModelId properties: id: type: integer RequestBodyModel: Type: 'AWS::ApiGateway::Model' Properties: RestApiId: !Ref Api ContentType: application/json Description: Request body model for Pet type, name, price, and ID. Schema: $schema: 'http://json-schema.org/draft-04/schema#' title: RequestBodyModel required: - price - name - type type: object properties: id: "$ref": !Sub - 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}' - Api: !Ref Api RequestBodyModelId: !Ref RequestBodyModelId price: type: number minimum: 25 maximum: 500 name: type: string type: type: string enum: - "dog" - "cat" - "fish" GETValidator: Type: AWS::ApiGateway::RequestValidator Properties: Name: params-only RestApiId: !Ref Api ValidateRequestBody: False ValidateRequestParameters: True POSTValidator: Type: AWS::ApiGateway::RequestValidator Properties: Name: body-only RestApiId: !Ref Api ValidateRequestBody: True ValidateRequestParameters: False ValidationResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'validation' ValidationMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref ValidationResource HttpMethod: GET AuthorizationType: NONE RequestValidatorId: !Ref GETValidator RequestParameters: method.request.querystring.q1: true Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ValidationMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref ValidationResource HttpMethod: POST AuthorizationType: NONE RequestValidatorId: !Ref POSTValidator RequestModels: application/json : !Ref RequestBodyModel Integration: Type: HTTP_PROXY IntegrationHttpMethod: POST Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - ValidationMethodGet - RequestBodyModel Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' Outputs: ApiRootUrl: Description: Root Url of the API Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}' ``` # Transformações de dados para APIs REST no API Gateway **nota** Essa seção explica os recursos que você usa com uma integração sem proxy. No entanto, recomendamos que, quando possível, você use uma integração com proxy para a API REST. Uma integração com proxy HTTP tem uma configuração de integração simplificada e pode evoluir com o backend sem a necessidade de descartar a configuração existente. Para obter mais informações, consulte [Escolher um tipo de integração de API do API Gateway](api-gateway-api-integration-types.md). Se usar uma integração sem proxy, você poderá utilizar dois recursos do API Gateway para transformar a solicitação de método e a resposta da integração. Você poderá transformar a solicitação do método se ela usar um formato de carga útil diferente da carga útil da solicitação de integração. Será possível transformar a resposta da integração se ela retornar um formato de carga útil diferente do formato que você precisa retornar na resposta do método. Consulte mais informações sobre o ciclo de vida da solicitação em [Exemplo de recurso para uma API REST](rest-api-develop.md#rest-api-develop-example). O exemplo a seguir mostra uma transformação de dados em que, para o cabeçalho `"x-version:beta"`, o parâmetro de cabeçalho `x-version` é transformado no parâmetro de cabeçalho `app-version`. A transformação dos dados de `x-version` para `app-version` ocorre na solicitação de integração. Dessa forma, o endpoint de integração recebe o valor do parâmetro do cabeçalho transformado. Quando o endpoint de integração retorna um código de status, esse código é transformado de `200` para `204` antes da resposta do método. ![\[Diagrama de transformação de dados do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/develop-non-proxy.png) Para criar uma transformação de dados, é possível usar os seguintes recursos: **Mapeamento de parâmetros** No mapeamento de parâmetros, você pode modificar os parâmetros do caminho do URL da solicitação de integração, os parâmetros da string de consulta do URL ou os valores do cabeçalho HTTP, mas não pode modificar a carga útil da solicitação de integração. Você também pode modificar os valores do cabeçalho de resposta HTTP. Use o mapeamento de parâmetros para criar valores de cabeçalho estáticos para compartilhamento de recursos de origem cruzada (CORS). É possível usar o mapeamento de parâmetros em sua solicitação de integração para integrações de proxy e não proxy, mas para usar o mapeamento de parâmetros para uma resposta de integração, você precisa de uma integração não proxy. O mapeamento de parâmetros não requer nenhuma programação em [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Para obter mais informações, consulte [Mapeamento de parâmetros para APIs REST no API Gateway](rest-api-parameter-mapping.md). **Transformações de modelo de mapeamento** Nas transformações de modelo de mapeamento, você usa um modelo de mapeamento para mapear parâmetros de caminho de URL, parâmetros de string de consulta de URL, cabeçalhos HTTP e o corpo da solicitação de integração ou resposta de integração. *Modelo de mapeamento* é um script expresso em [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) que usa [expressões JSONPath](https://goessner.net/articles/JsonPath/) e é aplicado à carga útil com base no cabeçalho `Content-type`. Com um modelo de mapeamento, é possível fazer o seguinte: + Selecionar quais dados enviar usando a integração a Serviços da AWS, como funções do Amazon DynamoDB ou do Lambda ou endpoints HTTP. Para obter mais informações, consulte [Tutorial: modificar a solicitação e a resposta de integração para integrações a serviços da AWS](set-up-data-transformations-in-api-gateway.md). + Substituir condicionalmente os parâmetros de solicitação e resposta de integração de uma API, criar valores de cabeçalho e substituir códigos de status. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). Você também pode especificar o comportamento da API quando um corpo de solicitação de integração tem um cabeçalho `Content-type` sem modelos de mapeamento correspondentes. Isso é chamado de comportamento de passagem direta de integração. Para obter mais informações, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md). ## Escolher entre mapeamento de parâmetros e transformações de modelos de mapeamento Recomendamos que você use o mapeamento de parâmetros para transformar dados quando possível. Se a API exigir que você altere o corpo ou execute substituições e modificações condicionais com base na solicitação de integração recebida ou na resposta de integração, e não for possível usar uma integração com proxy, use transformações de modelo de mapeamento. # Mapeamento de parâmetros para APIs REST no API Gateway **nota** Se você estiver usando uma API HTTP, consulte [Transformar solicitações e respostas de API para APIs HTTP no API Gateway](http-api-parameter-mapping.md). No mapeamento de parâmetros, você mapeia os parâmetros de solicitação ou resposta. É possível mapear parâmetros usando expressões de mapeamento de parâmetros ou valores estáticos. Consulte uma lista de expressões de mapeamento em [Referência da origem do mapeamento de parâmetros para APIs REST no API Gateway](rest-api-parameter-mapping-sources.md). É possível usar o mapeamento de parâmetros em sua solicitação de integração para integrações de proxy e não proxy, mas para usar o mapeamento de parâmetros para uma resposta de integração, você precisa de uma integração não proxy. Por exemplo, você pode mapear o parâmetro do cabeçalho da solicitação do método `puppies` para o parâmetro do cabeçalho da solicitação de integração `DogsAge0`. Então, se um cliente enviar o cabeçalho `puppies:true` para a API, a solicitação de integração enviará o cabeçalho da solicitação `DogsAge0:true` ao endpoint de integração. O diagrama a seguir mostra o ciclo de vida da solicitação nesse exemplo. ![\[Diagrama do exemplo de mapeamento de parâmetros do API Gateway para uma solicitação\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/parameter-mapping-example1.png) Para criar esse exemplo usando o API Gateway, consulte [Exemplo 1: mapear um parâmetro de solicitação de método para um parâmetro de solicitação de integração](request-response-data-mappings.md#request-response-data-mappings-example-1). Como outro exemplo, você também pode mapear o parâmetro do cabeçalho de resposta da integração `kittens` para o parâmetro do cabeçalho de resposta do método `CatsAge0`. Então, se o endpoint de integração retornar `kittens:false`, o cliente receberá o cabeçalho `CatsAge0:false`. O diagrama a seguir mostra o ciclo de vida da solicitação nesse exemplo. ![\[Diagrama de exemplo de mapeamento de parâmetros do API Gateway para uma resposta\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/parameter-mapping-example2.png) **Topics** + [Exemplos de mapeamento de parâmetros para APIs REST no API Gateway](request-response-data-mappings.md) + [Referência da origem do mapeamento de parâmetros para APIs REST no API Gateway](rest-api-parameter-mapping-sources.md) # Exemplos de mapeamento de parâmetros para APIs REST no API Gateway Os exemplos a seguir mostram como criar expressões de mapeamento de parâmetros usando o console do API Gateway, a OpenAPI e modelos do CloudFormation. Consulte um exemplo de como usar o mapeamento de parâmetros para criar os cabeçalhos CORS necessários em [CORS para APIs REST no API Gateway](how-to-cors.md). ## Exemplo 1: mapear um parâmetro de solicitação de método para um parâmetro de solicitação de integração O exemplo a seguir mapeia o parâmetro do cabeçalho da solicitação do método `puppies` para o parâmetro do cabeçalho da solicitação de integração `DogsAge0`. ------ #### [ Console de gerenciamento da AWS ] **Como mapear o parâmetro de solicitação do método** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Escolha um método. O método deve ter uma integração sem proxy. 1. Em **Configurações de solicitação de método**, selecione **Editar**. 1. Escolha **Cabeçalhos de solicitação HTTP**. 1. Escolha **Add header** (Adicionar cabeçalho). 1. Em **Nome**, digite **puppies**. 1. Escolha **Salvar**. 1. Selecione a guia **Solicitação de integração** e, em **Configurações de solicitação de integração**, selecione **Editar**. O Console de gerenciamento da AWS adiciona automaticamente um mapeamento de parâmetros de `method.request.header.puppies ` para `puppies` para você, mas é necessário alterar o **Nome** para corresponder ao parâmetro do cabeçalho da solicitação que é esperado pelo endpoint de integração. 1. Em **Nome**, digite **DogsAge0**. 1. Escolha **Salvar**. 1. Implante a API novamente para que as alterações entrem em vigor. As etapas a seguir mostram como verificar se o mapeamento de parâmetros foi bem-sucedido. **(Opcional) Testar o mapeamento de parâmetros** 1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. 1. Para os cabeçalhos, insira **puppies:true**. 1. Escolha **Testar**. 1. Em **Logs**, o resultado deve ser algo semelhante a: ``` Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true} Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations: Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344} ``` O parâmetro do cabeçalho da solicitação foi alterado de `puppies` para `DogsAge0`. ------ #### [ CloudFormation ] Nesse exemplo, você usa a propriedade [corpo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar um arquivo de definição da OpenAPI para o API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: ParameterMappingExample version: "2025-02-04T00:30:41Z" paths: /pets: get: parameters: - name: puppies in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.DogsAge0: method.request.header.puppies passthroughBehavior: when_no_match type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] ``` { "openapi" : "3.0.1", "info" : { "title" : "ParameterMappingExample", "version" : "2025-02-04T00:30:41Z" }, "paths" : { "/pets" : { "get" : { "parameters" : [ { "name" : "puppies", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.DogsAge0" : "method.request.header.puppies" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } } } ``` ------ ## Exemplo 2: mapear vários parâmetros de solicitação de método para diferentes parâmetros de solicitação de integração O exemplo a seguir mapeia o parâmetro de string de consulta de vários valores da solicitação do método `methodRequestQueryParam` para o parâmetro de string de consulta da solicitação de integração `integrationQueryParam` e mapeia o parâmetro de cabeçalho da solicitação do método `methodRequestHeaderParam` para o parâmetro de caminho da solicitação de integração `integrationPathParam`. ------ #### [ Console de gerenciamento da AWS ] **Como mapear os parâmetros da solicitação de método** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Escolha um método. O método deve ter uma integração sem proxy. 1. Em **Configurações de solicitação de método**, selecione **Editar**. 1. Selecione **Parâmetros de string de consulta de URL**. 1. Escolha **Add query string** (Adicionar string de consulta). 1. Em **Nome**, digite **methodRequestQueryParam**. 1. Escolha **Cabeçalhos de solicitação HTTP**. 1. Escolha **Add header** (Adicionar cabeçalho). 1. Em **Nome**, digite **methodRequestHeaderParam**. 1. Escolha **Salvar**. 1. Selecione a guia **Solicitação de integração** e, em **Configurações de solicitação de integração**, selecione **Editar**. 1. Selecione **Parâmetros de caminho de URL**. 1. Selecione **Adicionar parâmetro de caminho**. 1. Em **Nome**, digite **integrationPathParam**. 1. Em **Mapeado de**, insira **method.request.header.methodRequestHeaderParam**. Isso mapeia o cabeçalho da solicitação de método que você especificou na solicitação de método para um novo parâmetro de caminho de solicitação de integração. 1. Selecione **Parâmetros de string de consulta de URL**. 1. Escolha **Add query string** (Adicionar string de consulta). 1. Em **Nome**, digite **integrationQueryParam**. 1. Em **Mapeado de**, insira **method.request.multivaluequerystring.methodRequestQueryParam**. Isso mapeia o parâmetro da string de consulta de vários valores para um novo parâmetro de string de consulta de solicitação de integração de valor único. 1. Escolha **Salvar**. 1. Implante a API novamente para que as alterações entrem em vigor. ------ #### [ CloudFormation ] Nesse exemplo, você usa a propriedade [corpo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar um arquivo de definição da OpenAPI para o API Gateway. A definição da OpenAPI a seguir cria os seguintes mapeamentos de parâmetros para uma integração HTTP: + O cabeçalho da solicitação de método, chamado `methodRequestHeaderParam`, no parâmetro do caminho de solicitação de integração, chamado `integrationPathParam` + A string de consulta da solicitação de método de vários valores, chamada `methodRequestQueryParam`, na string de consulta da solicitação de integração, chamada `integrationQueryParam` ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example 2 version: "2025-01-15T19:12:31Z" paths: /: post: parameters: - name: methodRequestQueryParam in: query schema: type: string - name: methodRequestHeaderParam in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] A definição da OpenAPI a seguir cria os seguintes mapeamentos de parâmetros para uma integração HTTP: + O cabeçalho da solicitação de método, chamado `methodRequestHeaderParam`, no parâmetro do caminho de solicitação de integração, chamado `integrationPathParam` + A string de consulta da solicitação de método de vários valores, chamada `methodRequestQueryParam`, na string de consulta da solicitação de integração, chamada `integrationQueryParam` ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example 2", "version" : "2025-01-15T19:12:31Z" }, "paths" : { "/" : { "post" : { "parameters" : [ { "name" : "methodRequestQueryParam", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "methodRequestHeaderParam", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam", "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam" }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000, "type" : "http" } } } } } ``` ------ ## Exemplo 3: mapear campos do corpo da solicitação JSON para os parâmetros da solicitação de integração Também é possível mapear parâmetros da solicitação de integração com base em campos no corpo da solicitação JSON usando uma [expressão JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). O exemplo a seguir mapeia o corpo da solicitação de método para um cabeçalho da solicitação de integração chamado `body-header` e mapeia parte do corpo da solicitação, conforme expresso por uma expressão JSON, para um cabeçalho da solicitação de integração chamado `pet-price`. Para testar esse exemplo, forneça uma entrada que contenha uma categoria de preço, como a seguinte: ``` [ { "id": 1, "type": "dog", "price": 249.99 } ] ``` ------ #### [ Console de gerenciamento da AWS ] **Como mapear os parâmetros da solicitação de método** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Escolha um método `POST`, `PUT`, `PATCH` ou `ANY`. O método deve ter uma integração sem proxy. 1. Em **Configurações de solicitação de integração**, selecione **Editar**. 1. Selecione **Parâmetros de cabeçalhos de solicitações de URL**. 1. Selecione **Adicionar parâmetro de cabeçalho de solicitação**. 1. Em **Nome**, digite **body-header**. 1. Em **Mapeado de**, insira **method.request.body**. Isso mapeia o corpo da solicitação de método para um novo parâmetro de cabeçalho de solicitação de integração. 1. Selecione **Adicionar parâmetro de cabeçalho de solicitação**. 1. Em **Nome**, digite **pet-price**. 1. Em **Mapeado de**, insira ** method.request.body[0].price**. Isso mapeia uma parte do corpo da solicitação do método para um novo parâmetro de cabeçalho da solicitação de integração. 1. Escolha **Salvar**. 1. Implante a API novamente para que as alterações entrem em vigor. ------ #### [ CloudFormation ] Nesse exemplo, você usa a propriedade [corpo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar um arquivo de definição da OpenAPI para o API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example 3 version: "2025-01-15T19:19:14Z" paths: /: post: responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.pet-price: method.request.body[0].price integration.request.header.body-header: method.request.body requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] A definição de OpenAPI a seguir mapeia parâmetros de solicitação de integração com base nos campos no corpo da solicitação JSON. ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example 3", "version" : "2025-01-15T19:19:14Z" }, "paths" : { "/" : { "post" : { "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.pet-price" : "method.request.body[0].price", "integration.request.header.body-header" : "method.request.body" }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000, "type" : "http" } } } } } ``` ------ ## Exemplo 4: mapear a resposta de integração para a resposta do método Também é possível mapear a resposta de integração para a resposta do método. O exemplo a seguir mapeia o corpo da resposta de integração para um cabeçalho de resposta de método chamado `location`, mapeia o cabeçalho de resposta de integração `x-app-id` para o cabeçalho de resposta de método `id` e mapeia o cabeçalho de resposta de integração de vários valores `item` para o cabeçalho de resposta do método `items`. ------ #### [ Console de gerenciamento da AWS ] **Como mapear a resposta de integração** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. Escolha um método. O método deve ter uma integração sem proxy. 1. Escolha a guia **Resposta do método** e, em **Resposta 200**, selecione **Editar**. 1. Em **Nome do cabeçalho**, escolha **Adicionar cabeçalho**. 1. Crie três cabeçalhos chamados **id**, **item** e **location**. 1. Escolha **Salvar**. 1. Escolha a guia **Resposta de integração** e em **Padrão: resposta**, selecione **Editar**. 1. Em **Mapeamentos de cabeçalho**, insira o indicado a seguir. 1. Em **id**, insira **integration.response.header.x-app-id**. 1. Em **item**, insira **integration.response.multivalueheader.item** 1. Em **local**, insira **integration.response.body.redirect.url**. 1. Escolha **Salvar**. 1. Implante a API novamente para que as alterações entrem em vigor. ------ #### [ CloudFormation ] Nesse exemplo, você usa a propriedade [corpo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar um arquivo de definição da OpenAPI para o API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example version: "2025-01-15T19:21:35Z" paths: /: post: responses: "200": description: 200 response headers: item: schema: type: string location: schema: type: string id: schema: type: string x-amazon-apigateway-integration: type: http httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" responseParameters: method.response.header.id: integration.response.header.x-app-id method.response.header.location: integration.response.body.redirect.url method.response.header.item: integration.response.multivalueheader.item requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] A definição de OpenAPI a seguir mapeia a resposta de integração para a resposta do método. ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example", "version" : "2025-01-15T19:21:35Z" }, "paths" : { "/" : { "post" : { "responses" : { "200" : { "description" : "200 response", "headers" : { "item" : { "schema" : { "type" : "string" } }, "location" : { "schema" : { "type" : "string" } }, "id" : { "schema" : { "type" : "string" } } } } }, "x-amazon-apigateway-integration" : { "type" : "http", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.id" : "integration.response.header.x-app-id", "method.response.header.location" : "integration.response.body.redirect.url", "method.response.header.item" : "integration.response.multivalueheader.item" } } }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000 } } } } } ``` ------ # Referência da origem do mapeamento de parâmetros para APIs REST no API Gateway Ao criar um mapeamento de parâmetros, especifique os parâmetros de solicitação de método ou resposta de integração a serem modificados e especifique como modificar esses parâmetros. A tabela a seguir mostra os parâmetros de solicitação de método que você pode mapear e a expressão para criar o mapeamento. Nessas expressões, *nome* é o nome de um parâmetro de solicitação de método. Por exemplo, para mapear o parâmetro do cabeçalho da solicitação `puppies`, use a expressão `method.request.header.puppies`. A expressão deve corresponder à expressão regular `'^[a-zA-Z0-9._$-]+$]'`. É possível usar o mapeamento de parâmetros em sua solicitação de integração para integrações de proxy e não proxy. | **Fonte de dados mapeada** | **Expressão de mapeamento** | | --- | --- | | Caminho de solicitação de método | method.request.path.name | | String de consulta da solicitação de método | method.request.querystring.name | | String de consulta de solicitação do método de vários valores | method.request.multivaluequerystring.name | | Cabeçalho da solicitação de método | method.request.header.name | | Cabeçalho de solicitação de método de vários valores | method.request.multivalueheader.name | | Corpo de solicitação de método | method.request.body | | Corpo de solicitação de método (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* é uma expressão JSONPath para um campo JSON do corpo de uma solicitação. Consulte mais informações em [Expressão JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). | | Variáveis de estágio | stageVariables.name | | Variáveis de contexto | `context.name` O nome deve ser uma das [variáveis de contexto compatíveis](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valor estático | `'static_value'`. *static\$1value* é um literal de string e deve estar entre aspas simples. Por exemplo, `'https://www.example.com'`. | A tabela a seguir mostra os parâmetros da resposta de integração que você pode mapear e a expressão para criar o mapeamento. Nessas expressões, *nome* é o nome de um parâmetro de resposta de integração. É possível mapear cabeçalhos de resposta do método por meio de qualquer cabeçalho de resposta de integração ou corpo de resposta de integração, variáveis \$1context ou valores estáticos. Para usar o mapeamento de parâmetros para uma resposta de integração, você precisa de uma integração não proxy. | Fonte de dados mapeada | Expressão de mapeamento | | --- | --- | | Cabeçalho da resposta de integração | integration.response.header.name | | Cabeçalho da resposta de integração | integration.response.multivalueheader.name | | Corpo da resposta de integração | integration.response.body | | Corpo da resposta de integração (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* é uma expressão JSONPath para um campo JSON do corpo de uma resposta. Consulte mais informações em [Expressão JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). | | Variável de estágio | stageVariables.name | | Variável de contexto | `context.name` O nome deve ser uma das [variáveis de contexto compatíveis](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valor estático | ` 'static_value'` *static\$1value* é um literal de string e deve estar entre aspas simples. Por exemplo, `'https://www.example.com'`. | # Transformações de modelo de mapeamento para APIs REST no API Gateway Uma transformação de modelo de mapeamento usa um modelo de mapeamento para modificar a solicitação ou a resposta de integração. *Modelo de mapeamento* é um script expresso em [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) e é aplicado a uma carga útil usando o [JSONPath](https://goessner.net/articles/JsonPath/) baseado no cabeçalho `Content-type`. Você utiliza modelos de mapeamento ao usar transformações de modelos de mapeamento. Esta seção descreve informações conceituais relacionadas aos modelos de mapeamento. O diagrama a seguir mostra o ciclo de vida da solicitação para um recurso `POST /pets` que tem uma integração com um endpoint de integração da PetStore. Nessa API, um usuário envia dados sobre um animal de estimação e o endpoint de integração retorna a taxa de adoção associada a um animal de estimação. Nesse ciclo de vida da solicitação, as transformações do modelo de mapeamento filtram o corpo da solicitação para o endpoint de integração e filtram o corpo da resposta do endpoint de integração. ![\[Exemplo de ciclo de vida da solicitação\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/mapping-template-transforms.png) As seções a seguir explicam o ciclo de vida da solicitação e da resposta. ## Solicitação de método e solicitação de integração No exemplo anterior, se este for o corpo da solicitação enviado para a solicitação do método: ``` POST /pets HTTP/1.1 Host:abcd1234.us-west-2.amazonaws.com Content-type: application/json { "id": 1, "type": "dog", "Age": 11, } ``` Esse corpo da solicitação não está no formato correto para ser usado pelo endpoint de integração, então o API Gateway executa uma transformação do modelo de mapeamento. O API Gateway só executa uma transformação do modelo de mapeamento porque há um modelo de mapeamento definido para `application/json` de Content-Type. Se você não definir um modelo de mapeamento para Content-Type, por padrão, o API Gateway passará o corpo por meio da solicitação de integração ao endpoint de integração. Para modificar esse comportamento, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md). O modelo de mapeamento a seguir transforma os dados da solicitação de método na solicitação de integração antes de serem enviados ao endpoint de integração: ``` #set($inputRoot = $input.path('$')) { "dogId" : "dog_"$elem.id, "Age": $inputRoot.Age } ``` 1. A variável `$inputRoot` representa o objeto raiz nos dados JSON originais da seção anterior. As diretivas começam com o símbolo `#`. 1. `dog` é uma concatenação do `id` do usuário e de um valor de string. 1. `Age` é do corpo da solicitação do método. Então, a saída a seguir é encaminhada ao endpoint de integração: ``` { "dogId" : "dog_1", "Age": 11 } ``` ## Resposta de integração e resposta do método Após a solicitação bem-sucedida ao endpoint de integração, o endpoint envia uma resposta à resposta de integração do API Gateway. Veja a seguir exemplos de dados de saída do endpoint de integração: ``` { "dogId" : "dog_1", "adoptionFee": 19.95, } ``` A resposta do método espera uma carga útil diferente da retornada pela resposta de integração. O API Gateway executa uma transformação do modelo de mapeamento. O API Gateway só executa uma transformação do modelo de mapeamento porque há um modelo de mapeamento definido para `application/json` de Content-Type. Se você não definir um modelo de mapeamento para Content-Type, por padrão, o API Gateway passará o corpo por meio da resposta de integração para a resposta do método. Para modificar esse comportamento, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md). ``` #set($inputRoot = $input.path('$')) { "adoptionFee" : $inputRoot.adoptionFee, } ``` Veja a seguir a saída enviada à resposta do método: ``` {"adoptionFee": 19.95} ``` Isso conclui o exemplo de transformação do modelo de mapeamento. Recomendamos que, quando possível, em vez de usar transformações de modelo de mapeamento, você use uma integração com proxy para transformar dados. Para obter mais informações, consulte [Escolher um tipo de integração de API do API Gateway](api-gateway-api-integration-types.md). # Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway Se a solicitação de método tiver uma carga útil e você não tiver um modelo de mapeamento definido para o cabeçalho `Content-Type`, poderá optar por passar a carga útil da solicitação fornecida pelo cliente por meio da solicitação de integração ao backend sem transformação. O processo é conhecido como passagem direta de integração. O comportamento real de passagem de uma solicitação recebida é determinado por essa configuração. Existem três opções: **Quando nenhum modelo corresponder ao cabeçalho Content-Type da solicitação** Escolha essa opção se desejar que o corpo da solicitação de método passe a solicitação de integração para o back-end sem transformação quando o tipo de conteúdo da solicitação de método não corresponder a nenhum dos tipos de conteúdo associados aos modelos de mapeamento. Ao chamar a API do API Gateway, escolha essa opção definindo `WHEN_NO_MATCH` como o valor da propriedade `passthroughBehavior` na [Integração](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). **Quando não há modelos definidos (recomendado)** Escolha essa opção se desejar que o corpo da solicitação de método passe a solicitação de integração para o back-end sem transformação quando nenhum modelo de mapeamento estiver definido na solicitação de integração. Se um modelo for definido quando essa opção for selecionada, a solicitação de método de um tipo de conteúdo e carga útil que não corresponda a nenhum modelo de mapeamento definido será rejeitada com uma resposta HTTP 415 Tipo de mídia incompatível. Ao chamar a API do API Gateway, escolha essa opção definindo `WHEN_NO_TEMPLATES` como o valor da propriedade `passthroughBehavior` na [Integração](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). **Nunca** Escolha essa opção se não desejar que o corpo da solicitação de método passe a solicitação de integração para o back-end sem transformação quando nenhum modelo de mapeamento estiver definido na solicitação de integração. Se um modelo for definido quando essa opção for selecionada, a solicitação de método de um tipo de conteúdo não mapeado será rejeitada com uma resposta HTTP 415 Tipo de mídia sem suporte. Ao chamar a API do API Gateway, escolha essa opção definindo `NEVER` como o valor da propriedade `passthroughBehavior` na [Integração](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Os exemplos a seguir mostram os possíveis comportamentos de passagem. Exemplo 1: um modelo de mapeamento é definido na solicitação de integração para o tipo de conteúdo `application/json`. | Content-type | Opção de passagem | Comportamento | | --- | --- | --- | | Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1MATCH | A carga da solicitação é transformada usando o modelo. | | Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1TEMPLATES | A carga da solicitação é transformada usando o modelo. | | Nenhum O padrão do API Gateway é `application/json` | NEVER | A carga da solicitação é transformada usando o modelo. | | application/json | WHEN\$1NO\$1MATCH | A carga da solicitação é transformada usando o modelo. | | application/json | WHEN\$1NO\$1TEMPLATES | A carga da solicitação é transformada usando o modelo. | | application/json | NEVER | A carga da solicitação é transformada usando o modelo. | | application/xml | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | application/xml | WHEN\$1NO\$1TEMPLATES | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | | application/xml | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | Exemplo 2: um modelo de mapeamento é definido na solicitação de integração para o tipo de conteúdo `application/xml`. | Content-type | Opção de passagem | Comportamento | | --- | --- | --- | | Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1TEMPLATES | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | | Nenhum O padrão do API Gateway é `application/json` | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | | application/json | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | application/json | WHEN\$1NO\$1TEMPLATES | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | | application/json | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | | application/xml | WHEN\$1NO\$1MATCH | A carga da solicitação é transformada usando o modelo. | | application/xml | WHEN\$1NO\$1TEMPLATES | A carga da solicitação é transformada usando o modelo. | | application/xml | NEVER | A carga da solicitação é transformada usando o modelo. | Exemplo 3: nenhum modelo de mapeamento está definido na solicitação de integração. | Content-type | Opção de passagem | Comportamento | | --- | --- | --- | | Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1TEMPLATES | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | Nenhum O padrão do API Gateway é `application/json` | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | | application/json | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | application/json | WHEN\$1NO\$1TEMPLATES | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | application/json | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | | application/xml | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | application/xml | WHEN\$1NO\$1TEMPLATES | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. | | application/xml | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. | # Exemplo adicional de modelo de mapeamento para APIs REST no API Gateway O exemplo a seguir mostra uma API de álbum de fotos no API Gateway que usa modelos de mapeamento para transformar dados de solicitação e de resposta de integração. Ele também usa modelos de dados para definir cargas úteis de solicitação de método e resposta de integração. Para saber mais sobre modelos de dados, consulte [Modelos de dados para APIs REST](models-mappings-models.md). ## Solicitação de método e solicitação de integração Veja a seguir um modelo que define o corpo da solicitação do método. Esse modelo de entrada exige que o chamador faça upload de uma página de foto requer no mínimo 10 fotos por página. É possível usar esse modelo de entrada para gerar um SDK ou para usar uma validação de solicitação para a API. Ao usar a validação de solicitação, se o corpo da solicitação do método não aderir à estrutura de dados do modelo, o API Gateway falhará na solicitação. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosInputModel", "type": "object", "properties": { "photos": { "type": "object", "required" : [ "photo" ], "properties": { "page": { "type": "integer" }, "pages": { "type": "string" }, "perpage": { "type": "integer", "minimum" : 10 }, "total": { "type": "string" }, "photo": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "owner": { "type": "string" }, "photographer_first_name" : {"type" : "string"}, "photographer_last_name" : {"type" : "string"}, "secret": { "type": "string" }, "server": { "type": "string" }, "farm": { "type": "integer" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } } } } ``` Veja a seguir um exemplo de corpo de solicitação de método que adere à estrutura de dados do modelo de dados anterior. ``` { "photos": { "page": 1, "pages": "1234", "perpage": 100, "total": "123398", "photo": [ { "id": "12345678901", "owner": "23456789@A12", "photographer_first_name" : "Saanvi", "photographer_last_name" : "Sarkar", "secret": "abc123d456", "server": "1234", "farm": 1, "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "owner": "34567890@B23", "photographer_first_name" : "Richard", "photographer_last_name" : "Roe", "secret": "bcd234e567", "server": "2345", "farm": 2, "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } } ``` Nesse exemplo, se o corpo da solicitação do método anterior foi enviado pelo cliente, esse modelo de mapeamento transforma a carga útil para corresponder ao formato exigido pelo endpoint de integração. ``` #set($inputRoot = $input.path('$')) { "photos": [ #foreach($elem in $inputRoot.photos.photo) { "id": "$elem.id", "photographedBy": "$elem.photographer_first_name $elem.photographer_last_name", "title": "$elem.title", "ispublic": $elem.ispublic, "isfriend": $elem.isfriend, "isfamily": $elem.isfamily }#if($foreach.hasNext),#end #end ] } ``` Veja no exemplo a seguir os dados de saída da transformação. ``` { "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } ``` Esses dados são enviados para a solicitação de integração e, depois, ao endpoint de integração. ## Resposta de integração e resposta do método Veja a seguir um exemplo de modelo de saída para dados de fotos do endpoint de integração. Você pode usar esse modelo como um modelo de resposta de método, que é necessário quando você gera um SDK fortemente tipado para a API. Isso faz com que a saída seja convertida em uma classe adequada em Java ou Objective-C. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosOutputModel", "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "photographedBy": { "type": "string" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } } ``` O endpoint de integração pode não responder com uma resposta que faça adesão da estrutura de dados desse modelo. A resposta de integração pode parecer com o seguinte: ``` "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "description": "My sample photo 1", "public": true, "friend": false, "family": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "description": "My sample photo 1", "public": true, "friend": false, "family": false } ] } ``` O exemplo de modelo de mapeamento a seguir transforma os dados de resposta de integração no formato esperado pela resposta do método: ``` #set($inputRoot = $input.path('$')) { "photos": [ #foreach($elem in $inputRoot.photos.photo) { "id": "$elem.id", "photographedBy": "$elem.photographer_first_name $elem.photographer_last_name", "title": "$elem.title", "ispublic": $elem.public, "isfriend": $elem.friend, "isfamily": $elem.family }#if($foreach.hasNext),#end #end ] } ``` Veja no exemplo a seguir os dados de saída da transformação. ``` { "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } ``` Esses dados são enviados para a resposta do método e, depois, de volta ao cliente. # Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway É possível usar transformações de modelos de mapeamento para substituir qualquer tipo de parâmetro de solicitação, cabeçalho de resposta ou código de status da resposta. Use um modelo de mapeamento para fazer o seguinte: + Executar mapeamentos de parâmetros muitos para um. + Substituir os parâmetros após a aplicação dos mapeamentos padrão do API Gateway + Associar parâmetros condicionalmente com base no conteúdo do corpo ou outros valores de parâmetros. + Criar parâmetros de modo programático. + Substituir os códigos de status exibidos pelo seu endpoint de integração. As substituições são feitas no final. Uma substituição só pode ser aplicada a um parâmetro por vez. Se você tentar substituir o mesmo parâmetro várias vezes, o API Gateway vai gerar uma resposta `5XX`. Se você tiver de substituir o mesmo parâmetro várias vezes em todo o modelo, é recomendável criar uma variável e aplicar a substituição no final do modelo. O modelo é aplicado somente depois que todo o modelo é analisado. ## Exemplo 1: substituir o código de status com base no corpo da integração Veja a seguir como usar a [API de exemplo](api-gateway-create-api-from-example.md) para substituir o código de status com base no corpo da resposta de integração. ------ #### [ Console de gerenciamento da AWS ] **Como substituir um código de status com base no corpo da resposta de integração** 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 **Create API** (Criar API). 1. Em **API REST**, escolha **Criar**. 1. Em **Detalhes da API**, escolha **API de exemplo**. 1. Selecione **Criar API**. O API Gateway cria uma API de exemplo da loja de animais de estimação. Para recuperar informações sobre um animal de estimação, você usa a solicitação de método de API de `GET /pets/{petId}`, em que `{petId}` é um parâmetro de caminho correspondente a um número de ID de um animal de estimação. Nesse exemplo, você substitui o código de resposta do método `GET` por `400` quando uma condição de erro é detectada. 1. Na árvore **Recursos**, selecione o método `GET` em `/{petId}`. 1. Primeiro, você testa a implementação atual da API. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. 1. Em **petId**, insira **-1** e, depois, selecione **Testar**. O **Corpo da resposta** indica um erro fora do intervalo: ``` { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] } ``` Além disso, a última linha em **Logs** termina com: `Method completed with status: 200`. A integração foi concluída com sucesso, mas houve um erro. Agora, você vai substituir o código de status com base na resposta de integração. 1. Na guia **Resposta de integração**, em **Padrão - Resposta**, selecione **Editar**. 1. Selecione **Modelos de mapeamento**. 1. Escolha **Add mapping template** (Adicionar modelo de mapeamento). 1. Em **Tipo de conteúdo**, insira **application/json**. 1. Em **Corpo do modelo**, insira o seguinte: ``` #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end ``` Esse modelo de mapeamento usa a variável `$context.responseOverride.status` para substituir o código de status por `400` se a resposta de integração contiver a string `error`. 1. Escolha **Salvar**. 1. Selecione a guia **Testar**. 1. Em **petId**, insira **-1**. 1. Nos resultados, **Response Body (Corpo da resposta)** indica um erro fora do intervalo: ``` { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] } ``` Entretanto, a última linha em **Logs** agora termina com: `Method completed with status: 400`. ------ #### [ CloudFormation ] Nesse exemplo, você usa a propriedade [corpo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar um arquivo de definição da OpenAPI para o API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: PetStore Example 1 description: Example pet store API. version: "2025-01-14T00:13:18Z" paths: /pets/{petId}: get: parameters: - name: petId in: path required: true schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId} responses: default: statusCode: "200" responseTemplates: application/json: |- #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end requestParameters: integration.request.path.petId: method.request.path.petId passthroughBehavior: when_no_match type: http components: schemas: Pet: type: object properties: id: type: integer type: type: string price: type: number ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] A definição de OpenAPI a seguir cria o recurso `GET pets/{petId}` e substitui o código de status com base no corpo da integração. ``` { "openapi" : "3.0.1", "info" : { "title" : "PetStore Example 1", "description" : "Example pet store API.", "version" : "2025-01-14T00:13:18Z" }, "paths" : { "/pets/{petId}" : { "get" : { "parameters" : [ { "name" : "petId", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}", "responses" : { "default" : { "statusCode" : "200", "responseTemplates" : { "application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end" } } }, "requestParameters" : { "integration.request.path.petId" : "method.request.path.petId" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "components" : { "schemas" : { "Pet" : { "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string" }, "price" : { "type" : "number" } } } } } } ``` ------ ## Exemplo 2: substituir o cabeçalho da solicitação e criar outros cabeçalhos O exemplo a seguir usa a [API de exemplo](api-gateway-create-api-from-example.md) para substituir o cabeçalho da solicitação e criar outros cabeçalhos. ------ #### [ Console de gerenciamento da AWS ] **Como substituir o cabeçalho de solicitação de um método criando outro cabeçalho** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha a API de exemplo que você criou no tutorial anterior. O nome da API deve ser **PetStore**. 1. Na árvore **Recursos**, selecione o método `GET` em `/pet`. 1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, selecione **Editar**. 1. Selecione **Cabeçalhos de solicitação HTTP** e, depois, **Adicionar cabeçalho**. 1. Em **Nome**, digite **header1**. 1. Selecione **Adicionar cabeçalho** e, depois, crie um segundo cabeçalho chamado **header2**. 1. Escolha **Salvar**. Agora, você combina esses cabeçalhos em um valor de cabeçalho usando um modelo de mapeamento. 1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**. 1. Em **Passagem do corpo da solicitação**, selecione **Quando não há modelos definidos (recomendado)**. 1. Selecione **Modelos de mapeamento** e, depois, faça o seguinte: 1. Escolha **Add mapping template** (Adicionar modelo de mapeamento). 1. Em **Tipo de conteúdo**, insira **application/json**. 1. Em **Corpo do modelo**, insira o seguinte: ``` #set($header1Override = "pets") #set($header3Value = "$input.params('header1')$input.params('header2')") $input.json("$") #set($context.requestOverride.header.header3 = $header3Value) #set($context.requestOverride.header.header1 = $header1Override) #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value]) ``` Esse modelo de mapeamento substitui `header1` pela string `pets` e cria um cabeçalho de vários valores chamado `$header3Value` que combina `header1` e `header2`. 1. Escolha **Salvar**. 1. Selecione a guia **Testar**. 1. Em **Cabeçalhos**, copie o seguinte código: ``` header1:header1Val header2:header2Val ``` 1. Escolha **Test** (Testar). Em **Logs**, você deve ver uma entrada que inclui este texto: ``` Endpoint request headers: {header3=header1Valheader2Val, header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id, Accept=application/json, multivalueheader=pets,header1Valheader2Val} ``` ------ #### [ CloudFormation ] Nesse exemplo, você usa a propriedade [corpo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar um arquivo de definição da OpenAPI para o API Gateway. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: PetStore Example 2 description: Example pet store API. version: "2025-01-14T00:36:18Z" paths: /pets: get: parameters: - name: header2 in: header schema: type: string - name: page in: query schema: type: string - name: type in: query schema: type: string - name: header1 in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.header1: method.request.header.header1 integration.request.header.header2: method.request.header.header2 integration.request.querystring.page: method.request.querystring.page integration.request.querystring.type: method.request.querystring.type requestTemplates: application/json: |- #set($header1Override = "pets") #set($header3Value = "$input.params('header1')$input.params('header2')") $input.json("$") #set($context.requestOverride.header.header3 = $header3Value) #set($context.requestOverride.header.header1 = $header1Override) #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value]) passthroughBehavior: when_no_match type: http components: schemas: Pet: type: object properties: id: type: integer type: type: string price: type: number ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] A definição de OpenAPI a seguir cria o recurso `GET pets`, substitui o cabeçalho da solicitação e cria outros cabeçalhos. ``` { "openapi" : "3.0.1", "info" : { "title" : "PetStore Example 2", "description" : "Example pet store API.", "version" : "2025-01-14T00:36:18Z" }, "paths" : { "/pets" : { "get" : { "parameters" : [ { "name" : "header2", "in" : "header", "schema" : { "type" : "string" } }, { "name" : "page", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "type", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "header1", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.header1" : "method.request.header.header1", "integration.request.header.header2" : "method.request.header.header2", "integration.request.querystring.page" : "method.request.querystring.page", "integration.request.querystring.type" : "method.request.querystring.type" }, "requestTemplates" : { "application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } } } ``` ------ Para usar uma substituição de modelo de mapeamento, adicione uma ou mais das variáveis `$context` a seguir. Consulte uma lista de variáveis `$context` em [Variáveis de contexto para transformações de dados](api-gateway-mapping-template-reference.md#context-variable-reference). # Tutorial: modificar a solicitação e a resposta de integração para integrações a serviços da AWS O tutorial a seguir mostra como usar transformações de modelos de mapeamento para configurar modelos de mapeamento a fim de transformar solicitações e respostas de integração usando o console e a AWS CLI. **Topics** + [Configurar transformações de dados no console do API Gateway](#mapping-example-console) + [Configurar a transformação de dados usando a CLI da AWS](#mapping-example-cli) + [Modelo CloudFormation de transformação de dados concluído](#api-gateway-data-transformations-full-cfn-stack) ## Configurar transformações de dados no console do API Gateway Neste tutorial, você criará uma API incompleta e uma tabela do DynamoDB usando o seguinte arquivo .zip [data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip). Essa API incompleta tem um recurso `/pets` com os métodos `GET` e `POST`. + O método `GET` obterá dados do endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Os dados de saída serão transformados de acordo com o modelo de mapeamento em  [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). + O método `POST` possibilitará que o usuário `POST` informações sobre animais de estimação em uma tabela do Amazon DynamoDB usando um modelo de mapeamento. Baixe e descompacte [o modelo de criação de aplicativos para CloudFormation](samples/data-transformation-tutorial-console.zip). Você usará esse modelo para criar uma tabela do DynamoDB para publicar informações sobre animais de estimação e uma API incompleta. Você concluirá o restante das etapas no console do API Gateway. **Como criar uma pilha do CloudFormation** 1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Selecione **Create stack (Criar pilha)** e **With new resources (standard) (Com novos recursos (padrão))**. 1. Em **Specify template (Especificar modelo)**, escolha **Upload a template file (Fazer upload de um arquivo de modelo)**. 1. Selecione o modelo que você baixou. 1. Escolha **Next (Próximo)**. 1. Em **Nome da pilha**, insira **data-transformation-tutorial-console** e escolha **Avançar**. 1. Para **Configurar opções de pilha**, escolha **Avançar**. 1. Para **Capabilities** (Recursos), reconheça que CloudFormation pode criar recursos do IAM em sua conta. 1. Escolha **Próximo** e, depois, **Enviar**. CloudFormationO fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Quando o status da sua pilha do CloudFormation for **CREATE\$1COMPLETE**, você estará pronto para passar para a próxima etapa. **Como testar a resposta de integração `GET`** 1. Na guia **Recursos** da pilha de CloudFormation para **data-transformation-tutorial-console**, selecione o ID físico de sua API. 1. No painel de navegação, selecione **Recursos** e, depois, selecione o método **GET**. 1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. A saída do teste mostrará o seguinte: ``` [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Você transformará esse resultado de acordo com o modelo de mapeamento em  [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). **Como transformar a resposta de integração `GET`** 1. Selecione a guia **Resposta de integração**. Atualmente, não há modelos de mapeamento definidos, portanto, a resposta de integração não será transformada. 1. Em **Padrão - Resposta**, selecione **Editar**. 1. Selecione **Modelos de mapeamento** e, depois, faça o seguinte: 1. Escolha **Add mapping template** (Adicionar modelo de mapeamento). 1. Em **Tipo de conteúdo**, insira **application/json**. 1. Em **Corpo do modelo**, insira o seguinte: ``` #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ] ``` Escolha **Salvar**. **Como testar a resposta de integração `GET`** + Selecione a guia **Testar** e, depois, **Testar**. A saída do teste mostrará a resposta transformada. ``` [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] ``` **Como transformar dados de entrada do método `POST`** 1. Selecione o método **POST**. 1. Selecione a guia **Solicitação de integração** e, em **Configurações de solicitação de integração**, selecione **Editar**. O modelo CloudFormation preencheu alguns dos campos da solicitação de integração. + O tipo de integração é AWS service (Serviço da AWS). + O AWS service (Serviço da AWS) é o DynamoDB. + O método HTTP é o `POST`. + A ação é `PutItem`. + O perfil de execução que possibilita que o API Gateway coloque um item na tabela do DynamoDB é `data-transformation-tutorial-console-APIGatewayRole`. O CloudFormation criou esse perfil para possibilitar que o API Gateway tenha as permissões mínimas para interagir com o DynamoDB. O nome da tabela do DynamoDB não foi especificado. Você especificará o nome nas etapas a seguir. 1. Em **Passagem do corpo da solicitação**, selecione **Nunca**. Isso significa que a API rejeitará dados com tipos de conteúdo que não tenham um modelo de mapeamento. 1. Selecione **Modelos de mapeamento**. 1. O **Tipo de conteúdo** é definido como `application/json`. Isso significa que tipos de conteúdo que não sejam application/json serão rejeitados pela API. Para obter mais informações sobre os comportamentos de passagem direta de integração, consulte . [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md) 1. Insira o código a seguir no editor de texto. ``` { "TableName":"data-transformation-tutorial-console-ddb", "Item": { "id": { "N": $input.json("$.id") }, "type": { "S": $input.json("$.type") }, "price": { "N": $input.json("$.price") } } } ``` Esse modelo especifica a tabela como `data-transformation-tutorial-console-ddb` e define os itens como `id`, `type` e `price`. Os itens virão do corpo do método `POST`. Você também pode usar um modelo de dados para ajudar a criar um modelo de mapeamento. Para obter mais informações, consulte [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md). 1. Escolha **Salvar** para salvar seu modelo de mapeamento. **Como adicionar um método e uma resposta de integração do método `POST`** O CloudFormation criou um método em branco e uma resposta de integração. Você editará essa resposta para fornecer mais informações. Para ter mais informações sobre como editar respostas, consulte [Exemplos de mapeamento de parâmetros para APIs REST no API Gateway](request-response-data-mappings.md). 1. Na guia **Resposta de integração**, em **Padrão - Resposta**, selecione **Editar**. 1. Selecione **Modelos de mapeamento** e, depois, **Adicionar modelo de mapeamento**. 1. Em **Tipo de conteúdo**, insira **application/json**. 1. No editor de código, insira o seguinte modelo de mapeamento de saída para enviar uma mensagem de saída: ``` { "message" : "Your response was recorded at $context.requestTime" } ``` Para ter mais informações sobre variáveis de contexto, consulte [Variáveis de contexto para transformações de dados](api-gateway-mapping-template-reference.md#context-variable-reference). 1. Escolha **Salvar** para salvar seu modelo de mapeamento. **Testar o método `POST`** Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. 1. No corpo da solicitação, insira o exemplo a seguir. ``` { "id": "4", "type" : "dog", "price": "321" } ``` 1. Escolha **Testar**. A saída deve mostrar sua mensagem de êxito. Você pode abrir o console do DynamoDB em [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) para verificar se o item de exemplo está na sua tabela. **Para excluir uma pilha do CloudFormation** 1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Selecione sua pilha do CloudFormation. 1. Escolha **Excluir** e, em seguida, confirme sua escolha. ## Configurar a transformação de dados usando a CLI da AWS Neste tutorial, você criará uma API incompleta e uma tabela do DynamoDB usando o arquivo .zip [data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-cli.zip) a seguir. Essa API incompleta tem um recurso `/pets` com um método `GET` integrado ao endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Você criará um método `POST` para se conectar a uma tabela do DynamoDB e usará modelos de mapeamento para inserir dados em uma tabela do DynamoDB. + Você transformará os dados de saída de acordo com o modelo de mapeamento em  [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). + Você criará um método `POST` para possibilitar que o usuário `POST` informações sobre animais de estimação em uma tabela do Amazon DynamoDB usando um modelo de mapeamento. **Como criar uma pilha do CloudFormation** Baixe e descompacte [o modelo de criação de aplicativos para CloudFormation](samples/data-transformation-tutorial-cli.zip). Para concluir o tutorial a seguir, é necessária a [AWS Command Line Interface (AWS CLI) versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). Para comandos longos, um caractere de escape (`\`) é usado para dividir um comando em várias linhas. **nota** No Windows, alguns comandos da CLI do Bash que você costuma usar (como `zip`) não são compatíveis com os terminais integrados do sistema operacional. Para obter uma versão do Ubuntu com o Bash integrada no Windows, [instale o Subsistema do Windows para Linux](https://learn.microsoft.com/en-us/windows/wsl/install). Os exemplos de comandos da CLI neste guia usam a formatação Linux. Os comandos que incluem documentos JSON em linha deverão ser reformatados se você estiver usando a CLI do Windows. 1. Use o comando a seguir para criar a pilha de CloudFormation. ``` aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM ``` 1. CloudFormationO fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Use o comando a seguir para ver o status de sua pilha de CloudFormation. ``` aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli ``` 1. Quando o status da sua pilha de CloudFormation for `StackStatus: "CREATE_COMPLETE"`, use o comando a seguir para recuperar valores de saída relevantes para etapas futuras. ``` aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}" ``` Os valores de saída são os seguintes: + ApiRole, que é o nome do perfil que possibilita que o API Gateway coloque itens na tabela do DynamoDB. Para este tutorial, o nome do perfil é `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`. + DDBTableName, que é o nome da tabela do DynamoDB. Para este tutorial, o nome da tabela é `data-transformation-tutorial-cli-ddb`. + ResourceId, que é o ID do recurso de animais de estimação em que os métodos `GET` e `POST` são expostos. Para este tutorial, o ID do recurso é `efg456`. + ApiId, que é o ID da API. Para este tutorial, o ID da API é `abc123`. **Como testar o método `GET` antes da transformação de dados** + Use o comando a seguir para testar o método `GET`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET ``` A saída do teste mostrará o seguinte: ``` [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Você transformará esse resultado de acordo com o modelo de mapeamento em  [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). **Como transformar a resposta de integração `GET`** + Use o comando a seguir para atualizar a resposta de integração do método `GET`. Substitua o *rest-api-id* e o *resource-id* pelos seus valores. Use o comando a seguir para criar uma resposta de integração. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --status-code 200 \ --selection-pattern "" \ --response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}' ``` **Como testar o método `GET`** + Use o comando a seguir para testar o método `GET`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ ``` A saída do teste mostrará a resposta transformada. ``` [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] ``` **Como criar um método `POST`** 1. Use o comando a seguir para criar um novo método no recurso `/pets`. ``` aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --authorization-type "NONE" \ ``` Esse método possibilitará que você envie informações sobre animais de estimação para a tabela do DynamoDB que você criou na pilha de CloudFormation. 1. Use o comando a seguir para criar uma integração do AWS service (Serviço da AWS) no método `POST`. ``` aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --type AWS \ --integration-http-method POST \ --uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \ --credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \ --request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}' ``` 1. Use o comando a seguir para criar uma resposta de método para uma chamada bem-sucedida do método `POST`. ``` aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 ``` 1. Use o comando a seguir para criar uma resposta de integração para uma chamada bem-sucedida do método `POST`. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 \ --selection-pattern "" \ --response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}' ``` **Como testar o método `POST`** + Use o comando a seguir para testar o método `POST`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}' ``` A saída mostrará a mensagem de êxito. **Para excluir uma pilha do CloudFormation** + Use o comando a seguir para excluir seus recursos de CloudFormation. ``` aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli ``` ## Modelo CloudFormation de transformação de dados concluído O exemplo a seguir é um modelo de CloudFormation completo, que cria uma API e uma tabela do DynamoDB com um recurso `/pets` com os métodos `GET` e `POST`. + O método `GET` obterá dados do endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Os dados de saída serão transformados de acordo com o modelo de mapeamento em  [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). + O método `POST` possibilitará que o usuário `POST` informações sobre animais de estimação em uma tabela do DynamoDB usando um modelo de mapeamento. ### Exemplo de modelo CloudFormation ``` AWSTemplateFormatVersion: 2010-09-09 Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data. Parameters: StageName: Type: String Default: v1 Description: Name of API stage. Resources: DynamoDBTable: Type: 'AWS::DynamoDB::Table' Properties: TableName: !Sub data-transformation-tutorial-complete AttributeDefinitions: - AttributeName: id AttributeType: N KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5 APIGatewayRole: Type: 'AWS::IAM::Role' Properties: AssumeRolePolicyDocument: Version: 2012-10-17 Statement: - Action: - 'sts:AssumeRole' Effect: Allow Principal: Service: - apigateway.amazonaws.com Policies: - PolicyName: APIGatewayDynamoDBPolicy PolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Action: - 'dynamodb:PutItem' Resource: !GetAtt DynamoDBTable.Arn Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: data-transformation-complete-api ApiKeySourceType: HEADER PetsResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'pets' PetsMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: HTTP Credentials: !GetAtt APIGatewayRole.Arn IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ PassthroughBehavior: WHEN_NO_TEMPLATES IntegrationResponses: - StatusCode: '200' ResponseTemplates: application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]" MethodResponses: - StatusCode: '200' PetsMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: POST ApiKeyRequired: false AuthorizationType: NONE Integration: Type: AWS Credentials: !GetAtt APIGatewayRole.Arn IntegrationHttpMethod: POST Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem PassthroughBehavior: NEVER RequestTemplates: application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}" IntegrationResponses: - StatusCode: 200 ResponseTemplates: application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}" MethodResponses: - StatusCode: '200' ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' Outputs: ApiId: Description: API ID for CLI commands Value: !Ref Api ResourceId: Description: /pets resource ID for CLI commands Value: !Ref PetsResource ApiRole: Description: Role ID to allow API Gateway to put and scan items in DynamoDB table Value: !Ref APIGatewayRole DDBTableName: Description: DynamoDB table name Value: !Ref DynamoDBTable ``` # Exemplos de uso de variáveis para mapear transformações de modelos para o API Gateway Os exemplos a seguir mostram como usar as variáveis `$context`, `input` e `util` em modelos de mapeamento. Você pode usar uma integração simulada ou uma integração sem proxy do Lambda que retorna o evento de entrada ao API Gateway. Consulte uma lista de variáveis compatíveis com transformadores de dados em [Variáveis para transformações de dados para o API Gateway](api-gateway-mapping-template-reference.md). ## Exemplo 1: passar várias variáveis `$context` ao endpoint de integração O exemplo a seguir mostra um modelo de mapeamento que mapeia variáveis `$context` de entrada para variáveis de backend com nomes um pouco diferentes em uma carga de solicitação de integração: ``` { "stage" : "$context.stage", "request_id" : "$context.requestId", "api_id" : "$context.apiId", "resource_path" : "$context.resourcePath", "resource_id" : "$context.resourceId", "http_method" : "$context.httpMethod", "source_ip" : "$context.identity.sourceIp", "user-agent" : "$context.identity.userAgent", "account_id" : "$context.identity.accountId", "api_key" : "$context.identity.apiKey", "caller" : "$context.identity.caller", "user" : "$context.identity.user", "user_arn" : "$context.identity.userArn" } ``` A saída deste modelo de mapeamento deve ser semelhante ao seguinte: ``` { stage: 'prod', request_id: 'abcdefg-000-000-0000-abcdefg', api_id: 'abcd1234', resource_path: '/', resource_id: 'efg567', http_method: 'GET', source_ip: '192.0.2.1', user-agent: 'curl/7.84.0', account_id: '111122223333', api_key: 'MyTestKey', caller: 'ABCD-0000-12345', user: 'ABCD-0000-12345', user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar' } ``` Uma das variáveis é uma chave de API. Este exemplo pressupõe que o método exige a chave de API. ## Exemplo 2: passar todos os parâmetros de solicitação ao endpoint de integração por meio de uma carga útil JSON: O exemplo a seguir passa todos os parâmetros de solicitação, incluindo os parâmetros `path`, `querystring` e `header`, ao endpoint de integração por meio de uma carga útil JSON: ``` #set($allParams = $input.params()) { "params" : { #foreach($type in $allParams.keySet()) #set($params = $allParams.get($type)) "$type" : { #foreach($paramName in $params.keySet()) "$paramName" : "$util.escapeJavaScript($params.get($paramName))" #if($foreach.hasNext),#end #end } #if($foreach.hasNext),#end #end } } ``` Se uma solicitação tiver estes parâmetros de entrada: + Um parâmetro de caminho chamado `myparam` + Parâmetros de string de consulta `querystring1=value1,value2` + Cabeçalhos `"header1" : "value1"`. A saída deste modelo de mapeamento deve ser semelhante ao seguinte: ``` {"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}} ``` ## Exemplo 3: passar uma subseção de uma solicitação de método para o endpoint de integração O exemplo a seguir usa o parâmetro de entrada `name` para recuperar somente o parâmetro `name` e o parâmetro de entrada `input.json('$')` para recuperar todo o corpo da solicitação do método: ``` { "name" : "$input.params('name')", "body" : $input.json('$') } ``` Para uma solicitação que inclua os parâmetros de string de consulta `name=Bella&type=dog` e o seguinte corpo: ``` { "Price" : "249.99", "Age": "6" } ``` A saída deste modelo de mapeamento deve ser semelhante ao seguinte: ``` { "name" : "Bella", "body" : {"Price":"249.99","Age":"6"} } ``` Esse modelo de mapeamento remove o parâmetro da string de consulta `type=dog`. Se a entrada JSON contiver caracteres sem escape que não podem ser analisados pelo JavaScript, o API Gateway pode retornar uma resposta 400. Aplique `$util.escapeJavaScript($input.json('$'))` para garantir que a entrada JSON possa ser analisada corretamente. O exemplo anterior com `$util.escapeJavaScript($input.json('$'))` aplicado é o seguinte: ``` { "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$'))" } ``` Neste caso, a saída deste modelo de mapeamento deve ser semelhante ao seguinte: ``` { "name" : "Bella", "body": {"Price":"249.99","Age":"6"} } ``` ## Exemplo 4: usar a expressão JSONPath para passar uma subseção de uma solicitação de método ao endpoint de integração O exemplo a seguir usa expressões JSONPath para recuperar somente o parâmetro de entrada `name` e o `Age` do corpo da solicitação: ``` { "name" : "$input.params('name')", "body" : $input.json('$.Age') } ``` Para uma solicitação que inclua os parâmetros de string de consulta `name=Bella&type=dog` e o seguinte corpo: ``` { "Price" : "249.99", "Age": "6" } ``` A saída deste modelo de mapeamento deve ser semelhante ao seguinte: ``` { "name" : "Bella", "body" : "6" } ``` Esse modelo de mapeamento remove o parâmetro da string de consulta `type=dog` e o campo `Price` do corpo. Se uma carga útil de solicitação de método contiver caracteres sem escape que não podem ser analisados por JavaScript, o API Gateway pode retornar uma resposta `400`. Aplique `$util.escapeJavaScript()` para garantir que a entrada JSON possa ser analisada corretamente. O exemplo anterior com `$util.escapeJavaScript($input.json('$.Age'))` aplicado é o seguinte: ``` { "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$.Age'))" } ``` Neste caso, a saída deste modelo de mapeamento deve ser semelhante ao seguinte: ``` { "name" : "Bella", "body": "\"6\"" } ``` ## Exemplo 5: usar uma expressão JSONPath para passar informações sobre uma solicitação de método ao endpoint de integração O exemplo a seguir usa `$input.params()`, `$input.path()` e `$input.json()` para enviar informações sobre uma solicitação de método ao endpoint de integração. Esse modelo de mapeamento usa o método `size()` para fornecer o número de elementos em uma lista. ``` { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : $input.json('$.things') } ``` Para uma solicitação que inclui o parâmetro de caminho `123` e o seguinte corpo: ``` { "things": { "1": {}, "2": {}, "3": {} } } ``` A saída deste modelo de mapeamento deve ser semelhante ao seguinte: ``` {"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}} ``` Se uma carga útil de solicitação de método contiver caracteres sem escape que não podem ser analisados por JavaScript, o API Gateway pode retornar uma resposta `400`. Aplique `$util.escapeJavaScript()` para garantir que a entrada JSON possa ser analisada corretamente. O exemplo anterior com `$util.escapeJavaScript($input.json('$.things'))` aplicado é o seguinte: ``` { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : "$util.escapeJavaScript($input.json('$.things'))" } ``` A saída deste modelo de mapeamento deve ser semelhante ao seguinte: ``` {"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"} ``` # Variáveis para transformações de dados para o API Gateway Ao criar um mapeamento de parâmetros, é possível usar variáveis de contexto como a fonte de dados. Ao criar transformações de modelos de mapeamento, é possível usar variáveis de utilidade, entrada e contexto em scripts que você escreve na [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Consulte exemplos de modelos de mapeamento que usam essas variáveis de referência em [Exemplos de uso de variáveis para mapear transformações de modelos para o API Gateway](api-gateway-mapping-variable-examples.md). Consulte uma lista de variáveis de referência para registro em log de acesso em [Variáveis para registro em log de acesso no API Gateway](api-gateway-variables-for-access-logging.md). ## Variáveis de contexto para transformações de dados É possível usar as variáveis `$context` a seguir para transformações de dados. | Parameter | Descrição | | --- | --- | | \$1context.accountId | O ID da conta da AWS do proprietário da API | | \$1context.apiId | O identificador que o API Gateway atribui à sua API. | | \$1context.authorizer.claims.property | Uma propriedade das declarações retornadas do grupo de usuários do Amazon Cognito depois que o autor da chamada do método é autenticado com êxito. Para obter mais informações, consulte [Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). Chamar `$context.authorizer.claims` retorna um valor nulo. | | \$1context.authorizer.principalId | A identificação do usuário principal associada ao token enviado pelo cliente e retornada a partir de um autorizador do Lambda do API Gateway (anteriormente conhecido como autorizador personalizado). Para obter mais informações, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.property | O valor transformado em string do par de chave/valor especificado do mapa `context` retornado de uma função de autorizador do Lambda do API Gateway. Por exemplo, se o autorizador retornar o seguinte mapa `context`: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
Chamar `$context.authorizer.key` retornará a string `"value"`, chamar `$context.authorizer.numKey` retornará a string `"1"` e chamar `$context.authorizer.boolKey` retornará a string `"true"`. Com relação à *propriedade*, o único caractere especial aceito é o sublinhado `(_)`. Para obter mais informações, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md). | | \$1context.awsEndpointRequestId | O ID da solicitação do endpoint da AWS. | | \$1context.deploymentId | O ID da implantação de API. | | \$1context.domainName | O nome de domínio completo usado para invocar a API. Ele deve ser o mesmo que o cabeçalho `Host` de entrada. | | \$1context.domainPrefix | O primeiro rótulo do `$context.domainName`. | | \$1context.error.message | Uma string que contém uma mensagem de erro do API Gateway. Essa variável pode ser usada apenas para substituição de variável simples em um modelo de mapeamento de corpo [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), que não é processado pelo mecanismo Velocity Template Language, bem como no registro de acesso. Para obter mais informações, consulte [Monitorar a execução de APIs de WebSocket com métricas do CloudWatch](apigateway-websocket-api-logging.md) e [Configurar respostas do gateway para personalizar respostas de erro](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.messageString | O valor citado de \$1context.error.message, ou seja, "\$1context.error.message". | | \$1context.error.responseType | Um [tipo](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Essa variável pode ser usada apenas para substituição de variável simples em um modelo de mapeamento de corpo [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), que não é processado pelo mecanismo Velocity Template Language, bem como no registro de acesso. Para obter mais informações, consulte [Monitorar a execução de APIs de WebSocket com métricas do CloudWatch](apigateway-websocket-api-logging.md) e [Configurar respostas do gateway para personalizar respostas de erro](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.validationErrorString | Uma string que contém uma mensagem de erro de validação detalhada. | | \$1context.extendedRequestId | O ID estendido que o API Gateway gera e atribui à solicitação de API. O ID de solicitação estendido contém informações úteis para a depuração e solução de problemas. | | \$1context.httpMethod | O método HTTP utilizado. Os valores válidos incluem: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. | | \$1context.identity.accountId | O ID da conta da AWS associado à solicitação. | | \$1context.identity.apiKey | Para os métodos de API que exigem uma chave de API, essa variável é a chave de API associada à solicitação do método. Para métodos que não exigem uma chave de API, essa variável é um valor nulo. Para obter mais informações, consulte [Usar planos e chaves de API para APIs REST no APIs Gateway](api-gateway-api-usage-plans.md). | | \$1context.identity.apiKeyId | O ID da chave de API associada a uma solicitação de API que exige uma chave de API. | | \$1context.identity.caller | O identificador principal da entidade do autor da chamada que assinou a solicitação. Compatível com recursos que usam a autorização do IAM. | | \$1context.identity.cognitoAuthenticationProvider | Uma lista separada por vírgulas de todos os provedores de autenticação do Amazon Cognito usados pelo autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Por exemplo, para uma identidade de um grupo de usuários do Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Consulte informações sobre os provedores de autenticação do Amazon Cognito disponível em [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) no *Guia do desenvolvedor do Amazon Cognito*. | | \$1context.identity.cognitoAuthenticationType | O tipo de autenticação do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Os valores possíveis incluem `authenticated` para identidades autenticadas e `unauthenticated` para identidades não autenticadas. | | \$1context.identity.cognitoIdentityId | O ID de identidade do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | O ID do grupo de identidades do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. | | \$1context.identity.principalOrgId | O [ID da organização da AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). | | \$1context.identity.sourceIp | O endereço IP de origem da conexão TCP mais próxima que está fazendo a solicitação ao endpoint do API Gateway. | | \$1context.identity.clientCert.clientCertPem | O certificado de cliente codificado por PEM que o cliente apresentou durante a autenticação TLS mútua. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. | | \$1context.identity.clientCert.subjectDN | O nome distinto do assunto do certificado apresentado por um cliente. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. | | \$1context.identity.clientCert.issuerDN | O nome distinto do emissor do certificado apresentado por um cliente. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. | | \$1context.identity.clientCert.serialNumber | O número de série do certificado. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. | | \$1context.identity.clientCert.validity.notBefore | A data antes da qual o certificado é inválido. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. | | \$1context.identity.clientCert.validity.notAfter | A data após a qual o certificado é inválido. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. | | \$1context.identity.vpcId | O ID da VPC que está fazendo a solicitação ao endpoint do API Gateway. | | \$1context.identity.vpceId | O ID do endpoint da VPC que está fazendo a solicitação ao endpoint do API Gateway. Presente somente quando você tem uma API privada. | | \$1context.identity.user | O identificador principal da entidade do usuário que será autorizado contra o acesso a recursos. Compatível com recursos que usam a autorização do IAM. | | \$1context.identity.userAgent | O cabeçalho [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) do autor da chamada da API. | | \$1context.identity.userArn | O Nome do Recurso Amazon (ARN) do usuário efetivo identificado após a autenticação. Para obter mais informações, consulte [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). | | \$1context.isCanaryRequest | Retorna `true` se a solicitação foi direcionada ao canário e `false` se a solicitação não foi direcionada ao canário. Presente somente quando você tem um canário habilitado. | | \$1context.path | O caminho da solicitação. Por exemplo, para um URL de solicitação sem proxy de https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, o valor \$1context.path é /\$1stage\$1/root/child. | | \$1context.protocol | O protocolo de solicitação, por exemplo, , HTTP/1.1. As APIs do API Gateway podem aceitar solicitações HTTP/2, mas o API Gateway envia solicitações para integrações de back-end usando HTTP/1.1. Como resultado, o protocolo de solicitação é registrado como HTTP/1.1 mesmo se um cliente enviar uma solicitação que usa HTTP/2. | | \$1context.requestId | Um ID para a solicitação. Os clientes podem substituir esse ID de solicitação. Usar `$context.extendedRequestId` para um ID de solicitação exclusivo gerado pelo API Gateway. | | \$1context.requestOverride.header.header\$1name | Substituição do cabeçalho da solicitação. Esse parâmetro, quando definido, contém os cabeçalhos a serem usados em lugar dos **HTTP Headers (Cabeçalhos HTTP)** que são definidos no painel **Integration Request (Solicitação de integração)**. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.path.path\$1name | Substituição do caminho da solicitação. Esse parâmetro, quando definido, contém o caminho da solicitação a ser usado em lugar dos **URL Path Parameters (Parâmetros de caminho de URL)** que são definidos no painel **Integration Request (Solicitação de integração)**. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.querystring.querystring\$1name | Substituição da string de consulta da solicitação. Esse parâmetro, quando definido, contém as strings de consulta da solicitação a serem usadas em lugar dos **URL Query String Parameters (Parâmetros de string de consulta de URL)** que são definidos no painel **Integration Request (Solicitação de integração)**. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.header.header\$1name | Substituição do cabeçalho da resposta. Esse parâmetro, quando definido, contém o cabeçalho a ser retornado em lugar do Response header (Cabeçalho de resposta) que é definido como o Default mapping (Mapeamento padrão) no painel Integration Response (Resposta de integração). Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.status | Substituição do código de status da resposta. Esse parâmetro, quando definido, contém o código de status a ser retornado em lugar do Method response status (Status de resposta de método) que é definido como o Default mapping (Mapeamento padrão) no painel Integration Response (Resposta de integração). Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestTime | O horário da solicitação [CLF](https://httpd.apache.org/docs/current/logs.html#common) formatado (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | O tempo de solicitação formatado em [Epoch](https://en.wikipedia.org/wiki/Unix_time), em milissegundos. | | \$1context.resourceId | O identificador que o API Gateway atribui ao seu recurso. | | \$1context.resourcePath | O caminho para o seu recurso. Por exemplo, para a URI de solicitação sem proxy de `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, o valor `$context.resourcePath` é `/root/child`. Para obter mais informações, consulte [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md). | | \$1context.stage | O estágio de implantação da solicitação de API (por exemplo, `Beta` ou `Prod`). | | \$1context.wafResponseCode | A resposta recebida do [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` ou `WAF_BLOCK`. Não será definido se o estágio não estiver associado a uma ACL da web. Para obter mais informações, consulte [Usar o AWS WAF para proteger as APIs REST no API Gateway](apigateway-control-access-aws-waf.md). | | \$1context.webaclArn | O ARN completo da ACL da web que é utilizada para decidir se deseja permitir ou bloquear a solicitação. Não será definido se o estágio não estiver associado a uma ACL da web. Para obter mais informações, consulte [Usar o AWS WAF para proteger as APIs REST no API Gateway](apigateway-control-access-aws-waf.md). | ## Variáveis de entrada É possível usar as variáveis `$input` com distinção de maiúsculas e minúsculas a seguir para se referir à carga útil e aos parâmetros de solicitação de método. As seguintes funções estão disponíveis: | Variável e função | Descrição | | --- | --- | | \$1input.body | Retorna a carga de solicitação bruta como uma string. É possível usar `$input.body` para preservar números inteiros de ponto flutuante, como `10.00`. | | \$1input.json(x) | Essa função avalia uma expressão JSONPath e retorna os resultados como uma string JSON. Por exemplo, `$input.json('$.pets')` retorna uma string JSON que representa a estrutura `pets`. Para obter mais informações sobre o JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) ou [JSONPath para Java](https://github.com/json-path/JsonPath). | | \$1input.params() | Retorna um mapa de todos os parâmetros de solicitação. Recomendamos que você use `$util.escapeJavaScript` para higienizar o resultado a fim de evitar um potencial ataque de injeção. Para o controle total da higienização de solicitações, use uma integração de proxy sem um modelo e realize a higienização de solicitações em sua integração. | | \$1input.params(x) | Retorna o valor de um parâmetro de solicitação do método do caminho, da string de consulta ou do valor de cabeçalho (pesquisados nessa ordem), considerando uma string de nome do parâmetro `x`. Recomendamos que você use `$util.escapeJavaScript` para higienizar o parâmetro a fim de evitar um potencial ataque de injeção. Para o controle total da higienização de parâmetros, use uma integração de proxy sem um modelo e realize a higienização de solicitações em sua integração. | | \$1input.path(x) | Usa uma string de expressão JSONPath (`x`) e retorna uma representação de objeto JSON do resultado. Isso permite que você acesse e manipule elementos da carga nativamente em [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Por exemplo, se a expressão `$input.path('$.pets')` retorna um objeto da seguinte forma: 
[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]
`$input.path('$.pets').size()` retornaria `"3"`. Para obter mais informações sobre o JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) ou [JSONPath para Java](https://github.com/json-path/JsonPath). | ## Variáveis de estágio É possível usar as seguintes variáveis de estágio como espaços reservados para ARNs e URLs em integrações de método. Para obter mais informações, consulte [Usar variáveis de estágio para uma API REST no API Gateway](stage-variables.md). | Sintaxe | Descrição | | --- | --- | | \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'], ou \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* representa um nome de variável de estágio. | ## Variáveis de utilidade É possível usar as variáveis `$util` com distinção de maiúsculas e minúsculas a seguir para utilizar funções utilitárias para associar modelos. A menos que especificado de outra forma, o conjunto de caracteres padrão é UTF-8. | Função | Descrição | | --- | --- | | \$1util.escapeJavaScript() | Escapa os caracteres em uma string usando regras de string JavaScript. Essa função transformará quaisquer aspas simples comuns (`'`) em aspas com escape (`\'`). No entanto, as aspas simples com escape não são válidas no JSON. Portanto, quando a saída dessa função for usada em uma propriedade JSON, você deverá transformar todas aspas simples (`\'`) com escape de volta para aspas simples comuns (`'`). Isso é mostrado no exemplo a seguir: 
 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
| | \$1util.parseJson() | Usa um JSON "transformado em string" e retorna uma representação de objeto do resultado. Você pode usar o resultado dessa função para acessar e manipular elementos da carga nativamente em Apache VTL (Velocity Template Language). Por exemplo, se tiver a seguinte carga: 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
e usar o seguinte modelo de mapeamento 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Você receberá a seguinte saída: 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | Converte uma string no formato "application/x-www-form-urlencoded". | | \$1util.urlDecode() | Decodifica uma string "application/x-www-form-urlencoded". | | \$1util.base64Encode() | Codifica os dados em uma string codificada em base64. | | \$1util.base64Decode() | Decodifica os dados de uma string codificada em base64. | # Respostas do gateway para APIs REST no API Gateway Uma resposta do gateway é identificada por um tipo de resposta definido pelo API Gateway. Essa resposta consiste em um código de status HTTP, um conjunto de cabeçalhos adicionais que são especificados por mapeamentos de parâmetros e uma carga útil que é gerada por um modelo de mapeamento não [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html). Na API REST do API Gateway, uma resposta de gateway é representada por [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). No OpenAPI, uma instância de `GatewayResponse` é descrita pela extensão [x-amazon-apigateway-gateway-responses.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md). Para permitir uma resposta de gateway, você configura uma resposta de gateway para um [tipo de resposta com suporte](supported-gateway-response-types.md) em nível de API. Sempre que o API Gateway retorna uma resposta desse tipo, os mapeamentos de cabeçalho e os modelos de mapeamento de carga útil definidos na resposta de gateway são aplicados para retornar os resultados mapeados ao autor da chamada da API. Na seção a seguir, mostramos como configurar respostas de gateway usando o console do API Gateway e a API REST do API Gateway. ## Configurar respostas do gateway para personalizar respostas de erro Se o API Gateway falhar ao processar uma solicitação de entrada, ele retornará ao cliente uma resposta de erro sem encaminhar essa solicitação ao backend de integração. Por padrão, a resposta de erro contém uma breve mensagem de erro descritiva. Por exemplo, se você tentar chamar uma operação em um recurso de API indefinido, receberá uma resposta de erro com a mensagem `{ "message": "Missing Authentication Token" }`. Se você não tem experiência com o API Gateway, talvez ache difícil compreender o que exatamente deu errado. Para algumas das respostas de erro, o API Gateway permite personalização pelos desenvolvedores de APIs, de modo a retornar as respostas em diferentes formatos. Para o exemplo `Missing Authentication Token`, você pode adicionar uma dica à carga de resposta original com a causa possível, como neste exemplo: `{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`. Quando a API faz a intermediação entre um intercâmbio externo e a Nuvem AWS, você usa modelos de mapeamento VTL para a solicitação de integração ou a resposta de integração para mapear a carga útil de um formato para outro. No entanto, os modelos de mapeamento VTL funcionam apenas para solicitações válidas com respostas bem-sucedidas. Para solicitações inválidas, o API Gateway ignora completamente a integração e retorna uma resposta de erro. É necessário usar a personalização para renderizar as respostas de erro em um formato compatível com intercâmbio. Aqui, a personalização é renderizada em um modelo de mapeamento não VTL que oferece suporte apenas substituições de variáveis simples. Generalizando a resposta de erro gerada pelo API Gateway para todas as respostas geradas pelo API Gateway, nós as chamamos de *respostas de gateway*. Isso distingue as respostas geradas pelo API Gateway das respostas de integração. Um modelo de mapeamento de resposta de gateway pode acessar valores de variáveis `$context` e valores de propriedades `$stageVariables`, bem como parâmetros de solicitação de método, no formato `method.request.param-position.param-name`. Para obter mais informações sobre variáveis `$context`, consulte [Variáveis de contexto para transformações de dados](api-gateway-mapping-template-reference.md#context-variable-reference). Para obter mais informações sobre o `$stageVariables`, consulte [Variáveis de estágio](api-gateway-mapping-template-reference.md#stagevariables-template-reference). Para obter mais informações sobre parâmetros de solicitação de método, consulte [Variáveis de entrada](api-gateway-mapping-template-reference.md#input-variable-reference). **Topics** + [Configurar respostas do gateway para personalizar respostas de erro](#customize-gateway-responses) + [Configurar uma resposta de gateway para uma API REST usando o console do API Gateway](set-up-gateway-response-using-the-console.md) + [Configurar uma resposta de gateway usando a API REST do API Gateway](set-up-gateway-response-using-the-api.md) + [Configurar a personalização da resposta de gateway no OpenAPI](set-up-gateway-responses-in-swagger.md) + [Tipos de resposta de gateway do API Gateway](supported-gateway-response-types.md) # Configurar uma resposta de gateway para uma API REST usando o console do API Gateway O exemplo a seguir mostra como configurar uma resposta de gateway para uma API REST usando o console do API Gateway **Para personalizar uma resposta de gateway 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. Escolha uma API REST. 1. No painel de navegação principal, selecione **Respostas do gateway**. 1. Escolha um tipo de resposta e selecione **Editar**. Nesta demonstração, usamos **Token de autenticação ausente** como exemplo. 1. Você pode alterar o **Código de status** gerado pelo API Gateway para retornar um código de status diferente que atenda aos requisitos da API. Neste exemplo, a personalização altera o código de status de padrão (`403`) para `404` porque esta mensagem de erro ocorre quando um cliente chama um recurso inválido ou incompatível que pode ser considerado como não encontrado. 1. Para retornar os cabeçalhos personalizados, selecione **Adicionar cabeçalho de resposta** em **Cabeçalhos de resposta**. Para fins de ilustração, adicionamos os seguintes cabeçalhos personalizados: ``` Access-Control-Allow-Origin:'a.b.c' x-request-id:method.request.header.x-amzn-RequestId x-request-path:method.request.path.petId x-request-query:method.request.querystring.q ``` Nos mapeamentos de cabeçalho anteriores, um nome de domínio estático (`'a.b.c'`) é mapeado para o cabeçalho `Allow-Control-Allow-Origin`, para permitir acesso do CORS à API, o cabeçalho da solicitação de entrada de `x-amzn-RequestId` é mapeado para `request-id` na resposta, a variável de caminho `petId` da solicitação de entrada é mapeada para o cabeçalho `request-path` na resposta e o parâmetro de consulta `q` da solicitação original é mapeado para o cabeçalho `request-query` da resposta. 1. Em **Modelos de resposta**, mantenha `application/json` para **Tipo de conteúdo** e insira o seguinte modelo de mapeamento de corpo no editor do **Corpo do modelo**: ``` { "message":"$context.error.messageString", "type": "$context.error.responseType", "statusCode": "'404'", "stage": "$context.stage", "resourcePath": "$context.resourcePath", "stageVariables.a": "$stageVariables.a" } ``` Este exemplo mostra como mapear as propriedades `$context` e `$stageVariables` para propriedades do corpo de resposta de gateway. 1. Escolha **Salvar alterações**. 1. Implantar a API em um estágio novo ou existente. Teste a resposta do gateway chamando o seguinte comando CURL, pressupondo que o URL de invocação do método da API correspondente seja `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}`: ``` curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1 ``` Como o parâmetro de string de consulta extra `q=1` não é compatível com a API, um erro é retornado da resposta do gateway especificado. Você receberá uma resposta do gateway semelhante à seguinte: ``` > GET /custErr/pets/5?q=1 HTTP/1.1 Host: o81lxisefl.execute-api.us-east-1.amazonaws.com User-Agent: curl/7.51.0 Accept: */* HTTP/1.1 404 Not Found Content-Type: application/json Content-Length: 334 Connection: keep-alive Date: Tue, 02 May 2017 03:15:47 GMT x-amzn-RequestId: 123344566 Access-Control-Allow-Origin: a.b.c x-amzn-ErrorType: MissingAuthenticationTokenException header-1: static x-request-query: 1 x-request-path: 5 X-Cache: Error from cloudfront Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront) X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA== { "message":"Missing Authentication Token", "type": MISSING_AUTHENTICATION_TOKEN, "statusCode": '404', "stage": custErr, "resourcePath": /pets/{petId}, "stageVariables.a": a } ``` O exemplo anterior pressupõe que o backend da API seja [Pet Store](http://petstore-demo-endpoint.execute-api.com/petstore/pets) e que a API possua uma variável de estágio, `a`, definida. # Configurar uma resposta de gateway usando a API REST do API Gateway Antes de personalizar uma resposta de gateway usando a API REST do API Gateway, você já deve ter criado uma API e obtido seu identificador. Para recuperar o identificador da API, você pode seguir a relação do link [restapi:gateway-responses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) e examinar o resultado. **Para personalizar uma resposta de gateway usando a API REST do API Gateway** 1. Para substituir uma instância de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) inteira, chame a ação [gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html). Especifique um [responseType](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) (Tipo de resposta) desejado no parâmetro de caminho de URL e forneça na carga útil da solicitação os mapeamentos [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters) e [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseTemplates). 1. Para atualizar parte de uma instância `GatewayResponse`, chame a ação [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html). Especifique um `responseType` desejado no parâmetro de caminho de URL e forneça na carga útil da solicitação as propriedades individuais `GatewayResponse` desejadas, por exemplo, o mapeamento `responseParameters` ou `responseTemplates`. # Configurar a personalização da resposta de gateway no OpenAPI Você pode usar a extensão `x-amazon-apigateway-gateway-responses` no nível raiz de API para personalizar respostas de gateway no OpenAPI. A seguinte definição do OpenAPI mostra um exemplo para personalizar a [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) do tipo `MISSING_AUTHENTICATION_TOKEN`. ``` "x-amazon-apigateway-gateway-responses": { "MISSING_AUTHENTICATION_TOKEN": { "statusCode": 404, "responseParameters": { "gatewayresponse.header.x-request-path": "method.input.params.petId", "gatewayresponse.header.x-request-query": "method.input.params.q", "gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'", "gatewayresponse.header.x-request-header": "method.input.params.Accept" }, "responseTemplates": { "application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}" } } ``` Neste exemplo, a personalização altera o código de status do padrão (`403`) para `404`. Ela também adiciona à resposta de gateway quatro parâmetros de cabeçalho e um modelo de mapeamento de corpo para o tipo de mídia `application/json`. # Tipos de resposta de gateway do API Gateway O API Gateway expõe as seguintes respostas de gateway para personalização pelos desenvolvedores de APIs. | Tipo de resposta do Gateway | Código de status de padrão | Descrição | | --- | --- | --- | | ACCESS\$1DENIED | 403 | A resposta de gateway para uma falha de autorização; por exemplo, quando o acesso é negado por um autorizador personalizado ou do Amazon Cognito. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | API\$1CONFIGURATION\$1ERROR | 500 | A resposta do gateway para uma configuração de API inválida, incluindo quando um endereço de endpoint inválido é enviado, quando a decodificação em base64 falha nos dados binários quando o suporte binário está implementado ou quando o mapeamento da resposta de integração não pode corresponder a nenhum modelo e nenhum modelo padrão está configurado. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_5XX`. | | AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | A resposta de gateway por não conseguir se conectar a um autorizador personalizado ou do Amazon Cognito. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_5XX`. | | AUTHORIZER\$1FAILURE | 500 | A resposta de gateway quando um autorizador personalizado ou do Amazon Cognito falhou ao autenticar o autor da chamada. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_5XX`. | | BAD\$1REQUEST\$1PARAMETERS | 400 | A resposta de gateway quando o parâmetro de solicitação não pode ser validado de acordo com um validador de solicitação ativado. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | BAD\$1REQUEST\$1BODY | 400 | A resposta de gateway quando o corpo da solicitação não pode ser validado de acordo com um validador de solicitação ativado. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | DEFAULT\$14XX | Nulo | A resposta de gateway padrão para um tipo de resposta não especificado com o código de status de `4XX`. Alterar o código de status dessa resposta de gateway de retorno altera os códigos de status de todas as outras respostas `4XX` para o novo valor. Redefinir esse código de status para nulo reverte os códigos de status de todas as outras respostas `4XX` para seus valores originais. As [respostas personalizadas do AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) têm precedência sobre as respostas personalizadas do gateway. | | DEFAULT\$15XX | Nulo | A resposta de gateway padrão para um tipo de resposta não especificado com um código de status de `5XX`. Alterar o código de status dessa resposta de gateway de retorno altera os códigos de status de todas as outras respostas `5XX` para o novo valor. Redefinir esse código de status para nulo reverte os códigos de status de todas as outras respostas `5XX` para seus valores originais. | | EXPIRED\$1TOKEN | 403 | A resposta de gateway para um erro de token de autenticação do AWS expirado. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | INTEGRATION\$1FAILURE | 504 | A resposta de gateway para um erro de integração com falha. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_5XX`. | | INTEGRATION\$1TIMEOUT | 504 | A resposta de gateway para um erro de tempo limite de integração. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_5XX`. | | INVALID\$1API\$1KEY | 403 | A resposta do gateway para uma chave de API inválida enviada para um método que requer uma chave de API. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | INVALID\$1SIGNATURE | 403 | A resposta do gateway para um erro de assinatura da AWS inválido. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | MISSING\$1AUTHENTICATION\$1TOKEN | 403 | A resposta de gateway para um erro de token de autenticação ausente, incluindo casos quando o cliente tenta invocar um método de API ou recurso sem suporte. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | QUOTA\$1EXCEEDED | 429 | A resposta de gateway para o erro de cota de plano de uso excedida. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | REQUEST\$1TOO\$1LARGE | 413 | A resposta de gateway para o erro de solicitação muito grande. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão: `HTTP content length exceeded 10485760 bytes`. | | RESOURCE\$1NOT\$1FOUND | 404 | A resposta de gateway quando o API Gateway não consegue localizar o recurso especificado depois que uma solicitação de API passa na autenticação e na autorização, exceto para a autorização e a autenticação da chave de API. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | THROTTLED | 429 | A resposta de gateway quando limites de controle de fluxo em nível de plano de uso, método, estágio ou conta são excedidos. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | UNAUTHORIZED | 401 | A resposta de gateway quando o autorizador personalizado ou do Amazon Cognito falhou ao autenticar o autor da chamada. | | UNSUPPORTED\$1MEDIA\$1TYPE | 415 | A resposta de gateway quando a carga é de um tipo de mídia sem suporte, se o comportamento de passagem direta estrita estiver habilitado. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. | | WAF\$1FILTERED | 403 | A resposta de gateway quando uma solicitação é bloqueada pelo AWS WAF. Se o tipo de resposta não for especificado, essa resposta assumirá como padrão o tipo `DEFAULT_4XX`. As [respostas personalizadas do AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) têm precedência sobre as respostas personalizadas do gateway. | # CORS para APIs REST 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 entre origens que são iniciadas em scripts em execução no navegador. Consulte mais informações em [O que é CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/). ## Determinar se deseja habilitar o suporte ao CORS Uma solicitação HTTP *entre origens* é uma solicitação que é feita para: + Um *domínio* diferente (por exemplo, de `example.com` para `amazondomains.com`) + Um *subdomínio* diferente (por exemplo, de `example.com` para `petstore.example.com`) + Uma *porta* diferente (por exemplo, de `example.com` para `example.com:10777`) + Um *protocolo* diferente (por exemplo, de `https://example.com` para `http://example.com`) 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. As solicitações HTTP entre origens podem ser divididas em dois tipos: solicitações *simples* e solicitações *não simples*. ## Habilitar o CORS para uma solicitação simples Uma solicitação HTTP será *simples* se todas as condições a seguir forem verdadeiras: + Ela é emitida em relação a um recurso de API que permite apenas solicitações `POST`, `GET` e `HEAD`. + Se for uma solicitação de método `POST`, deverá incluir um cabeçalho `Origin`. + O tipo de conteúdo da carga da solicitação é `text/plain`, `multipart/form-data` ou `application/x-www-form-urlencoded`. + A solicitação não contém cabeçalhos personalizados. + Quaisquer requisitos adicionais que estão listados na [Documentação do Mozilla CORS para solicitações simples](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests). Para solicitações simples do método `POST` de origem cruzada, a resposta de seu recurso precisa incluir o cabeçalho `Access-Control-Allow-Origin: '*'` ou `Access-Control-Allow-Origin:'origin'`. Todas as outras solicitações HTTP entre origens são solicitações *não simples*. ## Habilitar o CORS para uma solicitação não simples Se os recursos de sua API receberem solicitações não simples, você deverá habilitar o suporte CORS adicional, dependendo de seu tipo de integração. ### Habilitar o CORS para integrações sem proxy Para essas integrações, o [protocolo CORS](https://fetch.spec.whatwg.org/#http-cors-protocol) exige que o navegador envie uma solicitação de simulação ao servidor e aguarde a aprovação (ou uma solicitação de credenciais) do servidor antes de enviar a solicitação real. Você deve configurar sua API para enviar uma resposta apropriada à solicitação de simulação. Como criar uma resposta de simulação: 1. Crie um método `OPTIONS` com uma integração de simulação. 1. Adicione os seguintes cabeçalhos de resposta à resposta do método 200: + `Access-Control-Allow-Headers` + `Access-Control-Allow-Methods` + `Access-Control-Allow-Origin` 1. Defina o comportamento de passagem da integração como `NEVER`. Nesse caso, a solicitação de método de um tipo de conteúdo não mapeado será rejeitada com uma resposta HTTP 415 Tipo de mídia incompatível. Para obter mais informações, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md). 1. Insira valores para os cabeçalhos de resposta. Para possibilitar todas as origens, todos os métodos e cabeçalhos comuns, use os seguintes valores de cabeçalho: + `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` + `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'` + `Access-Control-Allow-Origin: '*'` Depois de criar a solicitação de simulação, você deve retornar o cabeçalho `Access-Control-Allow-Origin: '*'` ou `Access-Control-Allow-Origin:'origin'` para todos os métodos habilitados para CORS para pelo menos todas as 200 respostas. ### Habilitar o CORS para integrações sem proxy usando o Console de gerenciamento da AWS Você pode usar o Console de gerenciamento da AWS para habilitar o CORS. O API Gateway cria um método `OPTIONS` e tenta adiciona o cabeçalho `Access-Control-Allow-Origin` às respostas de integração de métodos existentes. Isso nem sempre funciona e, às vezes, você precisa modificar manualmente a resposta de integração para retornar o cabeçalho `Access-Control-Allow-Origin` de todos os métodos habilitados para CORS para pelo menos todas as 200 respostas. Se você tiver tipos de mídia binários definidos como `*/*` para a API, quando o API Gateway criar um método `OPTIONS`, altere `contentHandling` para `CONVERT_TO_TEXT`. O comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) abaixo altera `contentHandling` para `CONVERT_TO_TEXT` em uma solicitação de integração: ``` aws apigateway update-integration \ --rest-api-id abc123 \ --resource-id aaa111 \ --http-method OPTIONS \ --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' ``` O comando [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html) abaixo altera `contentHandling` para `CONVERT_TO_TEXT` em uma resposta de integração: ``` aws apigateway update-integration-response \ --rest-api-id abc123 \ --resource-id aaa111 \ --http-method OPTIONS \ --status-code 200 \ --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' ``` ## Habilitar o suporte ao CORS para integrações de proxy Para uma integração de proxy do Lambda ou integração de proxy HTTP, seu back-end é responsável por retornar os cabeçalhos `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods` e `Access-Control-Allow-Headers`, porque uma integração de proxy não retorna uma resposta de integração. As seguintes funções de exemplo do Lambda retornam os cabeçalhos de CORS necessários: ------ #### [ Node.js ] ``` export const handler = async (event) => { const response = { statusCode: 200, headers: { "Access-Control-Allow-Headers" : "Content-Type", "Access-Control-Allow-Origin": "https://www.example.com", "Access-Control-Allow-Methods": "OPTIONS,POST,GET" }, body: JSON.stringify('Hello from Lambda!'), }; return response; }; ``` ------ #### [ Python 3 ] ``` import json def lambda_handler(event, context): return { 'statusCode': 200, 'headers': { 'Access-Control-Allow-Headers': 'Content-Type', 'Access-Control-Allow-Origin': 'https://www.example.com', 'Access-Control-Allow-Methods': 'OPTIONS,POST,GET' }, 'body': json.dumps('Hello from Lambda!') } ``` ------ **Topics** + [Determinar se deseja habilitar o suporte ao CORS](#apigateway-cors-request-types) + [Habilitar o CORS para uma solicitação simples](#apigateway-cors-simple-request) + [Habilitar o CORS para uma solicitação não simples](#apigateway-enable-cors-non-simple) + [Habilitar o suporte ao CORS para integrações de proxy](#apigateway-enable-cors-proxy) + [Ativar o CORS em um recurso usando o console do API Gateway](how-to-cors-console.md) + [Ativar o CORS em um recurso usando a API de importação do API Gateway](enable-cors-for-resource-using-swagger-importer-tool.md) + [Testar o CORS para uma API do API Gateway](apigateway-test-cors.md) # Ativar o CORS em um recurso usando o console do API Gateway Você pode usar o console do API Gateway para habilitar o suporte ao CORS para um ou todos os métodos em um recurso de API REST que você criou. Depois de habilitar o suporte ao CORS, defina o comportamento de passagem da integração como `NEVER`. Nesse caso, a solicitação de método de um tipo de conteúdo não mapeado será rejeitada com uma resposta HTTP 415 Tipo de mídia incompatível. Para obter mais informações, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md). **Importante** Os recursos podem conter recursos filho. A habilitação do suporte ao CORS para um recurso e seus métodos não o habilita recursivamente para recursos filho e seus métodos. **Para habilitar o suporte ao CORS em um recurso da API REST** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API. 1. Escolha um recurso em **Recursos**. 1. Na seção **Detalhes do recurso**, escolha **Ativar CORS**. ![\[No painel Recursos, selecione Habilitar CORS.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png) 1. Na caixa **Ativar CORS**, faça o seguinte: 1. (Opcional) Se você criou uma resposta de gateway personalizada e deseja habilitar o suporte ao CORS para uma resposta, selecione uma resposta de gateway. 1. Selecione cada método para habilitar o suporte ao CORS. O método `OPTION` deve ter o CORS habilitado. Se você habilitar o suporte ao CORS para um método `ANY`, o CORS será habilitado para todos os métodos. 1. No campo de entrada **Access-Control-Allow-Headers**, insira uma string estática de uma lista separada por vírgulas de cabeçalhos que o cliente deve enviar na solicitação real do recurso. Use a lista de cabeçalhos `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` fornecida pelo console ou especifique seus próprios cabeçalhos. 1. Use o valor `'*'` fornecido pelo console como o valor do cabeçalho **Access-Control-Allow-Origin** para permitir solicitações de acesso de todas as origens ou especifique uma origem que deve ter permissão para acessar o recurso. 1. Escolha **Salvar**. ![\[Escolher quais cabeçalhos são permitidos\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png) **Importante** Ao aplicar as instruções acima ao método `ANY` em uma integração de proxy, nenhum dos cabeçalhos CORS aplicáveis será definido. Em vez disso, o back-end deve retornar os cabeçalhos CORS aplicáveis, como `Access-Control-Allow-Origin`. Depois que o CORS for habilitado no método `GET`, um método `OPTIONS` será adicionado ao recurso se ainda não estiver lá. A resposta `200` do método `OPTIONS` é automaticamente configurada para retornar os três cabeçalhos `Access-Control-Allow-*` a fim de atender a handshakes de simulação. Além disso, o método real (`GET`) também é configurado por padrão para retornar o cabeçalho `Access-Control-Allow-Origin` em sua resposta 200. Para outros tipos de respostas, você precisará configurá-las manualmente para retornar o cabeçalho `Access-Control-Allow-Origin'` com "\$1" ou origens específicas, caso não queira retornar o erro `Cross-origin access`. Depois que você habilitar o suporte ao CORS em seu recurso, você deve implantar ou reimplantar a API para que as novas configurações entrem em vigor. Para obter mais informações, consulte [Crie um implantação do .](set-up-deployments.md#create-deployment). **nota** Se você não conseguir habilitar o suporte ao CORS em seu recurso depois de seguir o procedimento, recomendamos que você compare sua configuração de CORS com o recurso `/pets` da API de exemplo. Para saber como criar a API de exemplo, consulte [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). # Ativar o CORS em um recurso usando a API de importação do API Gateway Se você estiver usando o recurso [API Gateway Import API](api-gateway-import-api.md), poderá configurar o suporte para CORS usando um arquivo do OpenAPI. Primeiro, é necessário definir um método `OPTIONS` no seu recurso que retorne os cabeçalhos necessários. **nota** Os navegadores da Web esperam que cabeçalhos Access-Control-Allow-Headers e Access-Control-Allow-Origin sejam configurados em cada método de API que aceite solicitações CORS. Além disso, alguns navegadores primeiro fazem uma solicitação HTTP para um método `OPTIONS` no mesmo recurso e esperam receber os mesmos cabeçalhos. ## Exemplo do método `Options` O exemplo a seguir cria um método `OPTIONS` para uma integração simulada. ------ #### [ OpenAPI 3.0 ] ``` /users: options: summary: CORS support description: | Enable CORS by returning correct headers tags: - CORS responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: {} x-amazon-apigateway-integration: type: mock requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods: "'*'" method.response.header.Access-Control-Allow-Origin: "'*'" ``` ------ #### [ OpenAPI 2.0 ] ``` /users: options: summary: CORS support description: | Enable CORS by returning correct headers consumes: - "application/json" produces: - "application/json" tags: - CORS x-amazon-apigateway-integration: type: mock requestTemplates: "{\"statusCode\": 200}" passthroughBehavior: "never" responses: "default": statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods : "'*'" method.response.header.Access-Control-Allow-Origin : "'*'" responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Headers: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Origin: type: "string" ``` ------ Depois de configurar o método `OPTIONS` para o seu recurso, você poderá adicionar os cabeçalhos necessários aos outros métodos no mesmo recurso que precisam aceitar solicitações CORS. 1. Declare **Access-Control-Allow-Origin** e **Headers** para os tipos de resposta. ------ #### [ OpenAPI 3.0 ] ``` responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: {} ``` ------ #### [ OpenAPI 2.0 ] ``` responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Headers: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Origin: type: "string" ``` ------ 1. Na tag `x-amazon-apigateway-integration`, configure o mapeamento desses cabeçalhos para seus valores estáticos: ------ #### [ OpenAPI 3.0 ] ``` responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods: "'*'" method.response.header.Access-Control-Allow-Origin: "'*'" responseTemplates: application/json: | {} ``` ------ #### [ OpenAPI 2.0 ] ``` responses: "default": statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods : "'*'" method.response.header.Access-Control-Allow-Origin : "'*'" ``` ------ ## Exemplo de API O exemplo a seguir cria uma API completa com um método `OPTIONS` e um método `GET` com uma integração de `HTTP`. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "cors-api" description: "cors-api" version: "2024-01-16T18:36:01Z" servers: - url: "/{basePath}" variables: basePath: default: "/test" paths: /: get: operationId: "GetPet" responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: schema: type: "string" content: {} x-amazon-apigateway-integration: httpMethod: "GET" uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Origin: "'*'" passthroughBehavior: "never" type: "http" options: responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: application/json: schema: $ref: "#/components/schemas/Empty" x-amazon-apigateway-integration: responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'" method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Origin: "'*'" requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" type: "mock" components: schemas: Empty: type: "object" ``` ------ #### [ OpenAPI 2.0 ] ``` swagger: "2.0" info: description: "cors-api" version: "2024-01-16T18:36:01Z" title: "cors-api" basePath: "/test" schemes: - "https" paths: /: get: operationId: "GetPet" produces: - "application/json" responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: type: "string" x-amazon-apigateway-integration: httpMethod: "GET" uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Origin: "'*'" passthroughBehavior: "never" type: "http" options: consumes: - "application/json" produces: - "application/json" responses: "200": description: "200 response" schema: $ref: "#/definitions/Empty" headers: Access-Control-Allow-Origin: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Headers: type: "string" x-amazon-apigateway-integration: responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'" method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Origin: "'*'" requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" type: "mock" definitions: Empty: type: "object" ``` ------ # Testar o CORS para uma API do API Gateway É possível testar a configuração de CORS da API invocando a API e verificando os cabeçalhos de CORS na resposta. O comando `curl` a seguir envia uma solicitação OPTIONS para uma API implantada. ``` curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name} ``` ``` < HTTP/1.1 200 OK < Date: Tue, 19 May 2020 00:55:22 GMT < Content-Type: application/json < Content-Length: 0 < Connection: keep-alive < x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123 < Access-Control-Allow-Origin: * < Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token < x-amz-apigw-id: Abcd= < Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT ``` Os cabeçalhos `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers` e `Access-Control-Allow-Methods` na resposta mostram que a API oferece suporte ao CORS. Para obter mais informações, consulte [CORS para APIs REST no API Gateway](how-to-cors.md). # Tipos de mídia binários para APIs REST no API Gateway No API Gateway, a solicitação e a resposta da API têm uma carga de texto ou binária. Uma carga de texto é uma string JSON codificada por `UTF-8`. Uma carga binária é qualquer coisa além de uma carga de texto. A carga binária pode ser, por exemplo, um arquivo JPEG, um arquivo GZip ou um arquivo XML. A configuração da API necessária para oferecer suporte a mídia binária depende do fato de a API usar ou não integrações de proxy ou não proxy. Se você usa uma integração de proxy com streaming de resposta de carga útil, não precisa configurar seus tipos de mídia binária. Para obter mais informações, consulte [Transmitir a resposta para suas integrações de proxy no API Gateway](response-transfer-mode.md). ## AWS LambdaIntegrações de proxy do Para lidar com cargas binárias para integrações de proxy do AWS Lambda, é necessário codificar com base64 a resposta da sua função. Você também deve configurar os [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) para sua API. A configuração `binaryMediaTypes` da sua API é uma lista de tipos de conteúdo que sua API trata como dados binários. São exemplos de tipos de mídia binária `image/png` ou `application/octet-stream`. É possível usar o caractere curinga (`*`) para cobrir vários tipos de mídia. O API Gateway usa o primeiro cabeçalho `Accept` dos clientes para determinar se uma resposta deve retornar mídia binária. Para retornar mídia binária quando não for possível controlar a ordem dos valores de cabeçalho `Accept`, como solicitações de um navegador, defina os tipos de mídia binária da API como `*/*`. Para obter um código de exemplo, consulte [Exibir mídia binária de uma integração do proxy do Lambda no API Gateway](lambda-proxy-binary-media.md). Se você usa uma integração do proxy do Lambda com streaming de resposta de carga útil, não precisa configurar seus tipos de mídia binária. Para obter mais informações, consulte [Configurar uma integração de proxy do Lambda com streaming de resposta da carga útil no API Gateway](response-transfer-mode-lambda.md). ## Integrações sem proxy Para lidar com cargas binárias para integrações não proxy, adicione os tipos de mídia à lista [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) do recurso `RestApi`. A configuração `binaryMediaTypes` da sua API é uma lista de tipos de conteúdo que sua API trata como dados binários. Como alternativa, é possível definir as propriedades [contentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) nos recursos [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) e [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html). O valor `contentHandling` pode ser `CONVERT_TO_BINARY`, `CONVERT_TO_TEXT` ou indefinido. **nota** Em integrações `MOCK` ou privadas, não é possível usar a configuração das propriedades `contentHandling` no Console de gerenciamento da AWS. Você deve usar a AWS CLI, o CloudFormation ou um SDK para definir as propriedades `contentHandling`. Dependendo do valor de `contentHandling` e de se o cabeçalho `Content-Type` da resposta ou o cabeçalho `Accept` da solicitação de entrada corresponder ou não a uma entrada na lista `binaryMediaTypes`, o API Gateway poderá codificar os bytes binários brutos como uma string codificada em base64, decodificar uma string codificada em base64 de volta aos seus bytes brutos ou transmitir o corpo sem modificação. Você deve configurar a API da seguinte forma para dar suporte a cargas binárias para sua API no API Gateway: + Adicione os tipos de mídia binários desejados à lista `binaryMediaTypes` no recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html). Se essa propriedade e a propriedade `contentHandling` não estiverem definidas, as cargas serão tratadas como strings JSON codificadas em UTF-8. + Trate a propriedade `contentHandling` do recurso [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). + Para que a carga de solicitação seja convertida de uma string codificada em base64 em seu blob binário, defina a propriedade como `CONVERT_TO_BINARY`. + Para que a carga de solicitação seja convertida de um blob binário em uma string codificada em base64, defina a propriedade como `CONVERT_TO_TEXT`. + Para transmitir a carga sem modificação, deixe a propriedade indefinida. Para transmitir uma carga binária sem modificação, também é necessário garantir que o `Content-Type` corresponda a uma das entradas `binaryMediaTypes` e que [os comportamentos de passagem](integration-passthrough-behaviors.md) estejam habilitados para a API. + Defina a propriedade `contentHandling` do recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html). A propriedade `contentHandling`, o cabeçalho `Accept` nas solicitações do cliente e os `binaryMediaTypes` das APIs combinados determinam como o API Gateway lida com as conversões de tipo de conteúdo. Para obter mais detalhes, consulte [Conversões de tipo de conteúdo no API Gateway](api-gateway-payload-encodings-workflow.md). **Importante** Quando uma solicitação contém vários tipos de mídia em seu cabeçalho `Accept`, o API Gateway respeita apenas o primeiro tipo de mídia `Accept`. Em situações em que não é possível controlar a ordem dos tipos de mídia `Accept` e o tipo de mídia do seu conteúdo binário não é o primeiro da lista, adicione o primeiro tipo de mídia `Accept` na lista `binaryMediaTypes` da sua API. O API Gateway lida com todos os tipos de conteúdo nesta lista como binários. Por exemplo, para enviar um arquivo JPEG usando um elemento `` em um navegador, o navegador pode enviar `Accept:image/webp,image/*,*/*;q=0.8` em uma solicitação. Ao adicionar `image/webp` à lista `binaryMediaTypes`, o endpoint recebe o arquivo JPEG como binário. Para obter informações detalhadas sobre como o API Gateway lida com o texto e as cargas binárias, consulte [Conversões de tipo de conteúdo no API Gateway](api-gateway-payload-encodings-workflow.md). # Conversões de tipo de conteúdo no API Gateway A combinação dos `binaryMediaTypes` de sua API, os cabeçalhos em solicitações de clientes e a propriedade de integração `contentHandling` determinam como o API Gateway codifica as cargas. A tabela a seguir mostra como o API Gateway converte a carga útil da solicitação para configurações específicas do cabeçalho `Content-Type` de uma solicitação, a lista `binaryMediaTypes` de um recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) e o valor da propriedade `contentHandling` do recurso [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). | Carga da solicitação de método | Cabeçalho `Content-Type` da solicitação | `binaryMediaTypes` | `contentHandling` | Carga da solicitação de integração | | --- | --- | --- | --- | --- | | Dados de texto | Qualquer tipo de dados | Não definido | Não definido | String codificada em UTF8 | | Dados de texto | Qualquer tipo de dados | Não definido | CONVERT\$1TO\$1BINARY | Blob binário codificado em Base64 | | Dados de texto | Qualquer tipo de dados | Não definido | CONVERT\$1TO\$1TEXT | String codificada em UTF8 | | Dados de texto | Um tipo de dados de texto | Conjunto com tipos de mídia correspondentes | Não definido | Dados de texto | | Dados de texto | Um tipo de dados de texto | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1BINARY | Blob binário codificado em Base64 | | Dados de texto | Um tipo de dados de texto | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1TEXT | Dados de texto | | Dados binários | Um tipo de dados binários | Conjunto com tipos de mídia correspondentes | Não definido | Dados binários | | Dados binários | Um tipo de dados binários | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1BINARY | Dados binários | | Dados binários | Um tipo de dados binários | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1TEXT | String codificada em Base64 | A tabela a seguir mostra como o API Gateway converte a carga útil da resposta para configurações específicas do cabeçalho `Accept` de uma solicitação, a lista `binaryMediaTypes` de um recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) e o valor da propriedade `contentHandling` do recurso [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html). **Importante** Quando uma solicitação contém vários tipos de mídia em seu cabeçalho `Accept`, o API Gateway respeita apenas o primeiro tipo de mídia `Accept`. Em situações em que não é possível controlar a ordem dos tipos de mídia `Accept` e o tipo de mídia do seu conteúdo binário não é o primeiro da lista, adicione o primeiro tipo de mídia `Accept` na lista `binaryMediaTypes` da sua API. O API Gateway lida com todos os tipos de conteúdo nesta lista como binários. Por exemplo, para enviar um arquivo JPEG usando um elemento `` em um navegador, o navegador pode enviar `Accept:image/webp,image/*,*/*;q=0.8` em uma solicitação. Ao adicionar `image/webp` à lista `binaryMediaTypes`, o endpoint recebe o arquivo JPEG como binário. | Carga da resposta de integração | Cabeçalho `Accept` da solicitação | `binaryMediaTypes` | `contentHandling` | Mapear a carga da resposta | | --- | --- | --- | --- | --- | | Dados de texto ou binários | Um tipo de texto | Não definido | Não definido | String codificada em UTF8 | | Dados de texto ou binários | Um tipo de texto | Não definido | CONVERT\$1TO\$1BINARY | Blob codificado em Base64 | | Dados de texto ou binários | Um tipo de texto | Não definido | CONVERT\$1TO\$1TEXT | String codificada em UTF8 | | Dados de texto | Um tipo de texto | Conjunto com tipos de mídia correspondentes | Não definido | Dados de texto | | Dados de texto | Um tipo de texto | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1BINARY | Blob codificado em Base64 | | Dados de texto | Um tipo de texto | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1TEXT | String codificada em UTF8 | | Dados de texto | Um tipo binário | Conjunto com tipos de mídia correspondentes | Não definido | Blob codificado em Base64 | | Dados de texto | Um tipo binário | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1BINARY | Blob codificado em Base64 | | Dados de texto | Um tipo binário | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1TEXT | String codificada em UTF8 | | Dados binários | Um tipo de texto | Conjunto com tipos de mídia correspondentes | Não definido | String codificada em Base64 | | Dados binários | Um tipo de texto | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1BINARY | Dados binários | | Dados binários | Um tipo de texto | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1TEXT | String codificada em Base64 | | Dados binários | Um tipo binário | Conjunto com tipos de mídia correspondentes | Não definido | Dados binários | | Dados binários | Um tipo binário | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1BINARY | Dados binários | | Dados binários | Um tipo binário | Conjunto com tipos de mídia correspondentes | CONVERT\$1TO\$1TEXT | String codificada em Base64 | Ao converter uma carga de texto em um blob binário, o API Gateway pressupõe que os dados de texto sejam uma string decodificada em base64 e gera a saída dos dados binários como um blob decodificado em base64. Se a conversão falhar, ela retornará uma resposta `500`, indicando um erro de configuração da API. Você não fornece um modelo de mapeamento para tal conversão, embora deva habilitar os [comportamentos de passagem direta](integration-passthrough-behaviors.md) na API. Ao converter uma carga binária em uma string de texto, o API Gateway sempre aplica uma codificação de base64 aos dados binários. Você pode definir um modelo de mapeamento para esse tipo de carga, mas pode acessar somente a string codificada em base64 no modelo de mapeamento por meio de `$input.body`, conforme mostrado no seguinte trecho de um exemplo de modelo de mapeamento. ``` { "data": "$input.body" } ``` Para que a carga do binário seja transmitida sem modificação, você deve habilitar os [comportamentos de passagem direta](integration-passthrough-behaviors.md) na API. # Ativação do suporte binário usando o console do API Gateway Esta seção explica como habilitar o suporte a binários usando o console do API Gateway. Como exemplo, usamos uma API integrada ao Amazon S3. Nosso foco está nas tarefas para definir os tipos de mídia com suporte e especificar como a carga deve ser tratada. Para obter informações detalhadas sobre como criar uma API integrada do Amazon S3, consulte [Tutorial: Crie uma API REST como um proxy do Amazon S3](integrating-api-with-aws-services-s3.md). **Como habilitar o suporte binário usando o console do API Gateway** 1. Definir tipos de mídia binários para a API: 1. Crie uma nova API ou escolha uma API existente. Para esse exemplo, definimos o nome da API como `FileMan`. 1. Na API selecionada no painel de navegação principal, selecione **Configurações da API**. 1. No painel **Configurações da API**, selecione **Adicionar tipo de mídia binária** na seção **Tipos de mídia binária**. 1. Selecione **Adicionar tipo de mídia binária**. 1. Insira um tipo de mídia necessário, por exemplo, **image/png**, no campo de texto de entrada. Se necessário, repita esta etapa para adicionar mais tipos de mídia. Para oferecer suporte a todos os tipos de mídia binários, especifique `*/*`. 1. Escolha **Salvar alterações**. 1. Defina como as cargas de mensagem são manipuladas para o método de API: 1. Crie um novo recuso ou escolha um recurso existente na API. Para este exemplo, usamos o recurso `/{folder}/{item}`. 1. Crie um novo método ou escolha um método existente no recurso. Como exemplo, usamos o método `GET /{folder}/{item}` integrado à ação `Object GET` no Amazon S3. 1. Em **Manuseio de conteúdo**, selecione uma opção. ![\[Configure o método GET no console do API Gateway.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png) Escolha **Passthrough (Passagem)** se não desejar converter o corpo quando o cliente e o backend aceitarem o mesmo formato binário. Selecione **Converter em texto** para converter o corpo binário em uma string codificada em base64 quando, por exemplo, o back-end exigir que uma carga útil de solicitação binária seja transmitida como a propriedade JSON. E selecione **Converter em binário** quando o cliente enviar uma string codificada em base64, e o back-end exigir o formato binário original, ou quando o endpoint gerar uma string codificada em base64 e o cliente aceitar apenas a saída binária. 1. Em **Passagem do corpo da solicitação**, selecione **Quando não há modelos definidos (recomendado)** para habilitar o comportamento de passagem no corpo da solicitação. Você também pode selecionar **Nunca**. Isso significa que a API rejeitará dados com tipos de conteúdo que não tenham um modelo de mapeamento. 1. Preserve o cabeçalho `Accept` da solicitação de entrada na solicitação de integração. Você deverá fazer isso se tiver definido `contentHandling` como `passthrough` e quiser substituir essa configuração em tempo de execução. ![\[Mantenha o cabeçalho Accept na solicitação de integração.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png) 1. Para conversão em texto, defina um modelo de mapeamento para colocar os dados binários codificados em base64 no formato necessário. Veja um exemplo de modelo de mapeamento para conversão em texto: ``` { "operation": "thumbnail", "base64Image": "$input.body" } ``` O formato desse modelo de mapeamento depende das exigências de endpoint da entrada. 1. Escolha **Salvar**. # Ativação do suporte binário usando a API REST do API Gateway As tarefas a seguir mostram como habilitar o suporte binário usando chamadas de API REST do API Gateway. **Topics** + [Adicionar e atualizar tipos de mídia binária com suporte para uma API](#api-gateway-payload-encodings-setup-with-api-set-encodings-map) + [Configurar conversões de carga de solicitação](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding) + [Configurar conversões de carga de resposta](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding) + [Converter dados binários em dados de texto](#api-gateway-payload-encodings-convert-binary-to-string) + [Converter dados de texto em uma carga binária](#api-gateway-payload-encodings-convert-string-to-binary) + [Transmitir uma carga binária](#api-gateway-payload-encodings-pass-binary-as-is) ## Adicionar e atualizar tipos de mídia binária com suporte para uma API Para habilitar o API Gateway para oferecer suporte a um novo tipo de mídia binário, você deve adicionar o tipo de mídia binária à lista `binaryMediaTypes` do recurso `RestApi`. Por exemplo, para que o API Gateway lide com imagens JPEG, envie uma solicitação `PATCH` ao recurso `RestApi`: ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/image~1jpeg" } ] } ``` A especificação do tipo MIME de `image/jpeg`que faz parte do valor da propriedade `path` é escapada como `image~1jpeg`. Para atualizar os tipos de mídia binária com suporte, substitua ou remova o tipo de mídia da lista `binaryMediaTypes` do recurso `RestApi`. Por exemplo, para alterar o suporte binário de arquivos JPEG para bytes brutos, envie uma solicitação `PATCH` para o recurso `RestApi`, da seguinte forma: ``` PATCH /restapis/ { "patchOperations" : [{ "op" : "replace", "path" : "/binaryMediaTypes/image~1jpeg", "value" : "application/octet-stream" }, { "op" : "remove", "path" : "/binaryMediaTypes/image~1jpeg" }] } ``` ## Configurar conversões de carga de solicitação Se o endpoint exigir uma entrada de binário, defina a propriedade `contentHandling` do recurso `Integration` como `CONVERT_TO_BINARY`. Para fazer isso, envie uma solicitação `PATCH`, da seguinte forma: ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Configurar conversões de carga de resposta Se o cliente aceitar o resultado como um blob binário em vez de uma carga codificada em base64 retornada do endpoint, defina a propriedade `contentHandling` do recurso `IntegrationResponse` como `CONVERT_TO_BINARY`. Para fazer isso, envie uma solicitação `PATCH`, da seguinte forma: ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Converter dados binários em dados de texto Para enviar dados binários como uma propriedade JSON da entrada para o AWS Lambda ou Kinesis por meio do API Gateway, faça o seguinte: 1. Ative o suporte a cargas binárias da API adicionando o novo tipo de mídia binária de `application/octet-stream` à lista `binaryMediaTypes` da API. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. Defina `CONVERT_TO_TEXT` na propriedade `contentHandling` do recurso `Integration` e forneça um modelo de mapeamento para atribuir a string codificada em base64 dos dados binários a uma propriedade JSON. No exemplo a seguir, a propriedade JSON é `body` e `$input.body` mantém a string codificada em base64. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_TEXT" }, { "op" : "add", "path" : "/requestTemplates/application~1octet-stream", "value" : "{\"body\": \"$input.body\"}" } ] } ``` ## Converter dados de texto em uma carga binária Suponha que uma função do Lambda retorne um arquivo de imagem como uma string codificada em base64. Para transmitir essa saída binária para o cliente por meio do API Gateway, faça o seguinte: 1. Atualize a lista `binaryMediaTypes` da API adicionando o tipo de mídia binária de `application/octet-stream` se ele ainda não estiver na lista. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream", }] } ``` 1. Defina a propriedade `contentHandling` do recurso `Integration` como `CONVERT_TO_BINARY`. Não defina um modelo de mapeamento Quando você não define um modelo de mapeamento, o API Gateway chama o modelo de passagem para retornar o blob binário decodificado em base64 como o arquivo de imagem ao cliente. ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" } ] } ``` ## Transmitir uma carga binária Para armazenar uma imagem em um bucket do Amazon S3 usando o API Gateway, faça o seguinte: 1. Atualize a lista `binaryMediaTypes` da API adicionando o tipo de mídia binária de `application/octet-stream`, se ele ainda não estiver na lista. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. Na propriedade `contentHandling` do recurso `Integration`, defina `CONVERT_TO_BINARY`. Defina `WHEN_NO_MATCH` como o valor da propriedade `passthroughBehavior` sem definir um modelo de mapeamento. Isso permite que o API Gateway invoque o modelo de passagem. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }, { "op" : "replace", "path" : "/passthroughBehaviors", "value" : "WHEN_NO_MATCH" } ] } ``` # Importar e exportar codificações de conteúdo para o API Gateway Para importar a lista `binaryMediaTypes` em uma [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), use a seguinte extensão do API Gateway para o arquivo de definição do OpenAPI da API. A extensão também é usada para exportar as configurações de API. + [Propriedade x-amazon-apigateway-binary-media-types](api-gateway-swagger-extensions-binary-media-types.md) Para importar e exportar o valor da propriedade `contentHandling` em recurso `Integration` ou `IntegrationResponse`, use as seguintes extensões do API Gateway para as definições do OpenAPI: + [Objeto x-amazon-apigateway-integration](api-gateway-swagger-extensions-integration.md) + [Objeto x-amazon-apigateway-integration.response](api-gateway-swagger-extensions-integration-response.md) # Exibir mídia binária de uma integração do proxy do Lambda no API Gateway Para retornar mídia binária de uma [integração de proxy do AWS Lambda](set-up-lambda-proxy-integrations.md), codifique com base64 a resposta da sua função do Lambda. Também é necessário [configurar os tipos de mídia binária da API](api-gateway-payload-encodings-configure-with-console.md). Quando você configura os tipos de mídia binários da API, ela trata esse tipo de conteúdo como dados binários. O tamanho máximo da carga é 10 MB. **nota** Para usar um navegador da Web para invocar uma API com este exemplo de integração, defina os tipos de mídia binária da API como `*/*`. O API Gateway usa o primeiro cabeçalho `Accept` dos clientes para determinar se uma resposta deve retornar mídia binária. Para retornar mídia binária quando não for possível controlar a ordem dos valores de cabeçalho `Accept`, como solicitações de um navegador, defina os tipos de mídia binária da API como `*/*` (para todos os tipos de conteúdo). O exemplo a seguir da função do Lambda pode retornar uma imagem binária do Amazon S3 ou texto para clientes. A resposta da função inclui um cabeçalho `Content-Type` para indicar ao cliente o tipo de dados que ele retorna. A função define de modo condicional a propriedade `isBase64Encoded` em sua resposta, dependendo do tipo de dados que ela retorna. ------ #### [ Node.js ] ``` import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3" const client = new S3Client({region: 'us-east-2'}); export const handler = async (event) => { var randomint = function(max) { return Math.floor(Math.random() * max); } var number = randomint(2); if (number == 1){ const input = { "Bucket" : "bucket-name", "Key" : "image.png" } try { const command = new GetObjectCommand(input) const response = await client.send(command); var str = await response.Body.transformToByteArray(); } catch (err) { console.error(err); } const base64body = Buffer.from(str).toString('base64'); return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64body, 'isBase64Encoded': true } } else { return { 'headers': { "Content-Type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } } } ``` ------ #### [ Python ] ``` import base64 import boto3 import json import random s3 = boto3.client('s3') def lambda_handler(event, context): number = random.randint(0,1) if number == 1: response = s3.get_object( Bucket='bucket-name', Key='image.png', ) image = response['Body'].read() return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64.b64encode(image).decode('utf-8'), 'isBase64Encoded': True } else: return { 'headers': { "Content-type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } ``` ------ Para saber mais sobre tipos de mídia binária, consulte [Tipos de mídia binários para APIs REST no API Gateway](api-gateway-payload-encodings.md). # Acessar arquivos binários no Amazon S3 por meio de uma API do API Gateway Os exemplos a seguir mostram o arquivo do OpenAPI usado para acessar imagens no Amazon S3, como fazer download de uma imagem do Amazon S3 e como fazer upload de uma imagem para o Amazon S3. **Topics** + [Arquivo do OpenAPI de uma API de exemplo para acessar imagens no Amazon S3](#api-gateway-content-encodings-example-image-s3-swagger-file) + [Fazer download de uma imagem do Amazon S3](#api-gateway-content-encodings-example-download-image-from-s3) + [Carregar uma imagem para o Amazon S3](#api-gateway-content-encodings-example-upload-image-to-s3) ## Arquivo do OpenAPI de uma API de exemplo para acessar imagens no Amazon S3 O seguinte arquivo do OpenAPI demonstra uma API de amostra que ilustra o download de um arquivo de imagem do Amazon S3 e o upload de um arquivo de imagem para o Amazon S3. Essa API expõe os métodos `GET /s3?key={file-name}` e `PUT /s3?key={file-name}` para download e upload de um arquivo de imagem especificado. O método `GET` retorna o arquivo de imagem como uma string codificada em base64 como parte de uma saída JSON, seguindo o modelo de mapeamento fornecido, em uma resposta 200 OK. O método `PUT` obtém um blob binário bruto como entrada e retorna uma resposta 200 OK com uma carga útil vazia. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/s3": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling": "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/s3": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling" : "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Fazer download de uma imagem do Amazon S3 Para fazer download de um arquivo de imagem (`image.jpg`) como um blob binário do Amazon S3: ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` A resposta bem-sucedida tem a seguinte aparência: ``` 200 OK HTTP/1.1 [raw bytes] ``` Os bytes brutos são retornados porque o cabeçalho `Accept` é definido como um tipo de mídia binário de `application/octet-stream`, e o suporte binário está habilitado para a API. Como alternativa, para fazer download de um arquivo de imagem (`image.jpg`) como uma string codificada em base64 (formatada como uma propriedade JSON) no Amazon S3, adicione um modelo de resposta à resposta de integração 200, conforme mostrado no seguinte bloco de definição de OpenAPI em negrito: ``` "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } }, ``` A solicitação para fazer download do arquivo de imagem é semelhante à seguinte: ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` A resposta bem-sucedida tem a seguinte aparência: ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Carregar uma imagem para o Amazon S3 Para carregar um arquivo de imagem (`image.jpg`) como um blob binário no Amazon S3: ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` A resposta bem-sucedida tem a seguinte aparência: ``` 200 OK HTTP/1.1 ``` Para carregar um arquivo de imagem (`image.jpg`) como uma string codificada em base64 no Amazon S3: ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` A carga de entrada deve ser uma string codificada em base64, pois o valor do cabeçalho `Content-Type` está definido como `application/json`. A resposta bem-sucedida tem a seguinte aparência: ``` 200 OK HTTP/1.1 ``` # Acessar arquivos binários no Lambda usando uma API do API Gateway O exemplo de OpenAPI a seguir demonstra como acessar um arquivo binário no AWS Lambda por meio de uma API do API Gateway. Essa API expõe os métodos `GET /lambda?key={file-name}` e `PUT /lambda?key={file-name}` para download e upload de um arquivo de imagem especificado. O método `GET` retorna o arquivo de imagem como uma string codificada em base64 como parte de uma saída JSON, seguindo o modelo de mapeamento fornecido, em uma resposta 200 OK. O método `PUT` obtém um blob binário bruto como entrada e retorna uma resposta 200 OK com uma carga útil vazia. Crie a função do Lambda que é chamada pela API, e ela deve retornar uma string codificada em base64 com `application/json` como cabeçalho `Content-Type`. **Topics** + [Arquivo do OpenAPI de uma API de exemplo para acessar imagens no Lambda](#api-gateway-content-encodings-example-image-lambda-swagger-file) + [Download de uma imagem do Lambda](#api-gateway-content-encodings-example-download-image-from-lambda) + [Carregar uma imagem para o Lambda](#api-gateway-content-encodings-example-upload-image-to-lambda) ## Arquivo do OpenAPI de uma API de exemplo para acessar imagens no Lambda O seguinte arquivo do OpenAPI demonstra uma API de exemplo que ilustra o download de um arquivo de imagem do Lambda e o upload de um arquivo de imagem para o Lambda. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/lambda": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/lambda": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling" : "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Download de uma imagem do Lambda Para baixar um arquivo de imagem (`image.jpg`) como um blob binário do Lambda: ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` A resposta bem-sucedida tem a seguinte aparência: ``` 200 OK HTTP/1.1 [raw bytes] ``` Para baixar um arquivo de imagem (`image.jpg`) como uma string codificada em base64, formatada como uma propriedade JSON, do Lambda: ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` A resposta bem-sucedida tem a seguinte aparência: ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Carregar uma imagem para o Lambda Para carregar um arquivo de imagem (`image.jpg`) como um blob binário no Lambda: ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` A resposta bem-sucedida tem a seguinte aparência: ``` 200 OK ``` Para carregar um arquivo de imagem (`image.jpg`) como uma string codificada em base64 no Lambda: ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` A resposta bem-sucedida tem a seguinte aparência: ``` 200 OK ``` # Invocar APIs REST no API Gateway Para chamar uma API implantada, os clientes enviam solicitações ao URL do serviço de componente do API Gateway para execução da API, conhecido como `execute-api`. A URL base para APIs REST está no seguinte formato: ``` https://api-id.execute-api.region.amazonaws.com/stage/ ``` em que *api-id* é o identificador da API, *region* é a região da AWS e *stage* é o nome do estágio da implantação da API. **Importante** Antes de invocar uma API, você deve implantá-la no API Gateway. Para encontrar instruções sobre como implantar uma API, consulte [Implantar APIs REST no API Gateway](how-to-deploy-api.md). **Topics** + [Obter o URL de invocação de uma API](#apigateway-how-to-call-rest-api) + [Invocação de uma API](#apigateway-call-api) + [Use o console do API Gateway para testar um método de API REST](how-to-test-method.md) + [Usar um SDK Java gerado pelo API Gateway para uma API REST](how-to-call-apigateway-generated-java-sdk.md) + [Usar um SDK Android gerado pelo API Gateway para uma API REST](how-to-generate-sdk-android.md) + [Usar um SDK JavaScript gerado pelo API Gateway para uma API REST](how-to-generate-sdk-javascript.md) + [Usar um SDK Ruby gerado pelo API Gateway para uma API REST](how-to-call-sdk-ruby.md) + [Usar o SDK iOS gerado pelo API Gateway para uma API REST em Objective-C ou Swift](how-to-generate-sdk-ios.md) ## Obter o URL de invocação de uma API Você pode usar o console, a AWS CLI ou uma definição de OpenAPI exportada para obter o URL de invocação de uma API. ### Obter o URL de invocação de uma API usando o console O procedimento a seguir mostra como obter o URL de invocação de uma API no console da API REST. **Obter o URL de invocação de uma API usando o console da API REST** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API implantada. 1. No painel de navegação principal, escolha **Estágio**. 1. Em **Detalhes do estágio**, escolha o ícone de cópia para copiar o URL de invocação da API. Esse URL é para o recurso-raiz da sua API. ![\[Após a criação da API REST, o console mostra o URL de chamada da API.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png) 1. Para obter o URL de invocação de uma API para outro recurso na API, expanda o estágio no painel de navegação secundário e selecione um método. 1. Escolha o ícone de cópia para copiar o URL de invocação no nível de recurso da API. ![\[O URL no nível do recurso para a API REST está no painel de navegação secundário do estágio.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/resource-level-invoke-url.png) #### Obter o URL de invocação de uma API usando a AWS CLI O procedimento a seguir mostra como obter o URL de invocação de uma API usando a AWS CLI. **Obter o URL de invocação de uma API usando a AWS CLI** 1. Use o comando a seguir para obter `rest-api-id`. Esse comando retorna todos os valores `rest-api-id` em sua região. Para saber mais, consulte [get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html). ``` aws apigateway get-rest-apis ``` 1. Substitua o exemplo `rest-api-id` pelo seu `rest-api-id`, substitua o exemplo *\$1stage-name\$1* pelo seu *\$1stage-name\$1* e substitua a *\$1region\$1* pela sua região. ``` https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/ ``` ##### Obter o URL de invocação de uma API usando o arquivo de definição OpenAPI exportado da API Também é possível construir esse URL-raiz combinando os campos `host` e `basePath` de um arquivo de definição OpenAPI exportado da API. Para encontrar instruções sobre como exportar sua API, consulte [Exportar uma API REST do API Gateway](api-gateway-export-api.md). ## Invocação de uma API Você pode chamar sua API implantada usando o navegador, curl ou outras aplicações, como o [Postman](https://www.postman.com/). Além disso, você pode usar o console do API Gateway para testar uma chamada de API. O teste usa o recurso `TestInvoke` do API Gateway, que permite testar a API antes de implantá-la. Para ter mais informações, consulte [Use o console do API Gateway para testar um método de API REST](how-to-test-method.md). **nota** Os valores de parâmetros de strings de consulta em uma URL de invocação não podem conter `%%`. ### Invocar uma API usando um navegador da web Se sua API permitir acesso anônimo, você poderá usar qualquer navegador da web para invocar qualquer método `GET`. Insira o URL de invocação completo na barra de endereço do navegador. Para outros métodos ou chamadas que exigem autenticação, você deve especificar uma carga útil ou assinar as solicitações. É possível lidar com elas em um script por trás de uma página HTML ou em um aplicativo cliente usando um dos SDKs da AWS. #### Invocar uma API usando curl Você pode usar uma ferramenta como [curl](https://curl.se/) em seu terminal para chamar sua API. O exemplo de comando curl a seguir invoca o método GET no recurso `getUsers` do estágio `prod` de uma API. ------ #### [ Linux or Macintosh ] ``` curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers' ``` ------ #### [ Windows ] ``` curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers" ``` ------ # Use o console do API Gateway para testar um método de API REST Use o console do API Gateway para testar um método de API REST. **Topics** + [Pré-requisitos](#how-to-test-method-prerequisites) + [Testar um método com o console do API Gateway](#how-to-test-method-console) ## Pré-requisitos + Você deve especificar as configurações dos métodos que deseja testar. Siga as instruções em [Métodos para APIs REST no API Gateway](how-to-method-settings.md). ## Testar um método com o console do API Gateway **Importante** Testar métodos com o console do API Gateway pode ocasionar alterações em recursos que não podem ser desfeitas. Testar um método com o console do API Gateway é o mesmo que chamar o método fora do console do API Gateway. Por exemplo, se você usar o console do API Gateway para chamar um método que exclui os recursos de uma API, se a chamada do método for bem-sucedida, os recursos da API serão excluídos. **Como testar um método** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha uma API REST. 1. No painel **Resources (Recursos)**, escolha o método que você deseja testar. 1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia. ![\[Use a guia de teste para testar uma API. Ela está ao lado da guia de resposta do método.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-test-new-console.png) Insira os valores em qualquer das caixas exibidas (como **Strings de consulta**, **Cabeçalhos** e **Corpo da solicitação**). O console inclui esses valores na solicitação de método no formulário json/aplicativo padrão. Para ver opções adicionais que talvez você precise especificar, entre em contato com o proprietário da API. 1. Escolha **Test** (Testar). As informações a seguir serão exibidas: + **Request (Solicitação)** é o caminho do recurso que foi chamado para o método. + **Status** é o código de status HTTP da resposta. + **Latência (ms)** é o tempo entre a recepção da solicitação do chamador e a resposta retornada. + **Corpo da resposta** é o corpo de resposta HTTP. + **Cabeçalhos de resposta** são os cabeçalhos de resposta HTTP. **dica** Dependendo do mapeamento, o código de status HTTP, o corpo e os cabeçalhos de resposta podem ser diferentes dos enviados pela função do Lambda, pelo proxy HTTP ou pelo proxy de serviço da AWS. + Os **logs** são as entradas simuladas do Amazon CloudWatch Logs que teriam sido gravadas se esse método fosse chamado fora do console do API Gateway. **nota** Embora as entradas do CloudWatch Logs sejam simuladas, os resultados da chamada do método são reais. Além de usar o console do API Gateway, você pode usar a AWS CLI ou um AWS SDK para o API Gateway testar a invocação de um método. Para fazer isso usando a AWS CLI, consulte [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html). # Usar um SDK Java gerado pelo API Gateway para uma API REST Nesta seção, descreveremos as etapas para usar um SDK Java gerado pelo API Gateway para uma API REST ao utilizar a API de [Calculadora simples](simple-calc-lambda-api-swagger-definition.md) como exemplo. Antes de prosseguir, você deve concluir as etapas em [Gerar SDKs para APIs REST no API Gateway](how-to-generate-sdk.md). **Para instalar e usar um SDK Java gerado pelo API Gateway** 1. Extraia o conteúdo do arquivo .zip gerado pelo API Gateway que você baixou anteriormente. 1. Baixe e instale o [Apache Maven](https://maven.apache.org/) (deve ser a versão 3.5 ou posterior). 1. Faça download e instale o [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html). 1. Defina a variável de ambiente `JAVA_HOME`. 1. Acesse a pasta do SDK descompactada na qual o arquivo pom.xml está localizado. Essa pasta é `generated-code` por padrão. Execute o comando **mvn install** para instalar os arquivos de artefato compilados no seu repositório Maven local. Isso cria uma pasta `target`, que contém a biblioteca SDK compilada. 1. Digite o comando a seguir para criar um stub de projeto de cliente para chamar a API usando a biblioteca SDK instalada. ``` mvn -B archetype:generate \ -DarchetypeGroupdId=org.apache.maven.archetypes \ -DgroupId=examples.aws.apig.simpleCalc.sdk.app \ -DartifactId=SimpleCalc-sdkClient ``` **nota** O separador `\` no comando anterior é incluído para facilitar a leitura. O comando inteiro deve estar em uma única linha, sem separadores. Esse comando cria um stub de aplicativo. O stub do aplicativo contém um arquivo `pom.xml` e uma pasta `src` no diretório raiz do projeto (*SimpleCalc-sdkClient* no comando anterior). Inicialmente, há dois arquivos de origem: `src/main/java/{package-path}/App.java` e `src/test/java/{package-path}/AppTest.java`. Neste exemplo, *\$1package-path\$1* é `examples/aws/apig/simpleCalc/sdk/app`. Este caminho de pacote é derivado do valor `DarchetypeGroupdId`. Você pode usar o arquivo `App.java` como um modelo para o seu aplicativo cliente e pode adicionar outros na mesma pasta, se necessário. Você pode usar o arquivo `AppTest.java` como modelo de teste unitário para o seu aplicativo e pode adicionar outros arquivos de código de teste à mesma pasta de teste, conforme necessário. 1. Atualize as dependências de pacotes no arquivo `pom.xml` gerado para o seguinte, substituindo as propriedades `groupId`, `artifactId`, `version` e `name` do seu projeto, se necessário: ``` 4.0.0 examples.aws.apig.simpleCalc.sdk.app SimpleCalc-sdkClient jar 1.0-SNAPSHOT SimpleCalc-sdkClient http://maven.apache.org com.amazonaws aws-java-sdk-core 1.11.94 my-apig-api-examples simple-calc-sdk 1.0.0 junit junit 4.12 test commons-io commons-io 2.5 org.apache.maven.plugins maven-compiler-plugin 3.5.1 1.8 1.8 ``` **nota** Quando uma versão mais recente do artefato dependente de `aws-java-sdk-core` não for compatível com a versão especificada acima (`1.11.94`), você deve atualizar a tag `` para a nova versão. 1. Em seguida, mostramos como chamar a API com o uso do SDK, chamando os métodos `getABOp(GetABOpRequest req)`, `getApiRoot(GetApiRootRequest req)` e `postApiRoot(PostApiRootRequest req)` do SDK. Esses métodos correspondem aos métodos `GET /{a}/{b}/{op}`, `GET /?a={x}&b={y}&op={operator}` e `POST /`, com uma carga de solicitações da API `{"a": x, "b": y, "op": "operator"}`, respectivamente. Atualize o arquivo `App.java` da seguinte maneira: ``` package examples.aws.apig.simpleCalc.sdk.app; import java.io.IOException; import com.amazonaws.opensdk.config.ConnectionConfiguration; import com.amazonaws.opensdk.config.TimeoutConfiguration; import examples.aws.apig.simpleCalc.sdk.*; import examples.aws.apig.simpleCalc.sdk.model.*; import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*; public class App { SimpleCalcSdk sdkClient; public App() { initSdk(); } // The configuration settings are for illustration purposes and may not be a recommended best practice. private void initSdk() { sdkClient = SimpleCalcSdk.builder() .connectionConfiguration( new ConnectionConfiguration() .maxConnections(100) .connectionMaxIdleMillis(1000)) .timeoutConfiguration( new TimeoutConfiguration() .httpRequestTimeout(3000) .totalExecutionTimeout(10000) .socketTimeout(2000)) .build(); } // Calling shutdown is not necessary unless you want to exert explicit control of this resource. public void shutdown() { sdkClient.shutdown(); } // GetABOpResult getABOp(GetABOpRequest getABOpRequest) public Output getResultWithPathParameters(String x, String y, String operator) { operator = operator.equals("+") ? "add" : operator; operator = operator.equals("/") ? "div" : operator; GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator)); return abopResult.getResult().getOutput(); } public Output getResultWithQueryParameters(String a, String b, String op) { GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op)); return rootResult.getResult().getOutput(); } public Output getResultByPostInputBody(Double x, Double y, String o) { PostApiRootResult postResult = sdkClient.postApiRoot( new PostApiRootRequest().input(new Input().a(x).b(y).op(o))); return postResult.getResult().getOutput(); } public static void main( String[] args ) { System.out.println( "Simple calc" ); // to begin App calc = new App(); // call the SimpleCalc API Output res = calc.getResultWithPathParameters("1", "2", "-"); System.out.printf("GET /1/2/-: %s\n", res.getC()); // Use the type query parameter res = calc.getResultWithQueryParameters("1", "2", "+"); System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC()); // Call POST with an Input body. res = calc.getResultByPostInputBody(1.0, 2.0, "*"); System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC()); } } ``` No exemplo anterior, as definições de configuração usadas para instanciar o cliente SDK são para fins ilustrativos e não são necessariamente as melhores práticas recomendadas. Além disso, a chamada de `sdkClient.shutdown()` é opcional, especialmente se for necessário um controle preciso sobre quando liberar recursos. Mostramos os padrões essenciais para chamar uma API usando um SDK do Java. É possível estender as instruções para chamar outros métodos de API. # Usar um SDK Android gerado pelo API Gateway para uma API REST Nesta seção, descreveremos as etapas para usar um SDK Android gerado pelo API Gateway para uma API REST. Antes de avançar, você já deve ter completado as etapas em [Gerar SDKs para APIs REST no API Gateway](how-to-generate-sdk.md). **nota** O SDK gerado não é compatível com o Android 4.4 e versões anteriores. Para ter mais informações, consulte [Notas importantes do Amazon API Gateway](api-gateway-known-issues.md). **Para instalar e usar um SDK Android gerado pelo API Gateway** 1. Extraia o conteúdo do arquivo .zip gerado pelo API Gateway que você baixou anteriormente. 1. Baixe e instale o [Apache Maven](https://maven.apache.org/) (de preferência a versão 3.x). 1. Faça download e instale o [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html). 1. Defina a variável de ambiente `JAVA_HOME`. 1. Execute o comando **mvn install** para instalar os arquivos de artefato compilados no seu repositório Maven local. Isso cria uma pasta `target`, que contém a biblioteca SDK compilada. 1. Copie o arquivo do SDK (cujo nome é derivado do **ID do Artifact** e da **versão do Artifact** que você especificou ao gerar o SDK, por exemplo, `simple-calcsdk-1.0.0.jar`) da pasta `target`, juntamente com todas as outras bibliotecas da pasta `target/lib`, para a pasta `lib` do seu projeto. Se você usa o Android Studio, crie uma pasta `libs` no seu módulo de aplicativo cliente e copie o arquivo .jar necessário para essa pasta. Verifique se a seção de dependências no arquivo gradle do módulo contém o seguinte. ``` compile fileTree(include: ['*.jar'], dir: 'libs') compile fileTree(include: ['*.jar'], dir: 'app/libs') ``` Certifique-se de que nenhum arquivo .jar duplicado seja declarado. 1. Use a classe `ApiClientFactory` para inicializar o SDK gerado pelo API Gateway. Por exemplo: ``` ApiClientFactory factory = new ApiClientFactory(); // Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway. final SimpleCalcClient client = factory.build(SimpleCalcClient.class); // Invoke a method: // For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method: Result output = client.rootGet("1", "2", "+"); // where the Result class of the SDK corresponds to the Result model of the API. // // For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request, Result output = client.aBOpGet(a, b, c); // where a, b, c can be "1", "2", "add", respectively. // For the following API method: // POST / // host: ... // Content-Type: application/json // // { "a": 1, "b": 2, "op": "+" } // you can call invoke it by calling the rootPost method of the SDK as follows: Input body = new Input(); input.a=1; input.b=2; input.op="+"; Result output = client.rootPost(body); // where the Input class of the SDK corresponds to the Input model of the API. // Parse the result: // If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as String result=output.c; ``` 1. Para usar um provedor de credenciais do Amazon Cognito para autorizar chamadas para sua API, use a classe `ApiClientFactory` para transmitir um conjunto de credenciais da AWS usando o SDK gerado pelo API Gateway, como mostra o exemplo a seguir. ``` // Use CognitoCachingCredentialsProvider to provide AWS credentials // for the ApiClientFactory AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider( context, // activity context "identityPoolId", // Cognito identity pool id Regions.US_EAST_1 // region of Cognito identity pool ); ApiClientFactory factory = new ApiClientFactory() .credentialsProvider(credentialsProvider); ``` 1. Para definir uma chave de API usando o SDK gerado pelo API Gateway, use um código semelhante ao seguinte. ``` ApiClientFactory factory = new ApiClientFactory() .apiKey("YOUR_API_KEY"); ``` # Usar um SDK JavaScript gerado pelo API Gateway para uma API REST O procedimento a seguir mostra como usar um SDK JavaScript gerado pelo API Gateway. **nota** Estas instruções supõem que você já concluiu as instruções em [Gerar SDKs para APIs REST no API Gateway](how-to-generate-sdk.md). **Importante** Se a API tiver apenas métodos ANY definidos, o pacote SDK gerado não conterá um arquivo `apigClient.js`, e você precisará definir os métodos ANY por conta própria. **Para instalar, inicie e chame um SDK JavaScript gerado pelo API Gateway para uma API REST** 1. Extraia o conteúdo do arquivo .zip gerado pelo API Gateway que você baixou anteriormente. 1. Habilite o CORS (compartilhamento de recursos entre origens) para todos os métodos que o SDK gerado pelo API Gateway chamará. Para obter instruções, consulte [CORS para APIs REST no API Gateway](how-to-cors.md). 1. Na sua página da Web, inclua referências aos seguintes scripts. ``` ``` 1. No seu código, inicialize o SDK gerado pelo API Gateway usando um código semelhante ao seguinte. ``` var apigClient = apigClientFactory.newClient(); ``` Para inicializar o SDK gerado pelo API Gateway com credenciais da AWS, use um código semelhante ao seguinte. Se você usar credenciais da AWS, todas as solicitações para a API serão assinadas. ``` var apigClient = apigClientFactory.newClient({ accessKey: 'ACCESS_KEY', secretKey: 'SECRET_KEY', }); ``` Para usar uma chave de API com o SDK gerado pelo API Gateway, transmita essa chave de API como um parâmetro ao objeto `Factory`, usando um código semelhante ao seguinte. Se você usar uma chave de API, ela será especificada como parte do cabeçalho `x-api-key`, e todas as solicitações para essa API serão assinadas. Isso significa que você deve definir os cabeçalhos Accept CORS apropriados para cada solicitação. ``` var apigClient = apigClientFactory.newClient({ apiKey: 'API_KEY' }); ``` 1. Chame os métodos de API no API Gateway usando um código semelhante ao seguinte. Cada chamada retorna uma promessa com retornos de chamada de êxito e falha. ``` var params = { // This is where any modeled request parameters should be added. // The key is the parameter name, as it is defined in the API in API Gateway. param0: '', param1: '' }; var body = { // This is where you define the body of the request, }; var additionalParams = { // If there are any unmodeled query parameters or headers that must be // sent with the request, add them here. headers: { param0: '', param1: '' }, queryParams: { param0: '', param1: '' } }; apigClient.methodName(params, body, additionalParams) .then(function(result){ // Add success callback code here. }).catch( function(result){ // Add error callback code here. }); ``` Aqui, *methodName* é construído a partir do caminho de recurso da solicitação de método e do verbo HTTP. Para a API SimpleCalc, os métodos de SDK de métodos referentes aos métodos de API de ``` 1. GET /?a=...&b=...&op=... 2. POST / { "a": ..., "b": ..., "op": ...} 3. GET /{a}/{b}/{op} ``` métodos SDK correspondentes são os seguintes: ``` 1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters 2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...} 3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters ``` # Usar um SDK Ruby gerado pelo API Gateway para uma API REST O procedimento a seguir mostra como usar um SDK Ruby gerado pelo API Gateway. **nota** Estas instruções supõem que você já tenha concluído as instruções em [Gerar SDKs para APIs REST no API Gateway](how-to-generate-sdk.md). **Para instalar, instancie e chame um SDK Ruby gerado pelo API Gateway para uma API REST** 1. Descompacte o arquivo SDK Ruby baixado. A origem do SDK gerado é mostrada da seguinte forma. ![\[Descompacte o arquivo SDK Ruby obtido por download em um módulo Ruby\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png) 1. Crie um Ruby Gem a partir da origem do SDK gerado, usando os seguintes comandos shell em uma janela de terminal: ``` # change to /simplecalc-sdk directory cd simplecalc-sdk # build the generated gem gem build simplecalc-sdk.gemspec ``` Depois disso, **simplecalc-sdk-1.0.0.gem** se torna disponível. 1. Instale o gem: ``` gem install simplecalc-sdk-1.0.0.gem ``` 1. Crie um aplicativo de cliente. Instancie e inicialize o cliente de SDK Ruby no aplicativo: ``` require 'simplecalc-sdk' client = SimpleCalc::Client.new( http_wire_trace: true, retry_limit: 5, http_read_timeout: 50 ) ``` Se a API com autorização do tipo `AWS_IAM` estiver configurada, você pode incluir as credenciais da AWS do chamador, fornecendo `accessKey` e `secretKey` durante a inicialização: ``` require 'pet-sdk' client = Pet::Client.new( http_wire_trace: true, retry_limit: 5, http_read_timeout: 50, access_key_id: 'ACCESS_KEY', secret_access_key: 'SECRET_KEY' ) ``` 1. Faça chamadas de API por meio do SDK no aplicativo. **dica** Se você não estiver familiarizado com as convenções de chamada do método do SDK, você pode verificar o arquivo `client.rb` na pasta `lib` do SDK gerado. A pasta contém a documentação de cada chamada de método de API suportada. Para descobrir as operações suportadas: ``` # to show supported operations: puts client.operation_names ``` Isso resulta na seguinte tela, correspondente aos métodos de API de `GET /?a={.}&b={.}&op={.}`, `GET /{a}/{b}/{op}` e `POST /`, além de uma carga no formato `{a:"…", b:"…", op:"…"}`, respectivamente: ``` [:get_api_root, :get_ab_op, :post_api_root] ``` Para invocar o método de API de `GET /?a=1&b=2&op=+`, chame o método de SDK Ruby a seguir: ``` resp = client.get_api_root({a:"1", b:"2", op:"+"}) ``` Para invocar o método de API de `POST /` com uma carga de `{a: "1", b: "2", "op": "+"}`, chame o método de SDK Ruby a seguir: ``` resp = client.post_api_root(input: {a:"1", b:"2", op:"+"}) ``` Para invocar o método de API de `GET /1/2/+`, chame o método de SDK Ruby a seguir: ``` resp = client.get_ab_op({a:"1", b:"2", op:"+"}) ``` As chamadas bem-sucedidas do método de SDK retornam a seguinte resposta: ``` resp : { result: { input: { a: 1, b: 2, op: "+" }, output: { c: 3 } } } ``` # Usar o SDK iOS gerado pelo API Gateway para uma API REST em Objective-C ou Swift Neste tutorial, mostraremos como usar um SDK do iOS gerado pelo API Gateway para uma API REST em um aplicativo Objective-C ou Swift para chamar a API subjacente. Usaremos a [API SimpleCalc](simple-calc-lambda-api.md) como exemplo para ilustrar os tópicos a seguir: + Como instalar os componentes necessários do SDK Móvel da AWS no seu projeto Xcode + Como criar o objeto de cliente da API antes de chamar os métodos da API + Como chamar os métodos de API por meio dos métodos do SDK correspondentes no objeto de cliente da API + Como preparar uma entrada de método e analisar seu resultado usando as classes de modelo correspondentes do SDK **Topics** + [Usar o SDK do iOS (Objective-C) gerado para chamar a API](#how-to-use-sdk-ios-objc) + [Usar o SDK do iOS (Swift) gerado para chamar a API](#how-to-generate-sdk-ios-swift) ## Usar o SDK do iOS (Objective-C) gerado para chamar a API Antes de iniciar o procedimento a seguir, você deve concluir as etapas em [Gerar SDKs para APIs REST no API Gateway](how-to-generate-sdk.md) para o iOS no Objective-C e fazer download do arquivo .zip do SDK gerado. ### Instalar o SDK Móvel da AWS e um SDK do iOS gerado pelo API Gateway em um projeto Objective-C O procedimento a seguir descreve como instalar o SDK. **Para instalar e usar um SDK do iOS gerado pelo API Gateway no Objective-C** 1. Extraia o conteúdo do arquivo .zip gerado pelo API Gateway que você baixou anteriormente. Usando a [API SimpleCalc](simple-calc-lambda-api.md), você pode querer renomear a pasta do SDK descompactada para algo como **sdk\$1objc\$1simple\$1calc**. Nesta pasta do SDK, há um arquivo `README.md` file e um arquivo `Podfile`. O arquivo `README.md` contém as instruções para instalar e usar o SDK. Este tutorial fornece detalhes sobre essas instruções. A instalação utiliza o [CocoaPods](https://cocoapods.org) para importar as bibliotecas necessárias do API Gateway e outros componentes dependentes do SDK móvel da AWS. Você deve atualizar o `Podfile` para importar os SDKs para o projeto Xcode rápida do seu aplicativo. A pasta do SDK não arquivada também contém uma pasta `generated-src`, que contém o código-fonte do SDK gerado da sua API. 1. Inicie o Xcode e crie um novo projeto Objective-C do iOS. Anote o destino do projeto. Você precisará defini-lo no `Podfile`. ![\[Encontre o destino no Xcode.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png) 1. Para importar o AWS Mobile SDK for iOS no projeto Xcode usando o CocoaPods, faça o seguinte: 1. Instale o CocoaPods executando o seguinte comando em uma janela de terminal: ``` sudo gem install cocoapods pod setup ``` 1. Copie o arquivo `Podfile` da pasta do SDK extraído no mesmo diretório que contém seu arquivo de projeto Xcode. Substitua o seguinte bloco: ``` target '' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` com o nome de destino do seu projeto: ``` target 'app_objc_simple_calc' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` Se o seu projeto Xcode já contive um arquivo chamado `Podfile`, adicione a seguinte linha de código a ele: ``` pod 'AWSAPIGateway', '~> 2.4.7' ``` 1. Abra uma janela de terminal e execute o seguinte comando: ``` pod install ``` Isso instala o componente do API Gateway e outros componentes dependentes do SDK Móvel da AWS. 1. Feche o projeto Xcode e abra o arquivo `.xcworkspace` para reiniciar o Xcode. 1. Adicione todos os arquivos `.h` e `.m` do diretório `generated-src` do SDK extraído ao seu projeto Xcode. ![\[Os arquivos .h e .m estão na pasta generated-src\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png) Para importar o AWS Mobile SDK for iOS Objective-C no seu projeto, fazendo download explicitamente do SDK Móvel da AWS ou usando o [Carthage](https://github.com/Carthage/Carthage#installing-carthage), siga as instruções no arquivo *README.md*. Certifique-se de usar apenas uma dessas opções para importar o SDK Móvel da AWS. ### Chamar métodos de API usando o SDK do iOS gerado pelo API Gateway em um projeto Objective-C Quando você gerou o SDK com o prefixo de `SIMPLE_CALC` para essa [API SimpleCalc](simple-calc-lambda-api.md) com dois modelos para a entrada (`Input`) e a saída (`Result`) dos métodos, no SDK, a classe de cliente de API resultante torna-se `SIMPLE_CALCSimpleCalcClient` e as classes de dados correspondentes são `SIMPLE_CALCInput` e `SIMPLE_CALCResult`, respectivamente. As solicitações e respostas da API são mapeadas para os métodos do SDK, da seguinte maneira: + A solicitação de API de ``` GET /?a=...&b=...&op=... ``` torna-se o método SDK de ``` (AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b ``` A propriedade `AWSTask.result` é do tipo `SIMPLE_CALCResult`, se o modelo `Result` foi adicionado à resposta do método. Caso contrário, a propriedade será do tipo `NSDictionary`. + Essa solicitação de API de ``` POST / { "a": "Number", "b": "Number", "op": "String" } ``` torna-se o método SDK de ``` (AWSTask *)rootPost:(SIMPLE_CALCInput *)body ``` + A solicitação de API de ``` GET /{a}/{b}/{op} ``` torna-se o método SDK de ``` (AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op ``` O procedimento a seguir descreve como chamar os métodos de API no código-fonte do aplicativo Objective-C; por exemplo, como parte do `viewDidLoad` delegado em um arquivo `ViewController.m`. **Como chamar a API por meio do SDK do iOS gerado pelo API Gateway** 1. Importe o arquivo de cabeçalho da classe de cliente da API para tornar essa classe chamável no aplicativo: ``` #import "SIMPLE_CALCSimpleCalc.h" ``` A instrução `#import` também importa `SIMPLE_CALCInput.h` e `SIMPLE_CALCResult.h` para as duas classes de modelo. 1. Instancie a classe de cliente da API: ``` SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient]; ``` Para usar o Amazon Cognito com a API, defina a propriedade `defaultServiceConfiguration` no objeto `AWSServiceManager` padrão, conforme mostrado a seguir, antes de chamar o método `defaultClient` para criar o objeto de cliente da API (mostrado no exemplo anterior): ``` AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id]; AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds]; AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration; ``` 1. Chame o método `GET /?a=1&b=2&op=+` para realizar `1+2`: ``` [[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField1.text = [self handleApiResponse:task]; return nil; }]; ``` em que a função auxiliar `handleApiResponse:task` formata o resultado como uma string a ser exibida em um campo de texto (`_textField1`). ``` - (NSString *)handleApiResponse:(AWSTask *)task { if (task.error != nil) { return [NSString stringWithFormat: @"Error: %@", task.error.description]; } else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) { return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c]; } return nil; } ``` A exibição resultante é `1 + 2 = 3`. 1. Chame a carga `POST /` para realizar `1-2`: ``` SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init]; input.a = [NSNumber numberWithInt:1]; input.b = [NSNumber numberWithInt:2]; input.op = @"-"; [[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField2.text = [self handleApiResponse:task]; return nil; }]; ``` A exibição resultante é `1 - 2 = -1`. 1. Chame`GET /{a}/{b}/{op}` para realizar `1/2`: ``` [[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField3.text = [self handleApiResponse:task]; return nil; }]; ``` A exibição resultante é `1 div 2 = 0.5`. Aqui, `div` é usado no lugar de `/` porque a [função do Lambda simples](simple-calc-nodejs-lambda-function.md) no backend não manuseia variáveis de caminho codificadas por URL. ## Usar o SDK do iOS (Swift) gerado para chamar a API Antes de iniciar o procedimento a seguir, você deve concluir as etapas em [Gerar SDKs para APIs REST no API Gateway](how-to-generate-sdk.md) para o iOS no Swift e fazer download do arquivo .zip do SDK gerado. **Topics** + [Instalar o SDK móvel da AWS e o SDK gerado pelo API Gateway em um projeto Swift](#use-sdk-ios-swift-install-sdk) + [Chamar métodos de API por meio do SDK do iOS gerado pelo API Gateway em um projeto Swift](#use-sdk-ios-swift-call-api) ### Instalar o SDK móvel da AWS e o SDK gerado pelo API Gateway em um projeto Swift O procedimento a seguir descreve como instalar o SDK. **Para instalar e usar um SDK do iOS gerado pelo API Gateway no Swift** 1. Extraia o conteúdo do arquivo .zip gerado pelo API Gateway que você baixou anteriormente. Usando a [API SimpleCalc](simple-calc-lambda-api.md), você pode querer renomear a pasta do SDK descompactada para algo como **sdk\$1swift\$1simple\$1calc**. Nesta pasta do SDK, há um arquivo `README.md` file e um arquivo `Podfile`. O arquivo `README.md` contém as instruções para instalar e usar o SDK. Este tutorial fornece detalhes sobre essas instruções. A instalação utiliza o [CocoaPods](https://cocoapods.org) para importar os componentes necessários do SDK Móvel da AWS. Você deve atualizar o `Podfile` para importar os SDKs para o projeto Xcode rápida do seu aplicativo Swift. A pasta do SDK não arquivada também contém uma pasta `generated-src`, que contém o código-fonte do SDK gerado da sua API. 1. Inicie o Xcode e crie um novo projeto Swift do iOS. Anote o destino do projeto. Você precisará defini-lo no `Podfile`. ![\[Encontre o destino no Xcode.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png) 1. Para importar os componentes necessários do SDK Móvel da AWS no projeto Xcode usando o CocoaPods, faça o seguinte: 1. Se o CocoaPods não estiver instalado, instale-o executando o seguinte comando em uma janela de terminal: ``` sudo gem install cocoapods pod setup ``` 1. Copie o arquivo `Podfile` da pasta do SDK extraído no mesmo diretório que contém seu arquivo de projeto Xcode. Substitua o seguinte bloco: ``` target '' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` pelo nome de destino do seu projeto, conforme mostrado: ``` target 'app_swift_simple_calc' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` Se o seu projeto Xcode já contiver um `Podfile` com o destino correto, basta adicionar a seguinte linha de código ao loop `do ... end`: ``` pod 'AWSAPIGateway', '~> 2.4.7' ``` 1. Abra uma janela de terminal e execute o seguinte comando no diretório do aplicativo: ``` pod install ``` Isso instala o componente do API Gateway e quaisquer componentes dependentes do SDK Móvel da AWS no projeto do aplicativo. 1. Feche o projeto Xcode e abra o arquivo `*.xcworkspace` para reiniciar o Xcode. 1. Adicione todos os arquivos de cabeçalho do SDK (`.h`) e arquivos de código-fonte Swift (`.swift`) do diretório extraído `generated-src` para seu projeto Xcode. ![\[Os arquivos .h e .swift estão na pasta generated-src\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png) 1. Para permitir a chamada de bibliotecas Objective-C do SDK Móvel da AWS a partir do seu projeto de código Swift, defina o caminho do arquivo `Bridging_Header.h` na propriedade **Objective-C Bridging Header (Cabeçalho ponte Objective-C)**, na definição **Swift Compiler - General (Compilador Swift - Geral)** da configuração do projeto Xcode: ![\[Defina o caminho do arquivo Bridging_header.h na configuração Swift Compiler - General.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png) **dica** Você pode digitar **bridging** na caixa de pesquisa do Xcode para localizar a propriedade **Objective-C Bridging Header (Cabeçalho ponte Objective-C)**. 1. Construa o projeto Xcode para verificar se ele está corretamente configurado antes de prosseguir. Se o seu Xcode usar uma versão mais recente do Swift do que a versão com suporte para o SDK Móvel da AWS, você receberá erros do compilador Swift. Nesse caso, defina a propriedade **Use Legacy Swift Language Version (Usar versão de linguagem do Swift legado)** para **Yes (Sim)**, na configuração **Swift Compiler - Version (Compilador Swift - Versão)**: ![\[Defina a propriedade Legacy Swift Language Version como Yes.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png) Para importar o AWS Mobile SDK for iOS em Swift no seu projeto fazendo download explicitamente do AWS Mobile SDK ou usando o [Carthage](https://github.com/Carthage/Carthage#installing-carthage), siga as instruções no arquivo `README.md` que acompanha o pacote do SDK. Certifique-se de usar apenas uma dessas opções para importar o SDK Móvel da AWS. ### Chamar métodos de API por meio do SDK do iOS gerado pelo API Gateway em um projeto Swift Quando você gerou o SDK com o prefixo de `SIMPLE_CALC` para essa [API SimpleCalc](simple-calc-lambda-api.md) com dois modelos para descrever a entrada (`Input`) e a saída (`Result`) das solicitações e respostas da API, no SDK, a classe de cliente de API resultante torna-se `SIMPLE_CALCSimpleCalcClient` e as classes de dados correspondentes são `SIMPLE_CALCInput` e `SIMPLE_CALCResult`, respectivamente. As solicitações e respostas da API são mapeadas para os métodos do SDK, da seguinte maneira: + A solicitação de API de ``` GET /?a=...&b=...&op=... ``` torna-se o método SDK de ``` public func rootGet(op: String?, a: String?, b: String?) -> AWSTask ``` A propriedade `AWSTask.result` é do tipo `SIMPLE_CALCResult`, se o modelo `Result` foi adicionado à resposta do método. Caso contrário, ela será do tipo `NSDictionary`. + Essa solicitação de API de ``` POST / { "a": "Number", "b": "Number", "op": "String" } ``` torna-se o método SDK de ``` public func rootPost(body: SIMPLE_CALCInput) -> AWSTask ``` + A solicitação de API de ``` GET /{a}/{b}/{op} ``` torna-se o método SDK de ``` public func aBOpGet(a: String, b: String, op: String) -> AWSTask ``` O procedimento a seguir descreve como chamar os métodos de API no código-fonte do aplicativo Swift; por exemplo, como parte do `viewDidLoad()` delegado em um arquivo `ViewController.m`. **Como chamar a API por meio do SDK do iOS gerado pelo API Gateway** 1. Instancie a classe de cliente da API: ``` let client = SIMPLE_CALCSimpleCalcClient.default() ``` Para usar o Amazon Cognito com a API, defina uma configuração de serviço da AWS padrão (mostrada a seguir) antes de obter o método `default` (mostrado anteriormente): ``` let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id") let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider) AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration ``` 1. Chame o método `GET /?a=1&b=2&op=+` para realizar `1+2`: ``` client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` em que a função auxiliar `self.showResult(task)` imprime o resultado ou o erro no console; por exemplo: ``` func showResult(task: AWSTask) { if let error = task.error { print("Error: \(error)") } else if let result = task.result { if result is SIMPLE_CALCResult { let res = result as! SIMPLE_CALCResult print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!)) } else if result is NSDictionary { let res = result as! NSDictionary print("NSDictionary: \(res)") } } } ``` Em um aplicativo de produção, você pode exibir o resultado ou erro em um campo de texto. A exibição resultante é `1 + 2 = 3`. 1. Chame a carga `POST /` para realizar `1-2`: ``` let body = SIMPLE_CALCInput() body.a=1 body.b=2 body.op="-" client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` A exibição resultante é `1 - 2 = -1`. 1. Chame`GET /{a}/{b}/{op}` para realizar `1/2`: ``` client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` A exibição resultante é `1 div 2 = 0.5`. Aqui, `div` é usado no lugar de `/` porque a [função do Lambda simples](simple-calc-nodejs-lambda-function.md) no backend não manuseia variáveis de caminho codificadas por URL. # Desenvolver APIs REST usando OpenAPI no API Gateway Você pode usar o API Gateway para importar uma API REST de um arquivo de definição externo para o API Gateway. No momento, o API Gateway é compatível com arquivos de definição [v2.0 da OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) e [v3.0 da OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md), com exceções listadas em [Notas importantes do Amazon API Gateway para APIs REST](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis). É possível atualizar uma API substituindo-a por uma nova definição ou mesclar uma definição com uma API existente. As opções são especificadas usando um parâmetro de consulta `mode` no URL solicitado. Para obter um tutorial sobre o uso do recurso de importação de API no console do API Gateway, consulte [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). **Topics** + [Importar uma API otimizada para bordas para o API Gateway](import-edge-optimized-api.md) + [Importar uma API regional para o API Gateway](import-export-api-endpoints.md) + [Importar um arquivo do OpenAPI para atualizar uma definição de API existente](api-gateway-import-api-update.md) + [Defina a propriedade `basePath` OpenAPI](api-gateway-import-api-basePath.md) + [Variáveis da AWS para importação de OpenAPI](import-api-aws-variables.md) + [Erros e avisos ao importar a API para o API Gateway](api-gateway-import-api-errors-warnings.md) + [Exportar uma API REST do API Gateway](api-gateway-export-api.md) # Importar uma API otimizada para bordas para o API Gateway Você pode importar um arquivo de definição do OpenAPI de uma API para criar uma nova API otimizada para fronteiras especificando o tipo de endpoint `EDGE` como uma entrada adicional, além do arquivo do OpenAPI, para a operação de importação. É possível fazer isso usando o console do API Gateway, a AWS CLI ou um AWS SDK. Para obter um tutorial sobre o uso do recurso de importação de API no console do API Gateway, consulte [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). **Topics** + [Importar uma API otimizada para bordas usando o console do API Gateway](#import-edge-optimized-api-with-console) + [Importar uma API otimizada para bordas usando a AWS CLI](#import-edge-optimized-api-with-awscli) ## Importar uma API otimizada para bordas usando o console do API Gateway Para importar uma API otimizada para bordas usando o console do API Gateway, faça o seguinte: 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 **Create API** (Criar API). 1. Em **REST API** (API REST), escolha **Import** (Importar). 1. Copie uma definição do OpenAPI da API e cole-a no editor de código ou selecione **Escolher arquivo** para carregar um arquivo do OpenAPI de uma unidade local. 1. Em **Tipo de endpoint da API**, escolha **Otimizado para borda**. 1. Escolha **Criar API** para começar a importar as definições do OpenAPI. ## Importar uma API otimizada para bordas usando a AWS CLI O comando [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) indicado abaixo importa uma API do arquivo de definição do OpenAPI para criar uma API otimizada para borda: ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` ou com uma especificação explícita do parâmetro de string de consulta `endpointConfigurationTypes` para `EDGE`: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importar uma API regional para o API Gateway Ao importar uma API, você pode escolher a configuração de endpoint regional para a API. É possível usar o console do API Gateway, a AWS CLI ou um AWS SDK. Ao exportar uma API, a configuração de endpoint da API não está incluído nas definições da API exportada. Para obter um tutorial sobre o uso do recurso de importação de API no console do API Gateway, consulte [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md). **Topics** + [Importar uma API regional usando o console do API Gateway](#import-regional-api-with-console) + [Importar uma API regional usando a AWS CLI](#import-regional-api-with-awscli) ## Importar uma API regional usando o console do API Gateway Para importar uma API de um endpoint regional usando o console do API Gateway, faça o seguinte: 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 **Create API** (Criar API). 1. Em **REST API** (API REST), escolha **Import** (Importar). 1. Copie uma definição do OpenAPI da API e cole-a no editor de código ou selecione **Escolher arquivo** para carregar um arquivo do OpenAPI de uma unidade local. 1. Em **Tipo de endpoint da API**, escolha **Regional**. 1. Escolha **Criar API** para começar a importar as definições do OpenAPI. ## Importar uma API regional usando a AWS CLI O comando [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) indicado abaixo importa um arquivo de definição OpenAPI e define o tipo de endpoint como regional: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importar um arquivo do OpenAPI para atualizar uma definição de API existente Você pode importar as definições de APIs apenas para atualizar uma API existente, sem alterar sua configuração de endpoint, bem como os estágios e suas variáveis ou referências a chaves de APIs. A operação de importação para atualização pode ocorrer em dois modos: mesclagem ou substituição. Quando uma API (`A`) é mesclada com outra (`B`), a API resultante retém as definições de `A` e `B`, se as duas APIs não compartilharem definições conflitantes. Em caso de conflito, as definições de método da API de mesclagem (`A`) substituem as definições de método correspondentes da API mesclada (`B`). Por exemplo, suponha que `B` tenha declarado os seguintes métodos para retornar as respostas `200` e `206`: ``` GET /a POST /a ``` e que `A` declare o seguinte método para retornar as respostas `200` e `400`: ``` GET /a ``` Quando `A` é mesclada com `B`, a API resultante produz os seguintes métodos: ``` GET /a ``` que retorna `200` e `400` respostas e ``` POST /a ``` que retorna `200` e `206` respostas. A mesclagem de uma API é útil quando você decompôs suas definições de API externas em várias partes menores e apenas deseja aplicar as alterações de uma dessas partes de cada vez. Por exemplo, isso pode ocorrer se várias equipes são responsáveis por diferentes partes de uma API e têm alterações disponíveis em ritmos diferentes. Nesse modo, os itens da API existente que não estiverem especificamente indicados na definição importada serão ignorados. Quando uma API (`A`) substitui outra API (`B`), a API resultante assume as definições da API de substituição (`A`). A substituição de uma API é útil quando uma definição de API externa contém a definição completa de uma API. Nesse modo, os itens de uma API existente que não estiverem especificamente indicados na definição importada serão excluídos. Para mesclar uma API, envie uma solicitação `PUT` para `https://apigateway..amazonaws.com/restapis/?mode=merge`. O valor do parâmetro do caminho `restapi_id` especifica a API com a qual a definição de API fornecida será mesclada. O seguinte trecho de código mostra um exemplo da solicitação `PUT` para mesclar uma definição de API do OpenAPI em JSON, como a carga útil, com a API especificada já no API Gateway. ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` A operação de atualização se mesclagem usa duas definições de API completas e as mescla em uma só. Para uma alteração pequena e incremental, você pode usar a operação de [atualização de recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Para substituir uma API, envie uma solicitação `PUT` para `https://apigateway..amazonaws.com/restapis/?mode=overwrite`. O parâmetro de caminho `restapi_id` especifica a API que será substituída pelas definições de API fornecidas. O seguinte trecho de código mostra um exemplo de uma solicitação de substituição com a carga de uma definição do OpenAPI formatada em JSON: ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Quando o parâmetro de consulta `mode` não é especificado, supõe-se uma mesclagem. **nota** As operações `PUT` são idempotentes, mas não atômicas. Isso significa que, se um erro de sistema ocorrer no meio do processamento, a API poderá terminar em mau estado. No entanto, repetir a operação com êxito coloca a API no mesmo estado final, como se a primeira operação tivesse sido bem-sucedida. # Defina a propriedade `basePath` OpenAPI No [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md), você pode usar a propriedade `basePath` para fornecer uma ou mais partes de caminhos que precedem cada caminho definido na propriedade `paths`. Como o API Gateway tem várias maneiras de expressar um caminho de um recurso, o recurso Import API (Importar API) fornece as seguintes opções para interpretar a propriedade `basePath` durante uma importação: ignorar, preceder e dividir. No [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/), `basePath` não é mais uma propriedade de nível superior. Em vez disso, o API Gateway usa uma [variável de servidor](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) como convenção. O recurso Import API (Importar API) fornece as mesmas opções para interpretar o caminho base durante a importação. O caminho base é identificado da seguinte forma: + Se a API não contém variáveis `basePath`, o recurso Import API (Importar API) verifica a string `server.url` para conferir se ela contém um caminho além de `"/"`. Se sim, esse caminho será usado como caminho base. + Se a API contém apenas uma variável `basePath`, o recurso Import API (Importar API) a usa como caminho base, mesmo que ela não seja indicada no `server.url`. + Se a API contém várias variáveis `basePath`, o recurso Import API (Importar API) usa apenas a primeira como caminho base. ## Ignorar Se o arquivo do OpenAPI tiver um valor `basePath` de `/a/b/c`, e a propriedade `paths` contiver `/e` e `/f`, a seguinte solicitação `POST` ou `PUT`: ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` resultará nos seguintes recursos na API: + `/` + `/e` + `/f` O efeito é tratar `basePath` como se ele não estivesse presente, e todos os recursos da API declarados são atendidos em relação ao host. Isso pode ser usado, por exemplo, quando você tem um nome de domínio personalizado com um mapeamento de API que não inclui um *caminho base* e um valor de *estágio* que faz referência ao seu estágio de produção. **nota** O API Gateway cria automaticamente um recurso raiz para você, mesmo que ele não esteja explicitamente declarado no seu arquivo de definição. Quando não especificado, o `basePath` pega `ignore` por padrão. ## Preceder Se o arquivo do OpenAPI tiver um valor `basePath` de `/a/b/c` e a propriedade `paths` contiver `/e` e `/f`, a seguinte solicitação `POST` ou `PUT`: ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` resultará nos seguintes recursos na API: + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` O efeito é tratar `basePath` como se recursos adicionais estivessem sendo especificados (sem métodos) e adicioná-los ao conjunto de recursos declarados. Isso pode ser usado, por exemplo, quando diferentes equipes são responsáveis por diferentes partes de uma API e o `basePath` pode fazer referência ao local do caminho para a parte da API de cada equipe. **nota** O API Gateway cria recursos intermediários automaticamente para você, mesmo que eles não estejam explicitamente declarados na sua definição. ## Split Se o arquivo do OpenAPI tiver um valor `basePath` de `/a/b/c` e a propriedade `paths` contiver `/e` e `/f`, a seguinte solicitação `POST` ou `PUT`: ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` resultará nos seguintes recursos na API: + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` O efeito é tratar a parte do caminho mais no início, `/a`, como o início do caminho de cada recurso e criar recursos adicionais (sem método) na própria API. Isso pode ser usado, por exemplo, quando `a` é um nome de estágio que deseja expor como parte da sua API. # Variáveis da AWS para importação de OpenAPI Você pode usar as seguintes variáveis da AWS nas definições do OpenAPI. O API Gateway resolve as variáveis quando a API é importada. Para especificar uma variável, use `${variable-name}`. A tabela a seguir descreve as estatísticas da AWS disponíveis. | Nome da variável | Descrição | | --- | --- | | AWS::AccountId | O ID da conta AWS que importa a API. Por exemplo, 123456789012. | | AWS::Partition | A partição da AWS na qual a API é importada. Para regiões padrão da AWS a partição é aws. | | AWS::Region | A região da AWS na qual a API é importada. Por exemplo, us-east-2. | ## Exemplo de variáveis da AWS O exemplo a seguir usa variáveis da AWS para especificar uma função do AWS Lambda para uma integração. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # Erros e avisos ao importar a API para o API Gateway Ao importar o arquivo de definição externo para o API Gateway, ele pode gerar avisos e erros. As seções a seguir explicam os erros e os avisos que podem ocorrer durante a importação. ## Erros durante a importação Durante a importação, erros podem ser gerados para problemas importantes, como um documento inválido do OpenAPI. Os erros são retornados como exceções (por exemplo, `BadRequestException`) em uma resposta mal-sucedida. Quando ocorre um erro, a nova definição da API é descartada, e nenhuma alteração é feita na API existente. ## Avisos durante a importação Durante a importação, avisos podem ser gerados para problemas menores, como uma referência de modelo ausente. Se um aviso ocorrer, a operação continuará se a expressão de consulta `failonwarnings=false` for acrescentada à URL da solicitação. Caso contrário, as atualizações serão revertidas. Por padrão, `failonwarnings` é definido como `false`. Nesses casos, os avisos são retornados como um campo no recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resultante. Caso contrário, os avisos serão retornados como uma mensagem na exceção. # Exportar uma API REST do API Gateway Depois de criar e configurar uma API REST no API Gateway, usando o console do API Gateway ou de outra forma, você pode exportá-la para um arquivo OpenAPI usando a API de exportação do API Gateway, que faz parte do Amazon API Gateway Control Service. Para usar a API de exportação do API Gateway, você precisa assinar suas solicitações de API. Para ter mais informações sobre como assinar solicitações, consulte [Assinar solicitações de API](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) no *Guia do usuário do IAM*. Existem opções para incluir as extensões de integração do API Gateway, bem como as extensões do [Postman](https://www.postman.com), no arquivo de definição do OpenAPI exportado. **nota** Ao exportar a API usando a AWS CLI, inclua o parâmetro de extensões, conforme mostrado no exemplo a seguir, para garantir que a extensão `x-amazon-apigateway-request-validator` seja incluída: ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` Não será possível exportar uma API se suas cargas não forem do tipo `application/json`. Se você tentar, receberá uma resposta de erro indicando que os modelos de corpo JSON não foram encontrados. ## Solicitar a exportação de uma API REST Com o recurso Export API, você exporta uma API REST existente ao enviar uma solicitação GET, especificando a API a ser exportada como parte de caminhos de URL. A URL da solicitação tem o seguinte formato: ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ Você pode acrescentar a string de consulta `extensions` para especificar se deseja incluir extensões do API Gateway (com o valor `integration`) ou extensões do Postman (com o valor `postman`). Além disso, é possível definir o cabeçalho `Accept` como `application/json` ou `application/yaml` para receber a saída da definição de API no formato JSON ou YAML, respectivamente. Para obter mais informações sobre como enviar solicitações GET usando a API Export do API Gateway, consulte [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html). **nota** Se você definir modelos na sua API, eles deverão ser destinados ao tipo de conteúdo “application/json” para que o API Gateway exporte o modelo. Caso contrário, o API Gateway lançará uma exceção com a mensagem de erro de que apenas modelos de corpo não JSON foram encontrados. Os modelos devem conter propriedades ou serem definidos como um determinado tipo de JSONSchema. ## Fazer download da definição da API REST do OpenAPI em JSON Para exportar e fazer download de uma API REST em definições do OpenAPI no formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ Aqui, `` poderia ser, por exemplo, `us-east-1`. Para conhecer todas as regiões onde o API Gateway está disponível, consulte [Regiões e endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region). ## Fazer download da definição da API REST do OpenAPI em YAML Para exportar e fazer download de uma API REST em definições do OpenAPI no formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Fazer download da definição da API REST do OpenAPI com extensões Postman em JSON Para exportar e fazer download de uma API REST em definições do OpenAPI com Postman no formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## Fazer download da definição da API REST do OpenAPI com integração ao API Gateway em YAML Para exportar e fazer download de uma API REST em definições do OpenAPI com integração ao API Gateway no formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Exportar API REST usando o console do API Gateway Depois de [implantar sua API REST em um estágio](set-up-deployments.md#create-deployment), você pode prosseguir e exportar essa API no estágio para um arquivo do OpenAPI usando o console do API Gateway. No painel **Estágios** no console do API Gateway, escolha **Estágios**, **Exportar**. ![\[Exportar API REST usando o console do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/export-new-console.png) Especifique **Tipo de especificação da API**, **Formato** e **Extensões** para baixar a definição do OpenAPI da sua API.