Ativação do suporte binário usando a API REST do API Gateway

As tarefas a seguir mostram como habilitar o suporte binário usando chamadas de API REST do API Gateway.

Adicionar e atualizar tipos de mídia binária com suporte para uma API

Para habilitar o API Gateway para oferecer suporte a um novo tipo de mídia binário, você deve adicionar o tipo de mídia binária à lista binaryMediaTypes do recurso RestApi. Por exemplo, para que o API Gateway lide com imagens JPEG, envie uma solicitação PATCH ao recurso RestApi:

PATCH /restapis/<restapi_id>

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/binaryMediaTypes/image~1jpeg"
  } 
 ]
}

A especificação do tipo MIME de image/jpegque faz parte do valor da propriedade path é escapada como image~1jpeg.

Para atualizar os tipos de mídia binária com suporte, substitua ou remova o tipo de mídia da lista binaryMediaTypes do recurso RestApi. Por exemplo, para alterar o suporte binário de arquivos JPEG para bytes brutos, envie uma solicitação PATCH para o recurso RestApi, da seguinte forma:

PATCH /restapis/<restapi_id>

{
  "patchOperations" : [{
    "op" : "replace",
    "path" : "/binaryMediaTypes/image~1jpeg",
    "value" : "application/octet-stream"
  },
  {
    "op" : "remove",
    "path" : "/binaryMediaTypes/image~1jpeg"
  }]
}

Configurar conversões de carga de solicitação

Se o endpoint exigir uma entrada de binário, defina a propriedade contentHandling do recurso Integration como CONVERT_TO_BINARY. Para fazer isso, envie uma solicitação PATCH, da seguinte forma:

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration

{
  "patchOperations" : [ {
    "op" : "replace",
    "path" : "/contentHandling",
    "value" : "CONVERT_TO_BINARY"
  }]
}

Configurar conversões de carga de resposta

Se o cliente aceitar o resultado como um blob binário em vez de uma carga codificada em base64 retornada do endpoint, defina a propriedade contentHandling do recurso IntegrationResponse como CONVERT_TO_BINARY. Para fazer isso, envie uma solicitação PATCH, da seguinte forma:

PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code>

{
  "patchOperations" : [ {
    "op" : "replace",
    "path" : "/contentHandling",
    "value" : "CONVERT_TO_BINARY"
  }]
}

Converter dados binários em dados de texto

Para enviar dados binários como uma propriedade JSON da entrada para o AWS Lambda ou Kinesis por meio do API Gateway, faça o seguinte:

1. Ative o suporte a cargas binárias da API adicionando o novo tipo de mídia binária de application/octet-stream à lista binaryMediaTypes da API.

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream"
     } 
    ]
   }
   

2. Defina CONVERT_TO_TEXT na propriedade contentHandling do recurso Integration e forneça um modelo de mapeamento para atribuir a string codificada em base64 dos dados binários a uma propriedade JSON. No exemplo a seguir, a propriedade JSON é body e $input.body mantém a string codificada em base64.

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_TEXT"
       },
       {
         "op" : "add",
         "path" : "/requestTemplates/application~1octet-stream",
         "value" : "{\"body\": \"$input.body\"}"
       }
     ]
   }

Converter dados de texto em uma carga binária

Suponha que uma função do Lambda retorne um arquivo de imagem como uma string codificada em base64. Para transmitir essa saída binária para o cliente por meio do API Gateway, faça o seguinte:

1. Atualize a lista binaryMediaTypes da API adicionando o tipo de mídia binária de application/octet-stream se ele ainda não estiver na lista.

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream",
     }]
   }
   

2. Defina a propriedade contentHandling do recurso Integration como CONVERT_TO_BINARY. Não defina um modelo de mapeamento Quando você não define um modelo de mapeamento, o API Gateway chama o modelo de passagem para retornar o blob binário decodificado em base64 como o arquivo de imagem ao cliente.

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration/responses/<status_code>
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_BINARY"
       }
     ]
   }

Transmitir uma carga binária

Para armazenar uma imagem em um bucket do Amazon S3 usando o API Gateway, faça o seguinte:

1. Atualize a lista binaryMediaTypes da API adicionando o tipo de mídia binária de application/octet-stream, se ele ainda não estiver na lista.

   PATCH /restapis/<restapi_id>
   
   {
     "patchOperations" : [ {
       "op" : "add",
       "path" : "/binaryMediaTypes/application~1octet-stream"
     }
    ]
   }
   

2. Na propriedade contentHandling do recurso Integration, defina CONVERT_TO_BINARY. Defina WHEN_NO_MATCH como o valor da propriedade passthroughBehavior sem definir um modelo de mapeamento. Isso permite que o API Gateway invoque o modelo de passagem.

   PATCH /restapis/<restapi_id>/resources/<resource_id>/methods/<http_method>/integration
   
   {
     "patchOperations" : [
       {
         "op" : "replace",
         "path" : "/contentHandling",
         "value" : "CONVERT_TO_BINARY"
       },
       {
         "op" : "replace",
         "path" : "/passthroughBehaviors",
         "value" : "WHEN_NO_MATCH"
       }
     ]
   }