Trabalhar com tipos de mídia binária para APIs REST

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.

Integrações de proxy do AWS Lambda

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 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. Por exemplo, */* inclui todos os tipos de conteúdo.

Para ver um código demonstrativo, consulte Retornar mídia binária de uma integração de proxy do Lambda.

Integrações sem proxy

Para lidar com cargas binárias para integrações não proxy, adicione os tipos de mídia à lista 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 nos recursos Integration e IntegrationResponse. O valor contentHandling pode ser CONVERT_TO_BINARY, CONVERT_TO_TEXT ou indefinido.

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. 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.

  • 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 estejam habilitados para a API.

• Defina a propriedade contentHandling do recurso IntegrationResponse. 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.

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.