# Compressão de carga útil para APIs REST no API Gateway O API Gateway permite que o cliente chame uma API com cargas compactadas usando uma das [codificações de conteúdo compatíveis](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). Por padrão, o API Gateway oferece suporte à descompactação da carga de solicitação do método. No entanto, você deve configurar sua API para habilitar a compactação da carga de resposta do método. Para habilitar a compactação em uma [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), defina a propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize) como um inteiro não negativo entre 0 e 10485760 (10 milhões de bytes) ao criar a API ou depois de criá-la. Para desabilitar a compactação na API, defina `minimumCompressionSize` como nulo ou remova-o por completo. É possível habilitar ou desabilitar a compactação de uma API usando o console do API Gateway, a AWS CLI ou a API REST do API Gateway. Se você deseja que a compactação seja aplicada em cargas de qualquer tamanho, defina o valor de `minimumCompressionSize` como zero. No entanto, a compactação de dados de um volume pequeno pode, na verdade, aumentar o volume final dos dados. Além disso, a compactação no API Gateway e a descompactação no cliente podem aumentar a latência geral e exigir mais tempo de computação. Você deve executar casos de teste com a sua API para determinar um valor ideal. O cliente pode enviar uma solicitação de API com uma carga compactada e um cabeçalho `Content-Encoding` apropriado para que o API Gateway descompacte e aplique os modelos de mapeamento adequados, antes de passar a solicitação para o endpoint de integração. Depois que a compactação for habilitada e a API for implantada, o cliente poderá receber uma resposta da API com uma carga compactada se ela especificar um cabeçalho `Accept-Encoding` apropriado na solicitação do método. Quando o endpoint de integração espera e retorna cargas JSON não compactadas, qualquer modelo de mapeamento que esteja configurado para uma carga JSON não compactada será aplicável para a carga compactada. Para uma carga de solicitação de método compactada, o API Gateway descompacta a carga, aplica o modelo de mapeamento e passa a solicitação mapeada para o endpoint de integração. Para uma carga de resposta de integração não compactada, o API Gateway aplica o modelo de mapeamento, compacta a carga mapeada e retorna a carga compactada para o cliente. **Topics** + [Habilitar a compactação de payload para uma API no API Gateway](api-gateway-enable-compression.md) + [Chamar um método de API com uma payload compactada no API Gateway](api-gateway-make-request-with-compressed-payload.md) + [Receber uma resposta da API com uma payload compactada no API Gateway](api-gateway-receive-response-with-compressed-payload.md) # Habilitar a compactação de payload para uma API no API Gateway É possível habilitar a compactação para uma API usando o console do API Gateway, a AWS CLI ou um SDK da AWS. Para uma API existente, implante a API depois de habilitar a compactação, para que a alteração entre em vigor. Para uma nova API, você pode implantar a API depois que a configuração da API for concluída. **nota** A codificação de conteúdo com a prioridade mais alta deve ser aquela compatível com o API Gateway. Se não for, a compactação não será aplicada à carga da resposta. **Topics** + [Habilitar a compactação de carga para uma API usando o console do API Gateway](#api-gateway-enable-compression-console) + [Habilitar a compactação de carga útil para uma API usando a AWS CLI](#api-gateway-enable-compression-cli) + [Codificação de conteúdo compatível com o API Gateway](#api-gateway-supported-content-encodings) ## Habilitar a compactação de carga para uma API usando o console do API Gateway O procedimento a seguir descreve como habilitar a compactação de carga para uma API. **Como habilitar a compactação de carga 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 existente ou crie uma nova. 1. No painel de navegação principal, selecione **Configurações da API**. 1. Na seção **Detalhes da API**, escolha **Editar**. 1. Ative a **Codificação de conteúdo** para habilitar a compactação da carga útil. Em **Tamanho mínimo do corpo**, insira um número para o tamanho da compactação (em bytes). Para desativar a compactação, desative a opção **Codificação de conteúdo**. 1. Escolha **Salvar alterações**. ## Habilitar a compactação de carga útil para uma API usando a AWS CLI O comando [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) indicado abaixo cria uma API com compactação de carga útil: ``` aws apigateway create-rest-api \ --name "My test API" \ --minimum-compression-size 0 ``` O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo habilita a compactação de carga útil para uma API existente: ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value=0 ``` A propriedade `minimumCompressionSize` tem um valor inteiro não negativo entre 0 e 10485760 (10 milhões de bytes). Ela mede o limite de compactação. Se o tamanho da carga útil é menor do que esse valor, a compactação ou descompactação não são aplicadas na carga. Ao configurar para zero, a compactação pode ser definida para qualquer tamanho da carga útil. O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo desativa a compactação de carga útil: ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value= ``` Você também pode definir `value` como uma string vazia `""` ou omitir a propriedade `value` completamente na chamada anterior. ## Codificação de conteúdo compatível com o API Gateway O API Gateway é compatível com as seguintes codificações de conteúdo: + `deflate` + `gzip` + `identity` O API Gateway também é compatível com o formato de cabeçalho `Accept-Encoding` a seguir, de acordo com a especificação [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4): + `Accept-Encoding:deflate,gzip` + `Accept-Encoding:` + `Accept-Encoding:*` + `Accept-Encoding:deflate;q=0.5,gzip;q=1.0` + `Accept-Encoding:gzip;q=1.0,identity;q=0.5,*;q=0` # Chamar um método de API com uma payload compactada no API Gateway Para fazer uma solicitação da API com uma carga compactada, o cliente deve definir o cabeçalho `Content-Encoding` com uma das [codificações de conteúdo compatíveis](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). Suponha que você seja um cliente de API e queira chamar o método de API PetStore (`POST /pets`). Não chame o método usando esta saída JSON: ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Length: ... { "type": "dog", "price": 249.99 } ``` Em vez disso, você pode chamar o método com a mesma carga compactada usando a codificação GZIP: ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Encoding:gzip Content-Length: ... ���RPP*�,HU�RPJ�OW��e&���L,�,-y�j ``` Quando o API Gateway recebe a solicitação, ele verifica se a codificação de conteúdo especificada é compatível. Em seguida, ele tenta descompactar a carga com a codificação de conteúdo especificada. Se a descompactação for bem-sucedida, ele enviará a solicitação para o endpoint de integração. Se a codificação especificada não for compatível ou a carga fornecida não estiver compactada, o API Gateway retornará uma resposta com o erro `415 Unsupported Media Type`. O erro não será registrado em log no CloudWatch Logs se ele ocorrer na fase inicial de descompactação antes de sua API e etapa serem identificadas. # Receber uma resposta da API com uma payload compactada no API Gateway Ao fazer uma solicitação em uma API habilitada para compactação, o cliente pode optar por receber uma carga de resposta compactada de um determinado formato especificando um cabeçalho `Accept-Encoding` com uma [codificação de conteúdo compatível](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). O API Gateway só compacta a carga de resposta quando as seguintes condições são atendidas: + A solicitação de entrada tem o cabeçalho `Accept-Encoding` com uma codificação e formato de conteúdo compatíveis. **nota** Se o cabeçalho não estiver configurado, o valor padrão será `*` conforme definido na [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4). Nesse caso, o API Gateway não compacta a carga. Algum navegador ou cliente pode adicionar `Accept-Encoding` (por exemplo, `Accept-Encoding:gzip, deflate, br`) automaticamente para solicitações habilitadas para compactação. Isso pode ativar a compactação de carga útil no API Gateway. Sem uma especificação explícita dos valores de cabeçalho `Accept-Encoding` compatíveis, o API Gateway não compacta a carga. + A definição de `minimumCompressionSize` na API habilita a compactação. + A resposta de integração não tem um cabeçalho `Content-Encoding`. + O tamanho da carga da resposta de integração, após a aplicação do modelo de mapeamento adequado, é maior ou igual ao valor especificado em `minimumCompressionSize`. O API Gateway aplica qualquer modelo de mapeamento que estiver configurado para a resposta de integração antes de compactar a carga. Se a resposta de integração contiver um cabeçalho `Content-Encoding`, para o API Gateway, a carga da resposta de integração já estará compactada, e o processamento de compactação será ignorado. Como exemplo, veja a API PetStore e a seguinte solicitação: ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept: application/json ``` O backend responde à solicitação com uma carga JSON não compactada que é semelhante à seguinte: ``` 200 OK [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Para receber essa saída como uma carga compactada, o cliente da API pode enviar uma solicitação como esta: ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept-Encoding:gzip ``` O cliente recebe a resposta com um cabeçalho `Content-Encoding` e a carga codificada por GZIP semelhante a esta: ``` 200 OK Content-Encoding:gzip ... ���RP� J�)JV �:P^IeA*������+(�L �X�YZ�ku0L0B7!9��C#�&����Y��a���^�X ``` Quando a carga de resposta é compactada, a cobrança pela transferência de dados leva em conta apenas o tamanho dos dados compactados.