# Tipos de mídia binários para APIs REST no API Gateway
<a name="api-gateway-payload-encodings"></a>

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
<a name="api-gateway-payload-encodings-proxy"></a>

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
<a name="api-gateway-payload-encodings-non-proxy"></a>

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 `<img>` 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).