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 e o valor da propriedade contentHandling
do recurso Integration.
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_TO_BINARY |
Blob binário codificado em Base64 |
Dados de texto | Qualquer tipo de dados | Não definido | CONVERT_TO_TEXT |
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_TO_BINARY |
Blob binário codificado em Base64 |
Dados de texto | Um tipo de dados de texto | Conjunto com tipos de mídia correspondentes | CONVERT_TO_TEXT |
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_TO_BINARY |
Dados binários |
Dados binários | Um tipo de dados binários | Conjunto com tipos de mídia correspondentes | CONVERT_TO_TEXT |
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 e o valor da propriedade contentHandling
do recurso IntegrationResponse.
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.
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_TO_BINARY |
Blob codificado em Base64 |
Dados de texto ou binários | Um tipo de texto | Não definido | CONVERT_TO_TEXT |
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_TO_BINARY |
Blob codificado em Base64 |
Dados de texto | Um tipo de texto | Conjunto com tipos de mídia correspondentes | CONVERT_TO_TEXT |
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_TO_BINARY |
Blob codificado em Base64 |
Dados de texto | Um tipo binário | Conjunto com tipos de mídia correspondentes | CONVERT_TO_TEXT |
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_TO_BINARY |
Dados binários |
Dados binários | Um tipo de texto | Conjunto com tipos de mídia correspondentes | CONVERT_TO_TEXT |
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_TO_BINARY |
Dados binários |
Dados binários | Um tipo binário | Conjunto com tipos de mídia correspondentes | CONVERT_TO_TEXT |
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 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 na API.