# Habilitar la compatibilidad con datos binarios mediante la API Gateway REST API
<a name="api-gateway-payload-encodings-configure-with-control-service-api"></a>

Las siguientes tareas muestran cómo habilitar la compatibilidad con datos binarios mediante llamadas a la API REST de API Gateway.

**Topics**
+ [Añadir y actualizar tipos de medios binarios compatibles en una API](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [Configurar las conversiones de carga de solicitud](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [Configurar conversiones de carga de respuesta](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [Convertir datos binarios en datos de texto](#api-gateway-payload-encodings-convert-binary-to-string)
+ [Convertir datos de texto en una carga binaria](#api-gateway-payload-encodings-convert-string-to-binary)
+ [Transferir una carga binaria](#api-gateway-payload-encodings-pass-binary-as-is)

## Añadir y actualizar tipos de medios binarios compatibles en una API
<a name="api-gateway-payload-encodings-setup-with-api-set-encodings-map"></a>

Para habilitar API Gateway para que admita un nuevo tipo de medios binarios, debe agregar el tipo de medios binarios a la lista `binaryMediaTypes` del recurso `RestApi`. Por ejemplo, para que API Gateway admita imágenes JPEG, envíe una solicitud `PATCH` al recurso `RestApi`: 

```
PATCH /restapis/<restapi_id>

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

La especificación del tipo MIME de `image/jpeg` que forma parte del valor de la propiedad `path` se ha incluido en una secuencia de escape: `image~1jpeg`.

Para actualizar los tipos de medios binarios compatibles, sustituya o elimine el tipo de medios en la lista `binaryMediaTypes` del recurso `RestApi`. Por ejemplo, para cambiar la compatibilidad binaria de archivos JPEG a bytes sin formato, envíe una solicitud `PATCH` al recurso `RestApi`, tal y como se indica a continuación: 

```
PATCH /restapis/<restapi_id>

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

## Configurar las conversiones de carga de solicitud
<a name="api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding"></a>

Si el punto de conexión requiere una entrada binaria, establezca la propiedad `contentHandling` del recurso `Integration` en `CONVERT_TO_BINARY`. Para ello, envíe una solicitud `PATCH` de la siguiente manera: 

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

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

## Configurar conversiones de carga de respuesta
<a name="api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding"></a>

Si el cliente acepta el resultado como un blob binario en lugar de una carga codificada en base64 devuelta por el punto de conexión, establezca la propiedad `contentHandling` del recurso `IntegrationResponse` en `CONVERT_TO_BINARY`. Para ello, envíe una solicitud `PATCH`, de la siguiente manera:

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

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

## Convertir datos binarios en datos de texto
<a name="api-gateway-payload-encodings-convert-binary-to-string"></a>

Para enviar datos binarios como una propiedad JSON de la entrada a AWS Lambda o Kinesis a través de API Gateway, haga lo siguiente: 

1. Habilite la compatibilidad de carga binaria de la API añadiendo el nuevo tipo de medios binarios de `application/octet-stream` a la lista `binaryMediaTypes` de la API. 

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

1. Establezca `CONVERT_TO_TEXT` en la propiedad `contentHandling` del recurso `Integration` y proporcione una plantilla de asignación para asignar la cadena codificada en base64 de los datos binarios a una propiedad JSON. En el siguiente ejemplo, la propiedad JSON es `body` y `$input.body` contiene la cadena codificada en 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\"}"
       }
     ]
   }
   ```

## Convertir datos de texto en una carga binaria
<a name="api-gateway-payload-encodings-convert-string-to-binary"></a>

Supongamos que tiene una función de Lambda que devuelve un archivo de imagen como una cadena codificada en base64. Para pasar esta salida binaria al cliente a través de API Gateway, haga lo siguiente: 

1. Actualice la lista `binaryMediaTypes` de la API añadiendo el tipo de medios binarios de `application/octet-stream`, si aún no está en la lista. 

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

1.  Establezca la propiedad `contentHandling` del recurso `Integration` en `CONVERT_TO_BINARY`. No defina una plantilla de asignación. Si no define una plantilla de mapeo, API Gateway llama a la plantilla de paso a través para devolver el blob binario descodificado en base64 como el archivo de imagen al cliente. 

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

## Transferir una carga binaria
<a name="api-gateway-payload-encodings-pass-binary-as-is"></a>

 Para almacenar una imagen en un bucket de Amazon S3 utilizando API Gateway, haga lo siguiente: 

1. Actualice la lista `binaryMediaTypes` de la API añadiendo el tipo de medios binarios de `application/octet-stream`, si aún no está en la lista. 

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

1. En la propiedad `contentHandling` del recurso `Integration`, establezca `CONVERT_TO_BINARY`. Establezca `WHEN_NO_MATCH` como el valor de la propiedad `passthroughBehavior` sin definir una plantilla de asignación. Esto permite a API Gateway invocar la plantilla de acceso directo. 

   ```
   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"
       }
     ]
   }
   ```