# 使用 API Gateway REST API 启用二进制支持
<a name="api-gateway-payload-encodings-configure-with-control-service-api"></a>

以下任务演示如何使用 API Gateway REST API 调用来启用二进制支持。

**Topics**
+ [向 API 添加和更新受支持的二进制媒体类型](#api-gateway-payload-encodings-setup-with-api-set-encodings-map)
+ [配置请求负载转换](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding)
+ [配置响应负载转换](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding)
+ [将二进制数据转换为文本数据](#api-gateway-payload-encodings-convert-binary-to-string)
+ [将文本数据转换为二进制负载](#api-gateway-payload-encodings-convert-string-to-binary)
+ [传递二进制负载](#api-gateway-payload-encodings-pass-binary-as-is)

## 向 API 添加和更新受支持的二进制媒体类型
<a name="api-gateway-payload-encodings-setup-with-api-set-encodings-map"></a>

要允许 API Gateway 支持新的二进制媒体类型，必须将该二进制媒体类型添加到 `binaryMediaTypes` 资源的 `RestApi` 列表中。例如，要让 API Gateway 处理 JPEG 图像，应向 `PATCH` 资源提交 `RestApi` 请求：

```
PATCH /restapis/<restapi_id>

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

属于 `image/jpeg` 属性值一部分的 MIME 类型规范 `path` 将转义为 `image~1jpeg`。

要更新受支持的二进制媒体类型，请替换或删除 `binaryMediaTypes` 资源的 `RestApi` 列表中的该媒体类型。例如，要将二进制支持从 JPEG 文件更改为原始字节，请向 `PATCH` 资源提交 `RestApi` 请求，如下所示：

```
PATCH /restapis/<restapi_id>

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

## 配置请求负载转换
<a name="api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding"></a>

如果端点需要二进制输入，则将 `contentHandling` 资源的 `Integration` 属性设置为 `CONVERT_TO_BINARY`。为此，请提交 `PATCH` 请求，如下所示：

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

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

## 配置响应负载转换
<a name="api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding"></a>

如果客户端接受二进制 blob 形式的结果而不是从端点返回的 Base64 编码的负载，则将 `IntegrationResponse` 资源的 `contentHandling` 属性设置为 `CONVERT_TO_BINARY`。为此，请提交 `PATCH` 请求，如下所示：

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

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

## 将二进制数据转换为文本数据
<a name="api-gateway-payload-encodings-convert-binary-to-string"></a>

要通过 API Gateway 将二进制数据作为输入的 JSON 属性发送到 Amazon Lambda 或 Kinesis，请执行以下操作：

1. 通过将新的二进制媒体类型 `application/octet-stream` 添加到 API 的 `binaryMediaTypes` 列表，启用 API 的二进制负载支持。

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

1. 在 `CONVERT_TO_TEXT` 资源的 `contentHandling` 属性上设置 `Integration`，并提供映射模板以将二进制数据的 Base64 编码字符串分配给 JSON 属性。在以下示例中，JSON 属性为 `body`，并且 `$input.body` 保存 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\"}"
       }
     ]
   }
   ```

## 将文本数据转换为二进制负载
<a name="api-gateway-payload-encodings-convert-string-to-binary"></a>

假设 Lambda 函数返回一个 Base64 编码字符串形式的图像文件。要通过 API Gateway 将此二进制输出传递到客户端，请执行以下操作：

1. 通过添加二进制媒体类型 `binaryMediaTypes` (如果该类型尚不在列表中) 来更新 API 的 `application/octet-stream` 列表。

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

1.  将 `contentHandling` 资源的 `Integration` 属性设置为 `CONVERT_TO_BINARY`。请勿定义映射模板。如果不定义映射模板，API Gateway 会调用传递模板，以将 Base64 解码的二进制 blob 作为图像文件返回给客户端。

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

## 传递二进制负载
<a name="api-gateway-payload-encodings-pass-binary-as-is"></a>

 要使用 API Gateway 将图像存储在 Amazon S3 存储桶中，请执行以下操作：

1. 通过添加二进制媒体类型 `binaryMediaTypes`（如果该类型尚不在列表中）来更新 API 的 `application/octet-stream` 列表。

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

1. 在 `contentHandling` 资源的 `Integration` 属性上，设置 `CONVERT_TO_BINARY`。将 `WHEN_NO_MATCH` 设置为 `passthroughBehavior` 属性值，而不定义映射模板。这使 API Gateway 能够调用传递模板。

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