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.

Conversões de tipo de conteúdo de solicitação de API no API Gateway
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.

Conversões de tipo de conteúdo de resposta do API Gateway
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.